Sandbox

The sandbox lets your AI 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.

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.