Sandboxes

A workspace where AI agents run code

Give an agent an isolated VM to run commands, work with files and serve HTTP, for a single command or for a session that suspends and resumes with its files and processes intact.

Start building
sandboxes
volcano cloud sandboxes exec --preset python3.12 -- python -c 'print(6 * 7)'42# one command, one temporary VM, terminated when it finishedvolcano cloud sandboxes run --preset node22{ "id": "7cdbb4e3-…", "state": "starting", "memory_mb": 1024 }volcano cloud sandboxes exec 7cdbb4e3-… -- node -e 'console.log(process.version)'v22.22.0volcano cloud sandboxes suspend 7cdbb4e3-…# processes and files kept, and suspended time is not charged
Overview

Agents need somewhere to run what they write

An agent analyzing a dataset needs somewhere to execute Python. A coding assistant needs to edit files and run the tests. Run that code inside your own function or server and it can reach everything your code can; build your own fleet of throwaway machines and you are maintaining images, a scheduler, cleanup jobs and a way to reach a port inside each one.

Volcano Sandboxes put that environment inside your project, and each hosted session is its own isolated VM. Run one command and Volcano terminates the VM when it finishes, or keep a session whose files in /workspace and background processes carry over from one command to the next. Suspend it while the agent waits and the time is not charged. When a server runs inside, reach its port with a credential that lasts five minutes at most.

Sessions

One workspace across every step

A one-shot command runs in a temporary sandbox that is terminated before the result comes back. A session keeps its files in /workspace and its background processes running between commands, so an agent can run an analysis and answer the follow-up from what it already saved. A nonzero exit comes back as data for the agent to read, not as an error.

  • One-shot commands clean up after themselves
  • Files up to 8 MiB per read or write
  • A retried command returns its stored result
volcano cloud sandboxes shell 7cdbb4e3-… · data-analyst template
sandbox> python /workspace/analyze.py /workspace/sales.csvrevenue by region   NA 4.2M · EMEA 3.1M · APAC 2.4Msaved /workspace/monthly.csv, /workspace/revenue.pngsandbox> python /workspace/growth.py --quarter 3fastest growth in Q3: APAC, up 18%✓ the second script read what the first one saved
Suspend and resume

Paused while the agent waits

Suspend a session while the agent waits on a person, a model or a long-running job. Resume it later and the files in /workspace are still there and the server it started still answers. Suspended time uses no runtime allowance or credits, and the snapshot behind it is included. The session's lifetime keeps counting while it is suspended.

  • Processes and files survive a suspend
  • Suspended time is not charged
  • Terminate when done, and its files go with it
suspend, then resume
volcano cloud sandboxes suspend 7cdbb4e3-…state  suspending → suspended# no runtime charged while it waitsvolcano cloud sandboxes resume 7cdbb4e3-…state  resuming → runningvolcano cloud sandboxes exec 7cdbb4e3-… -- ls /workspacehttp.log  monthly.csv  revenue.png  sales.csv✓ files kept, and the server on port 8080 still answers
HTTP access

Reach a server inside the session

Start an app preview or an interactive tool in a session, then request a credential for that one session and port. Send it as X-Volcano-Sandbox-Token, or post it from a browser form to set a cookie, and HTTP, WebSocket, SSE and gRPC all use the same URL. A signed-in user of your app reaches only the sessions you granted to them.

  • Scoped to one session and one port
  • Expires within five minutes
  • Revoking a grant closes its open connections
a preview on port 8080
volcano cloud sandboxes exec 7cdbb4e3-… -- sh -c 'python -m http.server 8080 >/workspace/http.log 2>&1 &'# then, from your backendsession.access(8080)              url, token · expires in 5mGET  X-Volcano-Sandbox-Token: …    200 OKWS   same URL, same token          101 Switching Protocols✓ this session and this port only, for five minutes at most
Capabilities

What every sandbox gives you

An isolated VM per session

Each hosted session runs in its own virtual machine, with a private /workspace and 1 GiB of memory, or up to 2 GiB on Superagent.

Presets or your own image

Start from the python3.12 or node22 preset, or deploy a Dockerfile fragment that Volcano builds and validates before any session uses it.

Suspend and resume

Keep a session's processes and files while nothing is happening, without using runtime, and resume it when the work continues.

Ports you can reach

Short-lived credentials per session and port, with HTTP, WebSocket, SSE and gRPC on the same URL.

Metered on memory and time

Runtime is configured memory times running time, however many commands run. Hobby includes 5 GB-hours a month and Superagent 20.

API, CLI, SDKs and MCP

The same sandboxes from the REST API, the CLI, the JavaScript, Python and Ruby SDKs, MCP tools and the Dashboard, and on your machine with volcano start.

Code

Start it, run it, reach it

JavaScript
import { VolcanoClient } from '@volcano.dev/sdk'; // Sessions are managed with a service key, so this runs in a function or on // your own server, never in the browser. const client = new VolcanoClient({ apiUrl: process.env.VOLCANO_API_URL ?? 'https://api.volcano.dev', anonKey: process.env.VOLCANO_ANON_KEY, accessToken: process.env.VOLCANO_SERVICE_KEY, }); const projectId = process.env.VOLCANO_PROJECT_ID; const created = await client.sandboxes.create(projectId, { preset: 'python3.12', region: 'us-east-1', maxDurationSeconds: 1800, }); if (created.error) throw created.error; const session = created.data; try { // Creation returns while the VM is still starting. Poll, with a deadline. const deadline = Date.now() + 120_000; while (session.state !== 'running') { if (Date.now() >= deadline || ['unknown', 'terminated'].includes(session.state)) { throw new Error(`Session unavailable: ${session.state}`); } await new Promise((resolve) => setTimeout(resolve, 1000)); const refreshed = await session.refresh(); if (refreshed.error) throw refreshed.error; } // Files stay in /workspace for every later command in this session. const written = await session.files.write( '/workspace/analyze.py', new TextEncoder().encode(agentScript), ); if (written.error) throw written.error; // Keep the request ID with the command. Retrying with it returns the stored // result, and a command whose outcome is unknown is never run again. const requestId = crypto.randomUUID(); const run = await session.exec('python /workspace/analyze.py', { requestId }); if (run.error) throw run.error; // A nonzero exit is data for the agent to read, not a platform error. console.log(run.data.exitCode, run.data.stdout, run.data.stderr); // Serve what it built, and reach it with a credential for this session and // port. const served = await session.exec('python -m http.server 8080 >/workspace/http.log 2>&1 &'); if (served.error) throw served.error; const access = await session.access(8080); if (access.error) throw access.error; // The command returns before the server listens, and a request sent too early // gets a 502. Poll a read-only GET, with a deadline, before real traffic. const headers = { 'X-Volcano-Sandbox-Token': access.data.token }; const ready = Date.now() + 30_000; let response = null; while (!response || response.status === 502) { if (Date.now() >= ready) throw new Error('Preview server did not start listening'); await new Promise((resolve) => setTimeout(resolve, 500)); response = await fetch(access.data.url, { headers }).catch(() => null); } console.log(response.status); } finally { const stopped = await session.terminate(); if (stopped.error) throw stopped.error; }
Use cases

What people run in sandboxes

analyst session · data-analyst template
write    /workspace/sales.csv      184 KBexec     python analyze.py         exit 0 · saved monthly.csv, revenue.pngsuspend  waiting for the next questionresume   files and processes intactexec     python growth.py          exit 0 · read monthly.csvanswered from the saved results, nothing uploaded twice
Platform

Works with the rest of Volcano

Functions and agents

  • Keep the key on the server

    Create sessions and run commands from a function, so the service key that manages sandboxes never reaches a browser.

Durable functions

  • Agent runs that outlast a request

    Make each sandbox command a durable step with a fixed request ID, so a retried step never runs the command a second time.

Authentication

  • Share a session with a user

    Grant a signed-in user one session, so they can run commands in it or open its preview and reach no other.

File storage

  • Keep what the session made

    Copy results out of /workspace into a bucket before you terminate the session, because its files go with it.

Frequently asked questions

Read the docs
Who can reach a sandbox?

Each hosted session runs in its own isolated virtual machine. Creating and managing sessions takes a platform user token, or a service key or project access token for that project, and anonymous keys cannot reach a session at all. A signed-in user of your app can only use a session you explicitly granted to them, and cannot create, suspend, resume, terminate or grant sessions. Local sandboxes from volcano start are Docker containers that share your machine's kernel, so use hosted sandboxes when you need VM isolation.

When should I use a session instead of a one-shot command?

A one-shot command runs in a temporary sandbox and returns its result once that sandbox is terminated, which suits a single snippet of code. Use a session when several commands should share files, when a server has to stay up, or when the work runs longer than one request should wait: start it as a background process in the session and check its output or files with short requests.

How long can a session run?

Up to one hour on Hobby or eight hours on Superagent, startup included, and one hour by default. The lifetime keeps counting while a session is suspended, and activity never extends it, so choose it for the task when you create the session. Hobby runs up to 5 sessions at once; Superagent has no plan limit, with a safety ceiling of 100.

How are sandboxes billed?

On runtime: configured memory multiplied by running time, so a 1 GiB session running for half an hour uses 0.5 GB-hours however many commands it runs, and idle time while it runs counts. Hobby includes 5 GB-hours per account each monthly cycle; when they run out, starts and resumes are refused and running sessions are suspended. Superagent includes 20 GB-hours, then additional runtime in 5 GB-hour blocks of 25 credits. Suspended time, snapshots and local sandboxes are not charged.

Can I bring my own dependencies?

Yes. Put a Dockerfile fragment and its files in a directory, using RUN, COPY, ENV, WORKDIR and CMD but no FROM, ENTRYPOINT or USER, because Volcano supplies the base image and supervisor. Deploy it as a tar.gz of up to 32 MiB from the Dashboard, the CLI, an SDK or the API. Volcano builds and validates the image, including that every declared port accepts connections, before the template becomes active, and sessions already running keep the image they started with.

Can an agent drive a sandbox through MCP?

Yes. Volcano's MCP server has tools to start a session from a preset or template, run a one-shot command or a command in a session, read and write files, and suspend, resume or terminate sessions, with a full-scope project access token. A read-only token can list presets and inspect templates, sessions and files. The project always comes from the token, and a start or command retried with the same Idempotency-Key does not run twice. Port credentials and user grants stay with your backend.

Ready to give your agent a sandbox?

Build, deploy, and scale on Volcano's global platform — free to start, with no infrastructure to manage.

Start building free

Checkout more features

Next.js frontends← Next.js FrontendsDatabases and vectorDatabases & Vector →