Sandbox

The sandbox lets your agent read, write, and run code in a secure, isolated environment. When you chat with an agent that has Sandbox enabled, it can create files, run terminal commands, search codebases, and produce downloadable artifacts — all in a cloud VM private to your conversation.

Getting started

Sandbox is available when your agent has the Sandbox tool configured and uses a model suited to coding. You do not turn it on manually — the model uses the sandbox when your request needs it.

You can also request sandbox tools explicitly when using an agentless assistant: toggle Sandbox in the chat input area.

What the AI can do

With the sandbox active, the model can:

• Read files — View file contents with line numbers, or read specific line ranges.
• Write files — Create new files or overwrite existing ones.
• Edit files — Find and replace text, or apply multi-file patches.
• Delete files — Remove files or entire directories.
• List directories — Browse the file tree.
• Run commands — Execute any terminal command (e.g., npm install, node app.js, python script.py).
• Search — Grep for patterns across files, or fuzzy-search filenames.
• Download files — Generate a download link for any file or directory from the sandbox.

Seeing tool activity

While the model runs tools, each call appears in the chat:

• A collapsible row per operation with the tool name (for example, "Read", "Executing", "Write") and arguments.
• A spinner while the operation runs.
• On success, expandable output (file contents, command output, and so on).
• On error, a red warning icon and message.

Uploading files

Files you upload go into the sandbox at ./user-uploads/ when the sandbox is first created. The model can read from that path.

If you add files after the sandbox exists, they are synced one at a time.

App builder

App Builder is a dedicated flow for building full apps:

• Layout: chat (left) and preview (right).
• The model creates or resumes a sandbox and shows a live preview of the running app.
• Tabs: Preview, Code (embedded editor), and Database (for SQLite apps).
• When the conversation completes, changes can be committed and pushed to GitHub.

Which GitHub, deploy, and publish actions you can perform—not just what you can preview—depends on your organization’s plan and entitlements. For what App Builder does, plus paywalls, Business plan naming, and gated areas such as Branding, Policies, and Deploy approvals, see App Builder.

Timeouts and long-running commands

• Most file operations (read, write, delete, list) use a 60-second timeout. If the sandbox stops responding, the model gets an error and can retry or tell you.
• Shell commands default to 3 minutes; the model can raise the limit up to 30 minutes for long jobs such as builds or tests.
• Timed-out commands are stopped; the model decides the next step.

Sandbox persistence

The sandbox lasts for the chat session. If you close the browser and return, the model can resume the same environment — files and installed dependencies remain.

Each chat has its own sandbox; other chats cannot access its files.

Using the sandbox via API

Integrations can request sandbox tools on chat API calls.

Requesting sandbox tools

Option 1: Agent configuration — If the agent has a Sandbox tool in its settings, sandbox tools are included automatically.

Option 2: Explicit request — For agentless chats, add sandbox to the tools array:

{
  "prompt": "Create a Node.js hello world app",
  "tools": [
    { "type": "sandbox" }
  ]
}

Streaming events

When the model uses sandbox tools, the SSE stream can include:

• tool.call — Fired when a sandbox tool runs; includes the tool name and arguments.
• tool.message — Fired when a tool call finishes; includes status (success or error) and output.

Standard chat events (message.created, message.delta, message.complete) still apply.

Tool names

Tool	Description
sandbox_read_file	Read file contents (supports line ranges)
sandbox_write_file	Create or overwrite a file
sandbox_delete_file	Delete a file or directory
sandbox_list_directory	List directory contents
sandbox_run_command	Execute a shell command
sandbox_grep_files	Regex search across files
sandbox_find_files	Fuzzy filename search
sandbox_apply_patch	Apply a multi-file patch
sandbox_find_replace	Find and replace in a file
sandbox_download_url	Generate a download URL for a sandbox file

Sandbox state in responses

The chat object includes sandbox IDs when present:

{
  "id": "chat_abc123",
  "sandboxId": "csb_xyz",
  "browserSandboxId": "csb_browser_xyz"
}

Error handling

Sandbox errors surface as tool.message events with status: "error". Typical cases:

• Timeout — Filesystem ops after 60 seconds; commands after 3 minutes by default.
• File not found — The path is not in the sandbox.
• Command failure — Non-zero exit code from the shell.

The model receives these errors and usually chooses whether to retry, change approach, or tell you.

Limitations

• One sandbox per chat — A single chat cannot run multiple code sandboxes.
• No live command streaming — Output appears after the command finishes.
• Resume delay — After idle time, resuming a sandbox can take a few seconds (up to about 60 seconds if archived).
• Upload behavior — Files added before the sandbox exists sync automatically; later uploads sync individually (no bulk re-sync).
• No direct sandbox API — Clients cannot create, delete, or hibernate sandboxes; lifecycle is driven by the model during chat.
• Stream reconnection — The SSE stream ends after roughly 285 seconds; clients must reconnect via /resume.