# AIO Sandbox

> All-in-One Agent Sandbox Environment - Browser, Shell, File, VSCode Server, and MCP Hub in One Container

## Guide

- [Introduction](/guide/start/introduction.md)
- [Agent Call Sandbox vs In Sandbox](/guide/start/agent-sandbox.md): AIO Sandbox supports two common integration modes: the agent can call sandbox APIs from outside, or the agent can run inside the sandbox container. The main difference is where you keep orchestration logic, credentials, network access, and task execution.
- [Quick Start](/guide/start/quick-start.md): Get up and running with AIO Sandbox in just a few minutes.
- [Cloud Deployment](/guide/start/cloud-deployment.md): AIO Sandbox listens on 0.0.0.0 inside the container. On a cloud host, do not publish the container's 8080 port directly to a public interface. Keep the sandbox private and expose it through a reverse proxy or Ingress that handles TLS and access control.
- [FAQ](/guide/start/faq.md): This FAQ is written for the open-source Docker and SDK workflow.
- [Sandbox Info](/guide/basic/sandbox.md)
- [Browser & VNC](/guide/basic/browser.md): AIO Sandbox provides a full browser environment with VNC (Virtual Network Computing) access, enabling visual interaction with web applications and GUI-based workflows.
- [Display Recording](/guide/basic/display.md): AIO Sandbox can record the full desktop display and save it as an MP4 file. This captures browser UI, multiple tabs, popups, terminal windows, and any visible desktop activity. Use display recording when you need a complete visual audit trail. For page-only browser content, use browser page recording instead.
- [Shell Terminal](/guide/basic/shell.md): AIO Sandbox Shell is PTY-based, so it is best for REPLs, interactive programs, and tasks that need real terminal behavior. It exposes both REST APIs and WebSocket: use REST for a small number of terminal operations, and WebSocket for the built-in terminal or custom WebTerminal UI. For programmatic command execution, separated stdout/stderr, or offset-based incremental log reads, prefer Bash Pipe.
- [Bash Pipe](/guide/basic/bash.md): /v1/bash is a subprocess pipe-based command execution service for programmatic and agent-friendly workflows. It is different from the PTY-based Shell Terminal: Bash Pipe keeps stdout and stderr separate and supports incremental output reads with offsets.
- [Unified Code Execution](/guide/basic/code.md): /v1/code/execute provides a single entry point for running code. The sandbox routes supported languages to the matching runtime.
- [Jupyter](/guide/basic/jupyter.md): AIO Sandbox includes Jupyter kernel execution for Python code. It is useful for data processing, charts, notebooks, and stateful Python workflows.
- [Node.js](/guide/basic/nodejs.md): AIO Sandbox includes a Node.js runtime for JavaScript execution. Use it for scripts, JSON processing, web tooling, and JavaScript-based automation.
- [File Operations](/guide/basic/file.md): AIO Sandbox exposes file APIs under /v1/file/* for reading, writing, searching, uploading, downloading, and watching files inside the sandbox. The examples below assume the sandbox is available at http://localhost:8080 and use paths inside the container.
- [Utilities](/guide/basic/util.md): AIO Sandbox provides utility APIs for common agent tasks. The first public utility is content-to-Markdown conversion.
- [MCP Integration](/guide/basic/mcp.md): The Model Context Protocol (MCP) Hub in AIO Sandbox provides a centralized interface for AI agents to access multiple services through a single endpoint.
- [Skills](/guide/basic/skills.md): Skills are self-contained instruction and tool packages that can be registered in AIO Sandbox and discovered by an agent workflow.
- [AIO CLI](/guide/basic/aio-cli.md): The aio command-line tool wraps common AIO Sandbox APIs for terminal and agent workflows. It is available inside the sandbox container.
- [Error Handling](/guide/basic/error-handling.md): AIO Sandbox APIs expose several layers of errors. A robust client should not rely on HTTP status alone.
- [Preview Proxy](/guide/basic/proxy.md): AIO Sandbox includes built-in proxy endpoints that allow you to preview and test web applications and services directly from your development environment.
- [Code Server](/guide/basic/code-server.md): AIO Sandbox includes a fully-featured VSCode Server (Code Server) that provides a complete cloud development environment accessible through your web browser.
- [Authentication](/guide/basic/authentication.md): Support for JWT authentication using the environment variable JWT_PUBLIC_KEY (base64-encoded public key). Below is a complete process from generating keys, starting the service with static key mode, to making successful requests.
- [Environment Configuration](/guide/advanced/env-config.md): AIO Sandbox uses environment variables to configure services at container startup. When values are provided through Docker, Compose, or SDK configuration, pass them as strings.
- [Workspace](/guide/advanced/workspace.md): WORKSPACE controls the default working directory used by AIO Sandbox services.
- [AIO Hooks](/guide/advanced/lifecycle.md): AIO Hooks let you run startup commands at defined points in the container lifecycle. They are useful for installing lightweight dependencies, preparing files, or starting companion processes.
- [Proxy And Network](/guide/advanced/proxy-network.md): AIO Sandbox supports outbound proxy configuration and inbound preview proxying for services running inside the container.
- [Security](/guide/advanced/security.md): By default, a local AIO Sandbox is intended for trusted local development. When exposing it to a network or another service, add authentication and limit access.
- [Browser Configuration](/guide/advanced/browser-config.md): AIO Sandbox runs Chromium inside the container. You can configure language, homepage, user agent, and launch flags through environment variables.
- [Browser Cookies And State](/guide/advanced/browser-cookies.md): Browser state is often the most important part of browser automation. AIO Sandbox provides APIs for cookie management and full browser state save/load.
- [Browser Downloads](/guide/advanced/browser-downloads.md): Files downloaded by Chromium are stored inside the sandbox filesystem, so they can be inspected with shell commands or retrieved with the file API.
- [Code Server Configuration](/guide/advanced/code-server-config.md): AIO Sandbox includes code-server so you can open a browser-based VS Code environment inside the sandbox.
- [OpenCode Integration](/guide/advanced/opencode.md): AIO Sandbox includes the OpenCode CLI. OpenCode is an open-source terminal coding agent, so you can run it directly inside the sandbox or launch it through the built-in terminal page.
- [Codex Integration](/guide/advanced/codex.md): AIO Sandbox includes the OpenAI Codex CLI. Codex is a terminal-first AI coding agent, so you can run it directly inside the sandbox or launch it through the built-in terminal page.
- [Git Configuration](/guide/advanced/git-config.md): Git is commonly used to bring source code into the sandbox or commit generated changes.
- [WebTerminal Integration](/guide/advanced/web-terminal.md): AIO Sandbox provides a built-in Web Terminal page and exposes a Shell WebSocket endpoint so you can embed a terminal in your own local web UI. The examples below assume AIO Sandbox is running at http://localhost:8080.
- [Code Execution](/guide/basic/code-execution.md): Agent Sandbox provides powerful code execution capabilities for Python and JavaScript/Node.js, enabling you to run code in isolated environments with full control over execution and session management. This page is kept as an overview. For the current split guides, see Unified Code Execution, Jupyter, and Node.js.

## Daemon

- [Introduction](/daemon/start/introduction.md): aiod is the AIO Sandbox daemon. It serves the sandbox tools API over HTTP and WebSocket — commands, files, terminals, code execution, browser control, and MCP. The design keeps dependencies minimal: static musl builds on Linuxa native Windows buildgraceful degradation — browser, interpreters, and the desktop GUI worker are optional backends, detected at runtime Linux builds cover x86_64, arm64, and riscv64 (static musl). Windows builds cover x86_64 (aiod.exe, computer-use.exe).
- [Quick Start](/daemon/start/quick-start.md): aiod runs as a daemon and serves the sandbox tools API over HTTP. The design keeps dependencies minimal: static musl buildsone binary for containers, VMs, bare metal, and Windowsgraceful degradation when a capability is missing Examples use {base_url} for the daemon address: http://127.0.0.1:18091 by default, or the gateway port on a prebuilt image. WebSocket URLs use the same host and port with ws:// or wss://. [!TIP] Coming from a 1.x AIO image? See Migration from 1.x.
- [AIO Daemon Releases](/daemon/start/releases.md): Records the changelog of each AIO daemon and computer-use release and the binary artifacts per platform. Artifacts can be verified with SHA-256 checksums. Supported platforms: Linux x86_64, arm64, riscv64, and Windows x86_64.
- [AIO Daemon Dashboard](/daemon/start/dashboard.md): Use the Web Dashboard to debug a daemon quickly in your browser: open the dashboard.
- [Migration from 1.x](/daemon/start/migration.md): aiod stands in for the 1.x Python server. The public port and gateway are unchanged on the prebuilt images: most clients migrate by switching the image tag. The v1 surface is documented in v1 API Reference. The v2 surface is in the API Reference.
- [Architecture](/daemon/architecture.md): aiod is AIO Sandbox's core daemon process. It serves the sandbox tools API and hosts the MCP endpoint. The shell, interpreters, browser, and desktop it drives are separate processes. aiod discovers them at runtime but does not start them.
- [Sandbox Info & Capabilities](/daemon/basic/sandbox.md): The sandbox routes report aiod's environment and its current capabilities. Capabilities come from probing each subsystem, so the report tracks the live runtime rather than a fixed manifest. A missing subsystem degrades a capability. The request still succeeds. Results are cached; repeated polling is cheap. The v1 and v2 routes side by side are in Migration from 1.x.
- [Commands (Bash)](/daemon/basic/bash.md): A command is a fresh process. Each call spawns one, and tears it down when it exits or times out. No shell is left running afterward. A command session persists only the working directory, the run-as identity, any environment it was created with, and retained output between calls. For a live shell that stays attached and open, use Terminals instead. The v1 and v2 routes side by side are in Migration from 1.x.
- [Terminals (PTY)](/daemon/basic/shell.md): A terminal is a real PTY shell, backed by tmux when it is present or a native PTY otherwise. The session keeps its working directory, environment, and running program alive between calls. It accepts input while that program runs. Use it for REPLs, interactive programs, and a WebTerminal UI. A command is different: a fresh process per call, with no shell left running afterward. Use a terminal to stay attached and watch a session live. Use a command for a plain request/response with separate stdout and stderr. The v1 and v2 routes side by side are in Migration from 1.x.
- [File (FS)](/daemon/basic/file.md): The File plane reads, writes, edits, searches, transfers, and watches files. It shares one filesystem with commands, terminals, code execution, and browser downloads: a file written through this API is immediately visible to a shell command, and vice versa. The working directory is not a confinement boundary — file calls reach anywhere the daemon's own account can. Confinement is the sandbox's job, not this API's. On the file API, user means something different from its meaning on commands and terminals: On the file API, user only decides who owns new files and directories; on commands and terminals, it decides which account runs the process. The file API still reads and writes with the daemon's own privileges. GET /v1/capabilities reports the file capabilities under files, one flag per operation. The v1 and v2 routes side by side are in Migration from 1.x.
- [Error Handling](/daemon/basic/error-handling.md): Errors can appear in four layers: the HTTP status, the standard envelope, the JSON-RPC error object, and the isError flag on an MCP tools/call result. Check them in that order, then read the API's own fields: status and exit_code for commands, data.error_type for files, and outputs for code cells. Streaming is the exception: a WebSocket can report an error after the handshake succeeds.
- [Browser API](/daemon/basic/browser.md): aiod attaches to an existing Chromium; it does not launch the browser. Two environment variables decide where it attaches: Use a CDP client such as Playwright or Puppeteer, or call the REST API directly. /v1/browser/* and /v2/browser/* use the same request bodies. The exception is desktop input: v1 uses POST /v1/browser/actions, while v2 uses /v2/computer. See Computer Use.
- [CDP Access](/daemon/basic/cdp.md): aiod connects to an already running Chromium over CDP (Chrome DevTools Protocol). For external clients to connect, a reverse proxy in front of aiod also has to map Chromium's port 9222 to a public address.
- [Computer Use](/daemon/basic/display.md): computer-use is a worker process built to drive a real desktop: Mouse and keyboardScreenshotsClipboardOpen windowsThe accessibility tree It runs as a process separate from aiod, on any host with a desktop. Examples: An Ubuntu desktopA VM with Xvfb or XvncA Windows host with an interactive logon session aiod proxies its API. It does not touch the desktop itself. That process boundary keeps desktop control optional: aiod runs the same without a desktop present, and reaches one wherever computer-use is running. The desktop plane is v2-only, under /v2/computer/*. v1 keeps two aliases for 1.x clients: POST /v1/browser/actionsPOST /v1/display/record The routes side by side are in Migration from 1.x. The first part of this page is the action reference an agent's tools are built on. The second covers the viewers a person uses to watch or take over the same desktop. Browser API covers CDP-based page automation instead, and Computer Use examples walks one desktop task end to end.
- [Code Interpreter](/daemon/basic/code.md): Code execution is one dispatcher across languages and backends. Send a language and a code string: the daemon routes it to a runtime and answers when the run finishes. The runtime is a native REPL, an embedded IPython kernel, or an external Jupyter-compatible server. The dispatcher picks one per language and falls back through what it finds, so a request never has to name a runtime. A code session keeps an interpreter process alive between calls: what one call defines, the next one sees. Without a session, each run is a one-off in a process that is discarded afterwards. For a shell command rather than a code cell, use Commands. The v1 and v2 routes side by side are in Migration from 1.x.
- [Node.js](/daemon/basic/nodejs.md): /v1/nodejs/execute is aiod's JavaScript execution route: scripts, JSON processing, web tooling, JS-based automation. It always runs on the daemon's native REPL, a process spawned directly, needing only node on PATH. No external service is required. The same execution is also reachable by language, not just by route. Pass language: "javascript" (or "node") to POST /v2/code/execute. There is no separate /v2/nodejs.
- [Jupyter](/daemon/basic/jupyter.md): /v1/jupyter runs Python in a real IPython kernel. It covers what the native Python REPL cannot, at the cost of a heavier process: Rich output (display_data mime bundles, such as matplotlib PNGs)IPython magicsA choice of installed Python versions aiod implements this itself: it spawns ipykernel and speaks the Jupyter kernel protocol to it directly. No Jupyter server is involved, and nothing else needs to run.
- [Authentication](/daemon/basic/authentication.md): aiod supports one optional startup key. When no key is configured, every route is open and aiod is fully exposed. Bind it to 127.0.0.1, or put a gateway with its own authentication in front.
- [Observability](/daemon/basic/observability.md): aiod writes JSON logs to stdout, serves Prometheus metrics on GET /metrics, and exports OpenTelemetry traces when an endpoint is configured. Nothing is pushed by default.
- [Windows](/daemon/basic/windows.md): aiod on Windows is the same binary with the same API: auth, the response envelope, and OpenAPI are unchanged. This page covers only what differs from Linux, verified on Windows Server 2022 with Windows PowerShell 5.1.
- [Deployment & Operations](/daemon/ops/deployment.md): aiod runs in the foreground by default and can be handed to a process supervisor to run unattended. As a single binary, it exposes /health and /v1/capabilities as health checks. This page follows the deployment flow: install the binary, run it as a service, require an API key, wire up the health checks, then logs, environment variables, and troubleshooting.
- [Kubernetes](/daemon/ops/kubernetes.md): aiod is built to run as an ordinary container: one process, one port. It uses the same /health / /v1/capabilities split any Kubernetes probe expects. Run it as one container in a pod, with liveness on /health and readiness on /v1/capabilities. Add the extra security context only when the pod also runs a desktop or a Chromium the daemon controls. {base_url} below is the Service's address from inside the cluster, or the ingress address from outside it.
- [Examples](/daemon/examples/index.md): Each example starts with a concrete task against a live aiod daemon, exercises one sandbox capability, and checks the result. The code is runnable as written.
- [Agent Calls the Sandbox](/daemon/examples/agent-call-sandbox.md): Suppose an agent gets a small task: write data into the sandbox, process it with a command and Python, then read the result back. The whole flow takes four calls on one filesystem.
- [MCP](/daemon/examples/mcp.md): An MCP-capable agent can call the sandbox's built-in tools directly for file, command, code, and browser work.
- [Browser (CDP)](/daemon/examples/browser-cdp.md): When an agent needs full page automation, hand the sandbox's Chromium to Playwright or Puppeteer. The daemon supplies the CDP endpoint, and the client connects to and drives the same browser instance. Routes: GET /v2/browser/info GET /v1/browser/info For automation without a framework — navigate, snapshot, fill, click, screenshot over REST — see Browser Use.
- [Browser Use](/daemon/examples/browser-use.md): This example builds a small page from scratch: the agent writes the page, starts a static server, then uses HTTP to observe it, fill in a name, click a link, read the result, and take a screenshot. The page is built inside the sandbox by the file and command planes, so the whole flow runs offline and produces the same result every time. The tools are navigate, snapshot, fill, click, evaluate, and screenshot. Their routes are: /v2/browser/* /v1/browser/* Creating the page also requires one file write and one command run. Both surfaces take the same request bodies.
- [Interactive Terminal](/daemon/examples/terminal.md): This example follows a command that needs ongoing interaction: create a terminal session, attach to its PTY, run a command, send input, then reattach after the socket drops.
- [Code Execution](/daemon/examples/code-execution.md): Suppose an agent needs to analyze sales data: write a CSV into the sandbox, load and compute it in a stateful kernel, generate a chart, save it, and download it. The file routes carry the dataset and chart, while the analysis runs in the kernel session. If no state needs to survive between calls, one <ApiInlineV2>POST /v2/code/execute</ApiInlineV2><ApiInlineV1>POST /v1/code/execute</ApiInlineV1> call is enough.
- [File Operations](/daemon/examples/file-ops.md): This example follows a common development task: scaffold a small project, find and fix a TODO, read the changed lines, then watch the directory while a command changes it and handle the error contract. This example uses these routes: Files: /v2/fs/*Events: /v2/watch Files and events: /v1/file/*
- [Computer Use](/daemon/examples/computer-use.md): This example completes a real desktop task: open Chromium, reach a sample page, find and click a link, confirm the window title changed, and capture the screen. It uses the keyboard and accessibility tree throughout, with no pixel coordinates. The example page is built inside the sandbox by the file and command planes, so the whole flow runs offline and gives consistent results. The example uses these routes: /v2/computer/actions/v2/computer/actions/batch/v2/computer/accessibility/nodes/v2/computer/windows/v2/computer/screenshot The fixture also uses /v2/fs/write and /v2/commands.
- [](/daemon/api.md)
- [](/daemon/start/v1-api.md)

## API

- [](/api/index.md)

## Blog

- [Overview](/blog/index.md): Check here for the latest articles and release announcements about AIO Sandbox.
- [AIO Sandbox: An Integrated and Customizable Sandbox Environment for AI Agents](/blog/announcing-0.md)

## Other

- [AIO Sandbox Documentation](/README.md): This documentation provides comprehensive guides and API references for the AIO Sandbox environment.
- [](/404.md)
- [Agent Integration](/examples/agent.md): This guide shows how to integrate AI agents with AIO Sandbox, leveraging the Model Context Protocol (MCP) and REST APIs for powerful agent workflows.
- [Browser Automation Examples](/examples/browser.md): This guide shows how to use AIO Sandbox for browser automation, web scraping, and UI testing.
- [Examples](/examples/index.md): This section provides practical examples and integration guides for using AIO Sandbox in real-world scenarios.
- [Terminal Integration Examples](/examples/terminal.md): This section provides comprehensive examples for integrating with AIO Sandbox's WebSocket terminal interface.