Skip to main content

Agent Sandboxes

A machine of your own for Claude Code, Codex, OpenCode and Pi: created in a minute, stopped when idle, billed only while it runs, and reachable from the tools already on your laptop.

An agent sandbox is a SailOps container created with the agent-sandbox preset. It runs a managed image, persists the complete /home/agent, including its workspace at /home/agent/workspace, and can be used three ways: from the browser terminal of the container, over SSH from your IDE or terminal, and as the execution environment of your local coding agent through MCP tools. Everything a container offers (start, stop, volume snapshots, connections to your databases, logs, metrics, audit log) applies to a sandbox.

Sandboxes live under AI › Sandboxes in the project console.

Quick start​

curl -fsSL https://raw.githubusercontent.com/herewecloud/sailops-sandbox/main/install.sh | sh   # the sailops-sandbox CLI
export PATH="$HOME/.local/bin:$PATH" # also finds an unprivileged installation
sailops-sandbox init # paste a project API key once
sailops-sandbox run -- claude # Claude Code, inside a sandbox named after your repository

init registers the SailOps MCP server in every coding tool it finds on your machine (Claude Code, Codex, OpenCode, Cursor), installs the sandbox instructions, and wires SSH so ssh sailops-<name> works. From then on, your local agent runs its commands in the sandbox and never on your laptop.

The installer downloads the binary from the releases of the public repository herewecloud/sailops-sandbox. SAILOPS_SANDBOX_VERSION=v0.1.3 pins a release. For staging or a custom deployment, use sailops-sandbox init --api-url https://your-console-host; the Connect panel includes this URL automatically. Rerun installation and init to update existing SSH entries; the generated proxy uses the installed binary and credentials directory so IDEs do not need your terminal's PATH.

The API key needs the containers:list, containers:update, sandboxes:exec and sandboxes:connect scopes; the Connect button of a sandbox creates one with those preselected.

Use the sandbox from your own tools​

Two doors into a sandbox, both through SailOps, both audited:

  • MCP tools (sandbox_exec, sandbox_write_file, sandbox_read_file, …) on the SailOps MCP server at https://app.sailops.io/api/mcp. Your local agent keeps its context and editor, and executes in the sandbox.
  • SSH through the bridge at wss://app.sailops.io/api/ai/v1/sandboxes/<name>/ssh, which the CLI turns into a ProxyCommand. Works with plain ssh, VS Code and Cursor Remote-SSH, rsync and scp.

Claude Code (and Conductor)​

What you type once:

sailops-sandbox init

It runs claude mcp add --transport http --scope user sailops https://app.sailops.io/api/mcp --header "X-Api-Key: …" and installs the skill ~/.claude/skills/sailops-sandbox/SKILL.md. Conductor runs Claude Code under the hood, so it is covered too. Add this line to the CLAUDE.md of a project that should always run there:

This project's execution environment is the SailOps sandbox `<name>` (MCP server `sailops`). Run every shell command through the `sandbox_exec` tool and edit files with `sandbox_write_file`; never run commands locally.

What the agent can then do: list, create and start sandboxes, run builds, tests and git commands with sandbox_exec (exit code, stdout and stderr come back), read and write files, and stop the sandbox when done.

To run Claude Code inside the sandbox instead (your laptop can close), with the ANTHROPIC_API_KEY of the sandbox:

sailops-sandbox run -- claude        # = up + ssh -t sailops-<name> tmux new -A -s main claude

Codex​

sailops-sandbox init

adds [mcp_servers.sailops] to ~/.codex/config.toml and a delimited section to ~/.codex/AGENTS.md. The manual equivalent:

[mcp_servers.sailops]
url = "https://app.sailops.io/api/mcp"
http_headers = { "X-Api-Key" = "<your-api-key>" }

Put the same instruction as above in the project's AGENTS.md, or run Codex inside the sandbox with sailops-sandbox run -- codex.

Inside the sandbox, codex uses the provider in OPENAI_BASE_URL and the key in OPENAI_API_KEY. With SailOps Models enabled, it defaults to gpt-oss-120b with medium reasoning; set OPENAI_MODEL or pass -m to choose another model. Provider-hosted web search and Codex multi-agent namespaces are disabled because the upstream does not support them. Your own command-line configuration can override these defaults. Codex uses the sandbox’s gVisor boundary for execution; its nested Linux sandbox is disabled in the image because bubblewrap network setup is incompatible with this runtime. This applies only to Codex running inside the remote container, not your local Codex.

OpenCode​

init adds mcp.sailops to ~/.config/opencode/opencode.json and a section to ~/.config/opencode/AGENTS.md:

{
"mcp": {
"sailops": { "type": "remote", "url": "https://app.sailops.io/api/mcp", "headers": { "X-Api-Key": "<your-api-key>" }, "enabled": true }
}
}

Cursor​

init adds mcpServers.sailops to ~/.cursor/mcp.json and prints an Add to Cursor deep link (the Connect panel shows the same button). For Remote-SSH, open the workspace directly:

sailops-sandbox up my-repo && cursor --remote ssh-remote+sailops-my-repo /home/agent/workspace

VS Code​

With the Remote - SSH extension:

sailops-sandbox up my-repo && code --remote ssh-remote+sailops-my-repo /home/agent/workspace

up creates the sandbox if needed, starts it, authorises your ~/.ssh/id_ed25519.pub (or generates one) and refreshes ~/.config/sailops/ssh_config, which ~/.ssh/config includes. Every sandbox of the project gets a Host sailops-<name> block there.

Wake on SSH connection​

After the first sailops-sandbox up my-repo has registered your key, connect directly:

ssh sailops-my-repo

If the sandbox is stopped, CLI 0.1.3 starts it, waits for it to run, then opens SSH automatically. A startup already in progress is awaited. This also applies to scp, rsync and IDE connections using the generated Host block. The API key needs containers:list, containers:update and sandboxes:connect. A missing sandbox is not created by SSH.

The proxy waits up to ten minutes and writes progress only to stderr. Generated Host blocks use ConnectTimeout 660; rerun sailops-sandbox ssh-config --all after updating the CLI. VS Code and Cursor Remote-SSH may override this timeout: set remote.SSH.connectTimeout to 660 in the IDE settings for cold starts. OpenSSH command-line options override the Host configuration. Raw websocat connections require an already running sandbox.

rsync and scp​

Through the same Host block:

sailops-sandbox sync my-repo                      # rsync the current directory into /home/agent/workspace/my-repo, honouring .gitignore
rsync -az --filter=':- .gitignore' ./ sailops-my-repo:/home/agent/workspace/my-repo/
scp build.log sailops-my-repo:/home/agent/workspace/

sync supports the system rsync on macOS and GNU rsync, creates the destination directory and retains partial files so rerunning the command can resume an interrupted transfer. It preserves permissions and symbolic links and honours .gitignore; it does not delete unrelated destination files. Prefer it for directories with many small files. A failed or interrupted copy is incomplete until a subsequent transfer succeeds; scp does not automatically resume. Xpra file transfer and clipboard sharing remain disabled: use SSH tools to move files.

The CLI, and life without it​

CommandWhat it does
sailops-sandbox initStore the key, register the MCP server in each tool, install the skill and instructions, wire SSH
sailops-sandbox up [name]Create if missing, start, wait until Running, authorise your SSH key, refresh the SSH config
sailops-sandbox open [name]ssh -t sailops-<name> tmux new -A -s main
sailops-sandbox run [name] -- claudeup, then the command in a tmux session
sailops-sandbox sync [name] [path]rsync into the workspace
sailops-sandbox exec name -- pnpm testOne command, output printed, exit code preserved
sailops-sandbox list, start, stopWhat you expect
sailops-sandbox ssh-config name / --allThe Host block, or the whole managed file

name defaults to the name of the current git repository. The CLI is a static binary for macOS and Linux (amd64 and arm64); its configuration is ~/.config/sailops/credentials, or the SAILOPS_API_KEY and SAILOPS_API_URL environment variables.

Without the CLI, any WebSocket client can be the ProxyCommand, for instance websocat:

ssh -o ProxyCommand="websocat --binary wss://app.sailops.io/api/ai/v1/sandboxes/my-repo/ssh -H 'X-Api-Key: $SAILOPS_API_KEY'" -p 2222 agent@my-repo

and the exec endpoint is plain HTTP: POST /api/public/api/v1/sandboxes/{name}/exec with {"command": ["pnpm", "test"]} or {"shell": "cd my-repo && pnpm test"}, optional cwd, env and timeoutSeconds (60 by default, 600 at most).

Security notes​

  • SSH is key-only: no password, no root login, agent only. Keys are set in the sandbox settings (Connect panel, API, or sailops-sandbox up), stored as the SAILOPS_SSH_AUTHORIZED_KEYS secret of the container, and applied at once to a running sandbox.
  • sshd runs as the unprivileged agent user on port 2222 inside the sandbox; nothing is exposed on the internet. Every connection goes through a SailOps port-forward authenticated by your API key (scope sandboxes:connect) or your console session.
  • Host keys live on the workspace volume, so the fingerprint stays the same across stops. The CLI keeps them in ~/.config/sailops/known_hosts.
  • Every SSH session, every exec and every MCP command is written to the sandbox's Activity tab, with the command text for exec.
  • A bridge lives at most 24 hours and closes after 30 minutes without traffic; 20 sessions per sandbox at once. An open session, like an open terminal, pauses the idle stop.
  • The sandbox environment (your LLM keys, CLAUDE_CONFIG_DIR, …) is available in SSH sessions exactly as in the browser terminal: at every start, the entrypoint copies the container environment, LLM keys included, into ~/.ssh/environment (mode 600, readable by agent only). That file is in the persistent home and is overwritten from the current secrets at every start; do not use it for your own SSH configuration. SailOps also refreshes authorized_keys from the registered project keys. Your private keys and other SSH configuration remain persistent.
  • sandboxes:exec runs any command as agent, so in practice it also grants what sandboxes:connect does (a command can add an SSH key). Give it only to keys you would trust with SSH. The MCP sandbox_write_file tool refuses ~/.ssh and workspace/.sailops; SSH keys are changed in the sandbox settings.

What is in the image​

The image ghcr.io/herewecloud/agent-sandbox is public and rebuilt every night. It is based on Ubuntu 24.04 and ships:

AreaContents
Useragent (UID 1000), with privilege escalation disabled; the workspace lives in /home/agent/workspace
LanguagesNode 24 with pnpm, Python 3.13 with uv, Go (latest stable), Rust (stable, via rustup)
Toolsgit, git-lfs, gh (GitHub CLI), ripgrep, jq, tmux, sqlite3, rsync, build-essential
Coding agentsClaude Code (claude, auto-update disabled), Codex (codex), OpenCode (opencode), Pi (pi)
SSHOpenSSH server on port 2222, run by agent, key authentication only

The exact versions installed in your sandbox are listed in /etc/sailops/agents.json:

cat /etc/sailops/agents.json

Docker is not available inside a sandbox. The sandbox runs under gVisor with privilege escalation disabled. Install user tools in your persistent home; system-wide package installation with sudo is unavailable.

Creating a sandbox​

  1. Open AI › Sandboxes and click New sandbox.
  2. Choose a name, the workspace size (10 to 100 GiB, 20 GiB by default) and the idle timeout.
  3. Pick a compute class: eco (2 vCPU / 4 GiB by default) or standard (2 vCPU / 8 GiB). Trial organizations get eco with 1 vCPU / 2 GiB.
  4. Optionally enter LLM keys (see below) and connect databases or services of the project.
  5. Click Create sandbox. The first start pulls a multi-gigabyte image and can take a couple of minutes; later starts reuse the node cache.

The preset is applied server-side: the image, the start command and the workspace mount are imposed, and the sandbox has no public port, no autoscaling and no health probe. You can still resize the CPU and memory or the workspace later from the container's General tab.

From a tool, sailops-sandbox up, the sandbox_create MCP tool and POST /api/public/api/v1/sandboxes create one with the same defaults.

Giving the agents an LLM key​

The agents need credentials for a model provider. Two paths:

  • SailOps Models: create an API key with the ai-models:invoke scope and set OPENAI_API_KEY to it and OPENAI_BASE_URL to the Models endpoint. Codex, OpenCode and Pi speak the OpenAI API; Claude Code does not, so it needs your own Anthropic key.
  • Your own provider key: enter it in the LLM keys section when creating the sandbox, or later in the container's Environments tab. ANTHROPIC_API_KEY is read by Claude Code, OPENAI_API_KEY and OPENAI_BASE_URL by the OpenAI-compatible agents. The keys are stored as secret environment variables of the container and are never returned by the API.
Credentials end up in the workspace

Whatever an agent stores (~/.claude, ~/.codex, cloned repositories with tokens in their remotes) lands on the workspace volume. Personal Claude or ChatGPT subscriptions are not a supported way to sign the agents in: use an API key. The volume is kept while the sandbox is stopped and is copied into every volume snapshot. Treat snapshots as sensitive and delete the sandbox when you no longer need it.

Idle stop​

A running sandbox is stopped automatically when all of the following hold:

  • no terminal or SSH session has been open, no exec has run and no start has happened for longer than the idle timeout (2 hours by default, 30 minutes on trial, adjustable between 15 minutes and 24 hours), and
  • the CPU of the sandbox stayed under 2 % of its limit during the last 15 minutes.

The timeout is a minimum inactivity period, not an exact shutdown deadline. If runtime overhead hides whether the applications are idle, SailOps verifies their CPU over an additional 15-minute window. Missing or interrupted observations keep the sandbox running and billed until idleness can be established.

A long build or test run keeps the sandbox alive even with nothing attached. The stop writes a line in the container's Activity tab, as do terminal and SSH sessions: opening and closing one is audited.

The idle timeout can be changed from the sandbox card or through the API (PUT /api/v1/organizations/{organizationId}/projects/{projectId}/ai/sandboxes/{containerName}/settings, or PUT /api/public/api/v1/sandboxes/{name}/settings with an API key).

Network isolation​

An agent runs code you did not write, so each sandbox carries its own egress policy on top of the project isolation every workload gets. From inside a sandbox you can reach the Internet, the services of the same project and DNS; you cannot reach pods of other projects (use a project peering for that), the nodes of the cluster, or the cloud metadata endpoints (169.254.169.254, 169.254.42.42). The sandbox also runs with no Kubernetes service-account token.

The policy can be switched off per sandbox with networkIsolation: false in the same settings endpoint, which leaves only the platform-wide project isolation. It is meant for the rare case of a tool that must reach a node-local service; keep it on otherwise.

Pricing​

A sandbox is billed like any container: compute while it runs, the workspace volume always.

ItemCatalog price
eco, 2 vCPU / 4 GiBabout 0.068 EUR per running hour (50 EUR per month if never stopped)
standard, 2 vCPU / 8 GiBabout 0.183 EUR per running hour (133.6 EUR per month)
trial eco, 1 vCPU / 2 GiBabout 0.034 EUR per running hour
Workspace, 20 GiB standard block storageabout 2.47 EUR per month, whether the sandbox runs or not

A stopped sandbox costs nothing beyond its workspace. Token usage is billed by your model provider, or by SailOps Models once you use it.

Tips​

  • tmux is installed: run agents inside a tmux session (sailops-sandbox open does) so a closed terminal does not end them. The idle stop still applies once the agent is done and the CPU falls.
  • Volume snapshots of the workspace act as checkpoints before letting an agent loose on a repository.
  • Connect a project database from the Connections tab: its credentials are injected as environment variables the agents can read, over SSH too.

Network access​

Open the sandbox's Network tab to choose its outbound access. By default, the workspace can reach the public Internet and only the private services explicitly added in Connections. Connections create service credentials as well as the network grant. Removing a connection withdraws that grant as provisioning converges.

Project network permits other private services in the same project. New incoming connections to an isolated sandbox remain blocked; the authenticated terminal, SSH and MCP bridges still work. Nodes, the Kubernetes API and cloud metadata stay blocked. Confirmed project peerings retain their own destination ports.

Turn off Allow Internet access for an offline workspace. DNS and platform telemetry remain available, but public Git hosts, package registries and model APIs become unreachable. This switch does not filter individual domains.

sailops-sandbox network show my-repo
sailops-sandbox network set my-repo --private-access connected-services --internet false

The same controls are available in public sandbox settings as networkAccess.privateAccess (connected-services or project) and networkAccess.internetAccess, and through MCP tools sandbox_network_get and sandbox_network_update. Network updates require containers:update; reading requires containers:list. The Network form and these update commands keep the additional sandbox isolation enabled.

Graphical applications​

Graphical applications are disabled by default on new sandboxes. Enable them in Connect → Sandbox software, or with CLI 0.2.1 or later:

sailops-sandbox software set my-sandbox --graphics true

Changing software restarts a running sandbox and closes its sessions. Files and credentials in the workspace remain; a stopped sandbox stays stopped. Enabling graphics alone starts no application and does not change the compute class. Chromium + Xpra used about 700–800 MiB RAM in staging and share CPU/RAM with your coding agents while running. A connected viewer keeps compute running and billed. The first pull of the graphical image can take several minutes.

After enabling it, run these commands on your computer:

# Open the included Chromium browser without installing a local viewer.
sailops-sandbox app my-sandbox --browser -- sailops-browser

# Open a graphical terminal as a native window (requires a local Xpra client).
sailops-sandbox app my-sandbox -- xterm

# Open the lightweight Linux desktop in your browser.
sailops-sandbox desktop my-sandbox --browser

When Xpra is missing, native commands offer to install it after confirmation in an interactive terminal. You can also run sailops-sandbox install-xpra without an API key. On macOS, the CLI verifies the official download and installs into ~/Applications without sudo; an existing app is never replaced. On Linux, it uses your distribution package manager and may request administrator authorization. After installation, the native command continues. Decline or use --browser to avoid installing a local client; scripts never receive an interactive installation prompt.

Native mode requires Xpra on your computer. Browser mode needs only OpenSSH and your browser. Replace the program after -- with any installed Linux graphical application and its arguments. Applications exclusive to macOS or Windows cannot run in this Linux environment. GPU acceleration is not provided.

The CLI starts a stopped sandbox, prepares your SSH key, then opens an authenticated SSH tunnel. Browser mode prints a private loopback URL and opens it automatically. Keep the command running; press Ctrl+C to disconnect. Closing the browser releases the tunnel after two minutes without a connected viewer. Right-click the desktop to open its browser and terminal menu. Do not share the viewer link. No graphical port is exposed publicly. Clipboard synchronization, file transfer, printing, audio and webcam forwarding are disabled.

A connected viewer keeps compute running and billed. After disconnection, normal idle-stop rules resume. An unattached graphical session also expires after 15 minutes. Running applications do not survive sandbox shutdown; workspace files do.

sailops-sandbox apps my-sandbox
sailops-sandbox app-attach my-sandbox --browser SESSION_ID
sailops-sandbox app-stop my-sandbox SESSION_ID

The included browser runs as agent, using the outer gVisor isolation because Chromium's nested Linux sandbox is incompatible with this runtime. Current Firefox builds are not compatible with the staging gVisor runtime. Older sandbox images do not include graphical support: save your work and apply the managed image update before using these commands.

Choose preinstalled tools​

The creation form and Connect → Sandbox software offer a checklist for Claude Code, Codex, OpenCode and Pi. All four are selected by default; you may choose any subset or none. Git, SSH, tmux, Node.js, Python, Go and Rust remain in the common base. Selected tools are installed from a managed offline bundle before startup, without sudo or Internet access, and use additional scratch disk. Their settings and logins still live in the persistent workspace.

sailops-sandbox software show my-sandbox
sailops-sandbox software set my-sandbox --tools codex,opencode
sailops-sandbox software set my-sandbox --graphics false --tools none

The same settings are exposed as software on public sandbox creation/settings, and as spec.sandboxSoftware on the user container spec. MCP provides sandbox_software_get and sandbox_software_update; creation accepts graphicsEnabled and preinstalledTools. Software updates are approval-gated in Bosco because they can restart the sandbox. Only the curated tool names are accepted; arbitrary install commands and package URLs are refused.

Persistent home​

The entire /home/agent and /home/agent/workspace share the existing persistent volume and storage quota. Dotfiles (.bashrc, .gitconfig), private SSH keys, shell history, application settings and user-installed tools under the home survive stops, pod replacements and software changes. On the first start the managed image home is initialized without overwriting user files; its initial toolchains use part of that same volume quota. Existing workspace paths and files are kept. An older stopped sandbox receives the home mount on its next start; this does not recover data previously lost from an ephemeral home.

The managed .sailops/home-v1 directory inside the workspace backs the home; leave it in place. Volume snapshots therefore also contain the home, credentials and application data. Normal sandbox deletion and volume-retention choices apply to both together. Processes, open application sessions and system-level changes outside /home/agent do not persist. SailOps refreshes its managed SSH authorization/environment files at startup; user private keys and SSH configuration are retained.

Snapshot checkpoints​

Manual snapshots flush the running sandbox filesystem before creating the checkpoint, including both the home and workspace mounts. If the sandbox is starting, stopping or cannot flush its files, snapshot creation fails instead of publishing an unsafe checkpoint. Pause application writes or stop the sandbox first when you need an application-consistent backup; a filesystem checkpoint does not guarantee consistency of transactions still in progress.

Restore replaces the workspace volume and its persistent home with the snapshot contents. Files written after the checkpoint are lost, and running applications must be relaunched. A previously stopped sandbox stays stopped. SSH access authorized in SailOps is reapplied at startup.

Scheduled snapshots are not available for sandboxes yet: use a manual snapshot. Managed-agent state-volume backup/restore is not currently exposed through the managed-agent service.