Sandboxes

Give your agent a computer to run code on

Give your agent an isolated VM to run code, edit files, and preview apps, with a workspace that stays intact between commands.

Start building

sandboxes

$volcano cloud sandboxes exec --preset python3.12 -- python -c 'print(6 * 7)'42# one command, one temporary VM, terminated when it finished$volcano 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.0$volcano cloud sandboxes suspend 7cdbb4e3-…# processes and files kept, and suspended time is not charged

Overview

Give generated code its own place to run

An agent needs to test the code it writes, analyze a file, or start an app. Volcano Sandboxes give each hosted session its own isolated VM, with commands, files, and HTTP access.

Run a single snippet in a temporary sandbox that cleans up when it finishes. For work that takes several steps, keep a session and reuse its files and background processes. Suspend it between tasks and resume where it left off.

Work across steps

One workspace from the first command to the last

An agent can write a script, run it, and use the results in its next step. A session keeps files in /workspace and background processes alive between commands. A nonzero exit comes back as output for the agent to read, not as an error.

Use one-shot execution for a single snippet
Reuse files across commands in a session
Retry with the same request ID without rerunning code

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

Pause between tasks

Stop paying while the agent waits

Suspend a session while the agent waits for a reply or approval. Resume with its files and processes intact. Suspended time is free, and snapshots are included.

Keep files and processes through a pause
Resume within the session’s lifetime
Terminate when done to remove the workspace

suspend, then resume

$volcano cloud sandboxes suspend 7cdbb4e3-…state  suspending → suspended# no runtime charged while it waits$volcano cloud sandboxes resume 7cdbb4e3-…state  resuming → running$volcano cloud sandboxes exec 7cdbb4e3-… -- ls /workspacehttp.log  monthly.csv  revenue.png  sales.csv✓ files kept, and the server on port 8080 still answers

Preview what it builds

Open the app running in the sandbox

Start a server in the session, then request a credential for its port. Share the preview with a signed-in user by granting access to that session.

Credentials cover one session and one port
Credentials expire within five minutes
HTTP, WebSocket, SSE, and gRPC share one URL

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 your agent can use

An isolated VM per session

Hosted sessions get a private workspace with 1 GiB of memory on Hobby or up to 2 GiB on Superagent.

Python, Node.js, or custom dependencies

Start with python3.12 or node22, or deploy a Dockerfile fragment with the packages your agent needs.

A workspace that resumes

Suspend between tasks and resume with files and processes intact.

App previews over HTTP

Reach a running server with credentials scoped to its session and port, valid for at most five minutes.

Runtime included in each plan

Hobby includes 5 GB-hours a month and Superagent includes 20. Usage is configured memory multiplied by running time.

MCP, CLI, API, and SDKs

Give your agent MCP tools to run code, work with files, and manage sessions. Or use the CLI, REST API, or JavaScript, Python, and Ruby SDKs.

Code

Run code in your first sandbox

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

Manage sessions from a function
Run sandbox commands from a function and keep the service key on the server.

Durable functions

Retry workflow steps safely
Reuse each command’s request ID when a workflow retries a step to avoid running the code twice.

Authentication

Give users their own session access
Grant a signed-in user access to a specific session to run commands, read files, or open its preview.

File storage

Save results before cleanup
Copy results out of /workspace before terminating the session. Termination removes its files.

Frequently asked questions

Read the docs

How do I run code an LLM writes safely?

Run LLM-generated code in a hosted Volcano Sandbox, where each session has its own isolated VM. Manage sessions with a platform user token, project service key, or full-scope project access token. Grant signed-in users access only to the sessions they need. 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 sandbox session instead of one-shot execution?

Use a session when commands need to share files or keep a background process running. Use one-shot execution for a single snippet. Volcano terminates its temporary VM before the result comes back.

What are the memory and time limits for a sandbox?

Hobby sandboxes support up to 1 GiB of memory and a one-hour lifetime; Superagent supports up to 2 GiB and eight hours. The lifetime includes startup and keeps counting while suspended. Hobby allows five concurrent sessions, and Superagent has a 100-session safety ceiling.

How much does sandbox code execution cost?

Sandbox runtime is configured memory multiplied by running time, with 5 GB-hours included monthly on Hobby and 20 on Superagent per account. One GB-hour is 1 GiB running for one hour, including idle time. Superagent overage costs 25 credits per 5 GB-hour block; Hobby has no overage. Suspended time is free, and snapshots are included.

Can I install custom dependencies in a sandbox?

Deploy a custom sandbox template to include the dependencies your agent needs. Put a Dockerfile fragment and its files in a directory, without FROM, ENTRYPOINT or USER, because Volcano supplies the base image and supervisor. Deploy it with the CLI as an archive of up to 32 MiB, and Volcano builds and validates the image before activating it. Existing sessions keep their original image.

Can my AI agent run code in a sandbox through MCP?

An agent can run code and manage Volcano Sandboxes through MCP with a full-scope project access token. Start a session or run a one-shot command, read and write files, and suspend, resume, or terminate sessions. A read-only token can inspect sessions and read files. Issue port credentials and user grants from your backend.

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

Databases & Vector →