# Sandboxes Run commands and HTTP services in isolated sessions, with files and processes that persist across steps. Sandboxes give an agent, an application, or a developer an isolated place to run code. Run a single command in a temporary Sandbox, or keep a session alive for work that spans several steps: its files in `/workspace` and its background processes, including HTTP services, last until the session ends. Hosted Sandboxes run in isolated virtual machines; local Sandboxes run in Docker containers on your machine. ## Quick example Run a command in a temporary Sandbox from the CLI: ```bash volcano cloud sandboxes exec --preset python3.12 -- python -c 'print(42)' ``` The command prints the guest's stdout and stderr and exits with the guest process's exit code. Discover the presets you can use with `volcano cloud sandboxes presets` or `GET /sandboxes/presets`. ## Features | Feature | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | One-shot commands | Run one command in a temporary Sandbox that Volcano terminates when the command finishes | | Sessions | Keep a workspace, background processes, and HTTP services across many commands | | Suspend and resume | Pause a session with its processes and files intact; suspended time uses no runtime allowance | | CPU and disk caps | Bound a session's vCPUs and writable disk; the session reports the caps it enforces | | Files | Read, write, and list files in `/workspace`: 8 MiB per call, tar archives of a tree, or 1 GiB in parts | | HTTP access | Reach a session port over HTTP, WebSocket, SSE, or gRPC with short-lived, per-port credentials | | No outbound network | Create a session with `deny_all` egress: no DNS, internet, or link-local access for its whole lifetime, with a readback of what was applied | | User grants | Let a signed-in project user run commands, read files, and connect to one session | | Templates | Save a preset and memory size by name, or deploy a custom image from a `Dockerfile` fragment | | Safe retries | Retrying a request with the same idempotency key never runs the command a second time | | Unkept output | Return a command's output once and keep no copy of it, for one command or a whole session | | Local mode | The same API on your machine after `volcano start` | ## One-shot command or session Use a one-shot command when a single command produces the whole result. Its response returns after Volcano has terminated the Sandbox, with the command's stdout, stderr, and exit code. Use a session when several commands should share a workspace or a service must stay available. Creating a session is asynchronous: poll it until its state is `running` before running commands. Suspending a session keeps its processes and files; terminating it destroys them. See [Run a command](https://docs.staging.volcano.dev/platform/guides/sandboxes.md#run-a-command) and [Keep a session alive](https://docs.staging.volcano.dev/platform/guides/sandboxes.md#keep-a-session-alive) for the API calls. ## Who can use Sandboxes Platform user tokens, project service keys, and full-scope project access tokens manage Sandboxes. Read-only project access tokens can inspect templates, deployments, sessions, and session files. A signed-in project user can only use a session that has been explicitly granted to them, and cannot create, suspend, resume, or terminate sessions. Anonymous keys cannot create or access sessions. Keep service keys on your backend. See [Grant a signed-in user access](https://docs.staging.volcano.dev/platform/guides/sandboxes.md#grant-a-signed-in-user-access). ## Plans and limits Runtime is configured baseline memory multiplied by running time, so a 1 GiB session running for 30 minutes uses 0.5 GBh however many commands it runs. Suspended time, snapshots, and local sessions are not charged. Each plan sets an included runtime allowance, a memory limit, a maximum session lifetime, and a limit on concurrent sessions. See [Pricing and usage](https://docs.staging.volcano.dev/platform/guides/sandboxes.md#pricing-and-usage) for each plan's values, what happens when the allowance runs out, and usage counters. Check whether Sandboxes are available in an environment with [`GET /capabilities`](https://docs.staging.volcano.dev/platform/api-reference/overview.md#capabilities). ## Next steps | Guide | Description | | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | [Sandboxes guide](https://docs.staging.volcano.dev/platform/guides/sandboxes.md) | The full API: sessions, lifetimes, files, HTTP access, grants, and pricing | | [Turn off outbound network](https://docs.staging.volcano.dev/platform/guides/sandboxes.md#turn-off-outbound-network) | Run untrusted code in a session that cannot reach the network | | [Deploy a custom template](https://docs.staging.volcano.dev/platform/guides/sandboxes.md#deploy-a-custom-template) | Build your own image from a `Dockerfile` fragment | | [Run locally](https://docs.staging.volcano.dev/platform/guides/sandboxes.md#run-locally) | Use Docker-backed Sandboxes with `volcano start` | | [CLI](https://docs.staging.volcano.dev/cli/sandboxes.md) | Run commands and manage sessions, files, and templates from a terminal | | [JavaScript SDK](https://docs.staging.volcano.dev/sdk/js/sandboxes.md) | The `client.sandboxes` facade in JavaScript | | [Python SDK](https://docs.staging.volcano.dev/sdk/python/sandboxes.md) | The `client.sandboxes` facade in Python | | [Ruby SDK](https://docs.staging.volcano.dev/sdk/ruby/sandboxes.md) | The `client.sandboxes` facade in Ruby | | [MCP server](https://docs.staging.volcano.dev/platform/interfaces/mcp.md#sandbox-tools) | Let an AI agent start sessions, run commands, and read files |