Sandbox

The Sandbox gives your AI agent the ability to read, write, and run code in a secure, isolated development environment. When you chat with an AI that has Sandbox enabled, it can create files, execute terminal commands, search codebases, and generate downloadable artifacts — all within a cloud-based VM that is private to your conversation.

Getting Started

Sandbox is available when your AI agent has the Sandbox tool configured and uses a model with strong coding capabilities. You don't need to enable anything — the AI will automatically use the sandbox when your request involves code.

You can also explicitly request sandbox tools when chatting with an agentless assistant by toggling the Sandbox option in the chat input area.

What the AI Can Do

When the sandbox is active, your AI can perform these operations:

• 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

As the AI works, you'll see each tool call displayed in the chat:

• A collapsible row appears for each operation, showing the tool name (e.g., "Read", "Executing", "Write") and its arguments.
• While running, a spinner indicates the operation is in progress.
• On success, the row shows the result (file contents, command output, etc.) which you can expand to inspect.
• On error, a red warning icon appears with the error message.

Uploading Files

You can upload files to the chat, and they are automatically placed in the sandbox at ./user-uploads/ when the sandbox is first created. The AI knows about this directory and can read your files from there.

If you upload files after the sandbox already exists, they are synced individually.

AppBuilder

The AppBuilder is a specialized sandbox experience for building full applications:

• The screen splits into a chat panel (left) and a preview panel (right).
• The AI creates or resumes a sandbox automatically and provides a live preview of the running app.
• You can switch between Preview, Code (embedded editor), and Database (for SQLite apps) tabs.
• Changes made by the AI are committed and pushed to GitHub when the conversation completes.

Timeouts and Long Commands

• Most file operations (read, write, delete, list) have a 60-second timeout. If the sandbox becomes unresponsive, the AI receives an error and can retry or inform you.
• Terminal commands default to a 3-minute timeout. The AI can increase this up to 30 minutes for long-running operations like builds or test suites.
• If a command times out, it is terminated and the AI decides what to do next.

Sandbox Persistence

Your sandbox persists across messages in the same chat. If you close the browser and come back, the AI can resume the same sandbox environment — files and installed dependencies are still there.

Each chat has its own isolated sandbox. Other chats cannot see or modify your sandbox's files.

Using the Sandbox via API

If you're building an integration using the API, you can enable sandbox tools in your chat requests.

Requesting Sandbox Tools

Option 1: Agent configuration — If the AI agent has a Sandbox tool configured in its settings, sandbox tools are automatically included. No extra parameters are needed.

Option 2: Explicit request — For agentless chats, include sandbox in the tools array:

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

Streaming Events

When the AI uses sandbox tools, the SSE stream includes tool-specific events:

• tool.call — Emitted when the AI invokes a sandbox tool. Includes the tool name and arguments.
• tool.message — Emitted when a tool call completes. Includes the status (success or error) and output.

Standard chat events (message.created, message.delta, message.complete) continue alongside tool events.

Available 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

Checking Sandbox State

The chat object includes sandbox IDs when present:

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

Error Handling

Sandbox errors appear as tool.message events with status: "error". Common scenarios:

• Timeout — Filesystem operations time out after 60 seconds; commands after 3 minutes by default.
• File not found — The requested path doesn't exist in the sandbox.
• Command failure — Non-zero exit code from a shell command.

The AI receives these errors and typically decides how to proceed (retry, adjust approach, or inform you).

Limitations

• One sandbox per chat — You cannot have multiple code sandboxes in a single chat.
• No real-time command output — The AI waits for a command to finish before showing the result.
• Sandbox resume time — If the sandbox has been idle for a while, resuming it may take a few seconds (up to 60 seconds if archived).
• File upload is one-way at creation — Files uploaded before the sandbox was created are synced automatically. Later uploads are synced individually but there is no bulk re-sync.
• No sandbox management API — Clients cannot create, delete, or hibernate sandboxes directly. Sandbox lifecycle is managed by the AI during chat.
• Stream reconnection — The SSE stream closes after approximately 285 seconds. Clients must reconnect via the /resume endpoint.