Chat sandbox

The chat sandbox gives the assistant a private Linux environment to run code, edit files, and produce downloadable artifacts during a conversation. When you ask the assistant to execute a script, analyze a dataset, or generate a report, it works inside this environment and shares the results with you directly in the chat.

Once an administrator enables the sandbox, it starts automatically on the first request that needs it. You do not need to launch a separate environment or select it for each conversation.

What you can do with the sandbox

The sandbox supports a broad range of tasks:

• Run code and shell commands: Execute Python, Node.js, Go, or shell scripts. Install additional packages with pip, npm, or apt as needed.
• Analyze data and create visualizations: Upload a CSV or spreadsheet and ask the assistant to summarize it, compute statistics, or generate charts.
• Generate documents: Produce reports, presentations (PPTX), Word documents (DOCX), spreadsheets, or any file format the assistant can build with available tools.
• Transform files: Resize images, convert between formats, extract text from PDFs, or process uploaded files in other ways.
• Develop and iterate: Write code across multiple turns, fix errors, rebuild, and refine output without starting over. State accumulates throughout the conversation.

How the sandbox works

Each conversation gets its own isolated environment. The environment is a full Linux system with common development tools, a writable file system, and restricted internet access. Here is how it behaves:

• Starts automatically: The environment provisions itself the first time the assistant runs a command or creates a file. There is no setup step and no button to select. The first command in a conversation may take a few extra seconds while the environment starts.
• Persists across the conversation: Files created by one command are available to the next. Packages you install stay installed. The assistant can build up work incrementally over multiple turns.
• Resets between conversations: A new conversation always starts with a clean environment. Nothing carries over from previous conversations: no files, no installed packages, no saved state.
• Has restricted internet access: The environment reaches the internet through an outbound proxy restricted to approved package registries and source hosts (such as PyPI, npm, Go, Maven, Ubuntu apt, and GitHub). The assistant can install packages and clone repositories, but cannot reach arbitrary URLs -- which limits the risk of data leaving the sandbox.
• Is fully isolated: The environment cannot access your tailnet, other conversations, or any Aperture internal systems. Code runs in a contained space with no access to anything outside it.

Working with files

The sandbox organizes files into three areas with distinct roles:

Files you upload

When you attach a file to a message, the assistant can read it inside the environment. Uploaded files are read-only from the assistant's perspective. If the assistant needs to modify an uploaded file, it copies the file to its working space first, then works on the copy.

Working space

The assistant uses a private working directory for intermediate tasks such as installing dependencies, writing draft scripts, running builds. This space is not visible to you directly. It is the assistant's scratchpad. It is not preserved when the sandbox is idle-terminated. Only your uploaded files and shared output files persist.

Output files

When the assistant finishes a deliverable, it places the file in an output directory and shares it with you. Shared files appear as file cards in the chat. You can preview supported file types inline or download any file.

File preview support

When the assistant shares a file, the chat interface renders it based on its type. Some file types display inline, while others are available as downloads.

Source files such as .jsx, .tsx, and .mermaid are shown as syntax-highlighted text. The chat interface does not execute React components or render Mermaid diagrams.

Limits

The following limits apply to the sandbox:

The 5 GiB cap covers the combined uploads and outputs in a single conversation. When a conversation reaches it, the assistant returns the error This conversation's attached files exceed the sandbox capacity (5 GiB combined). Archive or remove some files and try again. Because the cap applies to the conversation as a whole, removing individual files does not reliably free space within that conversation. Start a new conversation to continue working.

Known limitations

The sandbox has the following limitations to be aware of:

• No state between conversations: Each conversation starts with a fresh environment. The assistant cannot access files or packages from a previous conversation. If you need to continue work, upload the relevant files to a new conversation.
• Large command output is truncated: Commands that produce more than 1 MiB of output are truncated. The assistant can work around this by redirecting output to a file and inspecting specific sections.
• HTML previews are restricted: Previewed HTML files cannot load external scripts or stylesheets, use localStorage or sessionStorage, or access browser APIs that require a full origin. Interactive web applications that depend on these features will not work in the preview.
• No GPU access: The environment does not have GPU hardware. Tasks that require GPU acceleration, such as training large machine learning models, are not supported.

Related

• Enable the chat sandbox for step-by-step setup instructions.
• Sandbox reference for tool parameters, size limits, timeouts, and error messages.
• Manage sandbox operations for monitoring and other operational tasks.
• Troubleshoot sandbox issues for diagnosing common problems.