Sandbox reference

The Aperture chat sandbox gives the AI assistant an isolated Linux VM for each conversation. The assistant uses five tools to run commands, read files, create files, edit files, and share output files with users. The VM persists across tool calls within a conversation and has restricted, allowlisted internet access.

This topic documents tool parameters, file system layout, size limits, supported file types, and error messages. For a conceptual overview of the sandbox feature, refer to the chat sandbox feature guide. For troubleshooting sandbox issues, refer to troubleshoot sandbox issues. For operational tasks such as monitoring, refer to manage sandbox operations.

Tools

The sandbox exposes five tools to the AI assistant. Tool names appear in the chat interface when the assistant invokes them.

bash

Execute a shell command in the sandbox VM.

The working directory is /home/aperture. The default timeout is 10 minutes. If timeout is provided and greater than zero, it overrides the default. The bash tool applies the supplied value without an upper-bound clamp, but the enclosing assistant turn is itself bounded at 10 minutes. A per-call timeout greater than 600 seconds therefore does not extend execution beyond the turn deadline, so the effective maximum is 10 minutes.

Output format:

• Exit code 0 with output: The raw command output
• Exit code 0 with no output: Exit code: 0 (no output)
• Non-zero exit code: Exit code: {code} followed by the output

Command output is truncated at 1 MiB (1,048,576 bytes) with a notice appended if exceeded. Output that exceeds this cap can be redirected to a file and read in sections with view.

view

View text files, images, and directory listings in the sandbox VM.

The timeout is 30 seconds. Output is truncated at 16,000 bytes with a notice appended if exceeded.

Behavior varies by target:

• Directory: Lists files up to 2 levels deep, ignoring hidden items and node_modules/, capped at 200 entries.
• Image file (.jpg, .jpeg, .png, .gif, .webp, .svg, .bmp, .ico): Returns metadata in the format [Image: {filename}, {size} bytes]. The view tool describes images by name and size rather than rendering them, so its image set differs from the chat preview: it does not include .avif, and it treats .svg as an image rather than a separate script-safe kind.
• Text file: Displays numbered lines. If view_range is provided, only the specified line range is shown. start_line is clamped to a minimum of 1. If end_line is -1, the view extends to the end of the file.

create_file

Create a new file with content in the sandbox VM.

The timeout is 30 seconds. Parent directories are created automatically. On success, returns Created {path} ({n} bytes) where n is the byte length of file_text.

str_replace

Replace a unique string in a file.

The timeout is 30 seconds. The old_str value must match the raw file content exactly and appear exactly once. If the string is not found, the tool returns an error. If it appears more than once, the tool returns an error indicating how many times it was found. On success, returns Replaced in {path}.

present_files

Make files visible to the user for viewing and downloading in the chat interface.

The timeout is 30 seconds for the entire call. A maximum of 20 paths can be presented per call. Each path must be an absolute path under /mnt/workspace/outputs/ with no .. segments.

The tool does not execute commands in the sandbox. Instead, it checks each file's existence and metadata, then returns a JSON result with download URLs for each file. The chat interface renders these as downloadable file attachments.

File system layout

The sandbox VM uses three directories:

/home/aperture/              # Working directory (assistant's scratch space)
/mnt/workspace/
    uploads/                 # User-uploaded files (read-only)
    outputs/                 # Output files (downloadable by user)

/home/aperture/ is the default working directory for all tool commands. The assistant uses this for intermediate work such as scripts, temporary data, and build artifacts. Files in this directory are not visible to users, and they are not preserved when the sandbox is idle-terminated -- only uploaded files and presented output files persist across an idle cycle.

/mnt/workspace/uploads/ contains files that users attach to the conversation. This directory is read-only in the sandbox. To modify an uploaded file, the assistant must copy it to /home/aperture/ first.

/mnt/workspace/outputs/ is where the assistant places final deliverables. Only files in this directory can be presented to users through present_files and downloaded through the chat interface. The present_files tool only accepts paths under this directory.

Size limits and quotas

The conversation storage limit is the combined size of all uploaded files and output files for a single conversation. When this limit is exceeded, all sandbox tool calls (bash, view, create_file, str_replace) fail with an error until files are removed. Starting a new conversation resets the storage.

Supported file types for preview

When the assistant presents output files, the chat interface renders them according to their file type:

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.

HTML files are served with a restrictive Content-Security-Policy that prevents loading external resources. Inline scripts and styles are permitted, but the page runs in a sandboxed iframe with an opaque origin. This means HTML output files cannot fetch data from external URLs or load external scripts. Because the iframe omits allow-same-origin, the page runs with a null origin and cannot read or write localStorage or sessionStorage, or reach the parent page's cookies, storage, or DOM.

Error messages

The following table lists user-visible error messages that may appear in the chat interface or as tool results:

These errors appear as tool results in the chat. In most cases the assistant handles them automatically by retrying or adjusting its approach. If the assistant cannot resolve an error, it explains the issue in its response.

For admin-facing errors (HTTP status codes from the download endpoint, sandbox connectivity issues), refer to troubleshoot sandbox issues.

Configuration

The sandbox is available wherever the chat UI is, which is on by default. To remove access, set enable_chat_ui to false in a grant:

Tailscale provisions and manages the underlying sandbox infrastructure for your instance.

For step-by-step instructions on enabling the sandbox, refer to the chat sandbox setup topic.