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 athttps://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 aProxyCommand. Works with plainssh, VS Code and Cursor Remote-SSH,rsyncandscp.
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
| Command | What it does |
|---|---|
sailops-sandbox init | Store 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] -- claude | up, then the command in a tmux session |
sailops-sandbox sync [name] [path] | rsync into the workspace |
sailops-sandbox exec name -- pnpm test | One command, output printed, exit code preserved |
sailops-sandbox list, start, stop | What you expect |
sailops-sandbox ssh-config name / --all | The 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,
agentonly. Keys are set in the sandbox settings (Connect panel, API, orsailops-sandbox up), stored as theSAILOPS_SSH_AUTHORIZED_KEYSsecret of the container, and applied at once to a running sandbox. - sshd runs as the unprivileged
agentuser 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 (scopesandboxes: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
execand 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 byagentonly). 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 refreshesauthorized_keysfrom the registered project keys. Your private keys and other SSH configuration remain persistent. sandboxes:execruns any command asagent, so in practice it also grants whatsandboxes:connectdoes (a command can add an SSH key). Give it only to keys you would trust with SSH. The MCPsandbox_write_filetool refuses~/.sshandworkspace/.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:
| Area | Contents |
|---|---|
| User | agent (UID 1000), with privilege escalation disabled; the workspace lives in /home/agent/workspace |
| Languages | Node 24 with pnpm, Python 3.13 with uv, Go (latest stable), Rust (stable, via rustup) |
| Tools | git, git-lfs, gh (GitHub CLI), ripgrep, jq, tmux, sqlite3, rsync, build-essential |
| Coding agents | Claude Code (claude, auto-update disabled), Codex (codex), OpenCode (opencode), Pi (pi) |
| SSH | OpenSSH 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
- Open AI › Sandboxes and click New sandbox.
- Choose a name, the workspace size (10 to 100 GiB, 20 GiB by default) and the idle timeout.
- 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.
- Optionally enter LLM keys (see below) and connect databases or services of the project.
- 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:invokescope and setOPENAI_API_KEYto it andOPENAI_BASE_URLto 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_KEYis read by Claude Code,OPENAI_API_KEYandOPENAI_BASE_URLby the OpenAI-compatible agents. The keys are stored as secret environment variables of the container and are never returned by the API.
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
exechas 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.
| Item | Catalog price |
|---|---|
| eco, 2 vCPU / 4 GiB | about 0.068 EUR per running hour (50 EUR per month if never stopped) |
| standard, 2 vCPU / 8 GiB | about 0.183 EUR per running hour (133.6 EUR per month) |
| trial eco, 1 vCPU / 2 GiB | about 0.034 EUR per running hour |
| Workspace, 20 GiB standard block storage | about 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
tmuxis installed: run agents inside a tmux session (sailops-sandbox opendoes) 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.