Sandboxes

Cloud Sandbox runtime is included in HOBBY and SUPERAGENT plans, with additional runtime billed on SUPERAGENT. See Pricing and usage for allowances, charges, and exemptions. Check whether Sandboxes are available with GET /capabilities: the sandboxes, sandboxes.sessions, sandboxes.custom_templates, sandboxes.network_isolation, and sandboxes.output_not_kept entries report each part. Where Sandboxes are not available, every Sandbox endpoint answers 404 with error code feature_unavailable:

{ "error": "sandboxes are not available", "code": "feature_unavailable" }

Where they are turned off after use, only creating or starting a session, template, execution, or deployment, and listing presets, answer that 404, so sessions and templates you already have can still be read and deleted.

A 503 means the Sandbox service is temporarily unavailable. For commands, follow the retry rules below. In local mode it means the local Sandbox service is not running, see Run locally.

Run a command

Run a command in a temporary Sandbox:

curl "$VOLCANO_API_URL/projects/$PROJECT_ID/sandbox-executions" \
  -H "Authorization: Bearer $SERVICE_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"preset":"python3.12","region":"us-east-1","command":"python -c '\''print(42)'\''","timeout_seconds":30}'

{
  "session_id": "7cdbb4e3-0419-574e-8017-705734ae8d76",
  "region": "us-east-1",
  "duration_ms": 2300,
  "stdout": "42\n",
  "stderr": "",
  "exit_code": 0,
  "stdout_truncated": false,
  "stderr_truncated": false,
  "timed_out": false,
  "output_kept": true
}

stdout and stderr each hold the first 1 MiB (1,048,576 bytes) the command wrote. stdout_truncated or stderr_truncated is true when it wrote more.

Discover published presets and regions with GET /sandboxes/presets. Use the returned preset IDs when creating templates, sessions, or one-shot executions. An empty catalog means no verified preset has been published yet.

If startup fails or times out before the command is sent, one-shot execution returns code sandbox_start_failed. The HTTP status follows the recorded reason: 422 for sandbox_run_hook_timeout on a custom deployment, 429 for exhausted allowance or expired allowance retention, and 503 for other or unknown startup reasons, including hook timeouts on managed presets and sandbox_network_untrusted. A deny_all startup whose final observation shows outbound network access records sandbox_network_untrusted, even if its hook also timed out. The command did not run. Reusing the same Idempotency-Key replays that failure. The error message includes the recorded reason when known, including on replay:

{
  "error": "sandbox failed to start; command was not executed; reason: sandbox_run_hook_timeout",
  "code": "sandbox_start_failed"
}

Investigate the reason before using a new key for another attempt. Confirmed running time is billed, including when a VM boots late before cleanup stops it. For repeated startup or run-hook timeouts, check the template's startup configuration and logs; a timeout alone does not establish a template fault. For sandbox_allowance_exhausted, restore the runtime allowance or credits first. The message is diagnostic text and may change; use the response code for stable programmatic error handling. If no reason was recorded, the message remains generic. Startup timeout also requests termination; background cleanup continues after the request ends. Wait or back off before using a fresh key: cleanup can still hold capacity after a failure response. Every fresh-key refusal is also retained, so an immediate retry can consume another key without starting a VM. sandbox_start_timeout means the startup wait expired; sandbox_session_expired means the requested session lifetime ended first. Increase the lifetime for the latter. Rarely, startup fails with sandbox_launch_outcome_unknown. The session isn't billed. Its startup command may already have started and can run until the session would have expired; Volcano can't reach it. Start a new session with a new key. Caller cancellation or a caller deadline during admission or startup returns 504 if the connection can still deliver a response. The outcome stays unknown; reuse the original key.

One-shot admission can also refuse a command before it runs:

For these explicit response code values, the original key continues to replay the refusal after the limit is resolved. Use a new key for a new attempt. A 403 or 429 without one of these codes or sandbox_start_failed does not establish that the command was never sent.

A command on an existing session that is not ready, is stopping, or has expired returns 409 with code sandbox_session_not_running. The command was not sent. Wait for a running session and use a new key for a new attempt. The original key continues to replay the refusal even after the session resumes.

For other errors or a lost response, reuse the original key. An unknown outcome returns 409; do not switch keys to repeat a command with side effects.

GET /sandbox-sessions/{sessionId} includes last_error_code for the last recorded lifecycle reason. Observations without a new reason preserve it, including after termination or recovery. This is historical information, not a current error; use state to determine the session's current state. The field is omitted when no reason is known.

sandbox_launch_outcome_unknown: the session isn't billed. Its startup command may already have started and can run until the session would have expired; Volcano can't reach it. Start a new session. A session whose launch outcome was unknown when it ended for an earlier reason, such as project_deleting, keeps that reason's code, with the same caveat.

Additional codes may be introduced; accept unknown values. A recorded reason alone does not establish whether a command ran or authorize a retry. Use the execution response's code and the retry rules above.

Use a region returned for the selected preset and memory size; region availability can differ between presets. Sandbox availability is independent of where the API request is served. For a custom template, use a region in its verified deployment. New regions appear after their deployment is ready and the corresponding images have passed verification.

Temporarily unavailable regions

us-west-2 is temporarily unavailable for Sandboxes. The catalog omits it, and a new session or one-shot execution there answers 400:

{
  "error": "this region is temporarily unavailable for Sandboxes; choose another region from GET /sandboxes/presets",
  "code": "sandbox_region_unavailable"
}

Choose another region from the catalog. Sessions already in us-west-2 stay readable and can be terminated, and templates and deployments are unchanged. A custom template deployed while the region is unavailable builds no image there; redeploy it once the region returns to start sessions there.

Keep a session alive

Create a session, then poll its returned ID until state is running:

curl "$VOLCANO_API_URL/projects/$PROJECT_ID/sandbox-sessions" \
  -H "Authorization: Bearer $SERVICE_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"preset":"python3.12","region":"us-east-1","memory_mb":1024,"max_duration_seconds":3600}'

{
  "id": "7cdbb4e3-0419-574e-8017-705734ae8d76",
  "project_id": "8b1ec799-b9dd-4db0-8466-486d57d166f1",
  "sandbox_id": null,
  "region": "us-east-1",
  "memory_mb": 1024,
  "state": "starting",
  "desired_state": "running",
  "created_at": "2026-09-23T12:00:00Z",
  "expires_at": "2026-09-23T13:00:00Z",
  "network": { "egress": "default", "applied": "unknown" },
  "executions": { "keep_output": true }
}

Use GET /sandbox-sessions/{sessionId} to read state. Creation is asynchronous; starting does not mean commands can run yet. unknown requires operator recovery. Volcano reports running when the session can accept authenticated requests.

Run commands through POST /sandbox-sessions/{sessionId}/exec, with a new Idempotency-Key for each intended command:

curl "$VOLCANO_API_URL/sandbox-sessions/$SESSION_ID/exec" \
  -H "Authorization: Bearer $SERVICE_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"command":"python -m http.server 8080 >/workspace/http.log 2>&1 &","timeout_seconds":10}'

The HTTP service remains alive after the command returns. Its lifetime belongs to the session. The command can return before the service starts listening. Poll a read-only health endpoint with a timeout before sending application traffic; a request made before the port is listening can return 502. Do not restart the command or retry a write request just to wait for readiness.

A cloud session runs at most 64 commands at once and has no limit on how many it runs in total. A command holds its slot until it exits and every background process it started has exited too, so a service started with & keeps its slot while it runs. With every slot in use, exec returns 429 with code sandbox_command_capacity and starts nothing; retry with the same Idempotency-Key once a command finishes. Sessions on a custom template built before guest version hosting-4 instead refuse every command after their 64th with 409; rebuild the template to lift that limit.

File requests on a terminated session return 404. On a session that is still starting or is suspended they return 503; wait for running. An exec request on a session that is not running returns 409 sandbox_session_not_running and retains its refusal; after recovery, use a new key for a new command attempt.

Suspending retains the session's state; terminating destroys it.

These operations return 202. Poll state for completion. desired_state records the requested outcome. Once termination is requested, public reads report terminating until the session is terminated, unless its state is unknown and requires operator recovery. A session whose launch outcome was unknown when it ended reads terminated with last_error_code sandbox_launch_outcome_unknown, or with the earlier reason it was already ending for, without confirming that its VM stopped. The session isn't billed. Its startup command may already have started and can run until the session would have expired; Volcano can't reach it. Closing new-session admission does not prevent termination or grant revocation.

Turn off outbound network

Set network.egress to deny_all to create a session with no outbound network for its whole lifetime:

curl "$VOLCANO_API_URL/projects/$PROJECT_ID/sandbox-sessions" \
  -H "Authorization: Bearer $SERVICE_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"preset":"python3.12","region":"us-east-1","network":{"egress":"deny_all"}}'

In a deny_all session:

• DNS lookups fail.
• Connections to internet addresses over IPv4 and IPv6 fail, and so do link-local addresses such as 169.254.169.254 and fe80::/10.
• Nothing can connect back out through the path Volcano uses to reach the session.
• Loopback works: a process can serve files on 127.0.0.1 or ::1 to another process in the same session.
• Commands, files, suspend, and resume work as usual.
• Port access answers 400 with code sandbox_network_isolated.

Check that GET /capabilities lists sandboxes.network_isolation as available before you depend on deny_all. Where it is unavailable, a request for deny_all answers 400 with code feature_unavailable, and sessions you already created with it keep their policy.

The policy is fixed when the session is created. Suspend and resume keep it, and no request changes it; create another session for a different policy. POST /projects/{id}/sandbox-executions takes the same network field. Omitting network is the same as {"egress":"default"}, which keeps the region's standard outbound internet access. A retry with the same Idempotency-Key must send the same policy; a different one returns 409.

Every session reads back its policy:

{ "network": { "egress": "deny_all", "applied": "deny_all" } }

egress is the policy you requested. applied is what Volcano last observed on the session itself, never the request alone:

A session first reports running only after its network has been observed. If you depend on deny_all, wait for state to be running, read network.applied, and terminate the session unless it is deny_all. Act on applied only while the session is running: a terminated session keeps what Volcano last observed.

After that, applied reads unknown in two expected windows: from a suspend or resume request until Volcano observes the session again, and briefly while Volcano rolls out an update. Act on a later unknown only while the session's desired_state is running: then stop sending it work and terminate it.

If Volcano observes a deny_all session with outbound network access, or in a state that doesn't match its policy, it refuses the session's commands and file calls and terminates it at once: desired_state reads terminated, last_error_code reads sandbox_network_untrusted, and the session doesn't start again. Its applied keeps what Volcano last observed, so it can read default. A deny_all session whose final observation shows outbound network access also reads sandbox_network_untrusted, even when Volcano first observes it after it has ended or its startup hook timed out. A session that is already terminating when Volcano observes a mismatch keeps the last_error_code it had, which can be empty, unless its final observation shows outbound network access, which reads sandbox_network_untrusted, or a startup-hook timeout, which reads sandbox_run_hook_timeout. Once a session reads sandbox_network_untrusted, no later change replaces it. Volcano still terminates it.

Volcano also checks the isolated network that deny_all sessions use in each region. If it finds that network open, it terminates every deny_all session in the region that has started, with sandbox_network_untrusted, and starts no new one until the network checks out again. A started session that was already terminating keeps terminating and also reads sandbox_network_untrusted.

Volcano starts a deny_all session only after it has recently confirmed the network isolation that session needs in its region. When it can't, it doesn't start the session: the session ends with last_error_code sandbox_network_isolation_unavailable, and a one-shot execution returns 503 with sandbox_start_failed. No command runs. Retry later with a new session, or a new Idempotency-Key for one-shot execution. Resuming a suspended deny_all session needs the same confirmation. When Volcano can't confirm it, it terminates the session instead of resuming it, with the same last_error_code.

Local mode applies the same policy and readback. In a deny_all container, only loopback is up, with no route out. ::1 works where the Docker host's kernel has IPv6. A local deny_all session from a custom template needs a template deployed on this version of Volcano or later: one deployed earlier ends with sandbox_image_outdated (409 for one-shot execution) until you redeploy it.

Choose lifetime and memory

Supply exactly one of preset or sandbox_id when creating or executing. A preset starts a session directly without creating a template; the returned sandbox_id is null. Sessions created from an explicit template return its ID. Presets support 1024 and 2048 MB; omitted memory selects 1024 MB. Named Sandboxes retain their selected memory for both sessions and one-shot executions when memory_mb is omitted. A conflicting override is rejected.

Unlimited local sessions return expires_at: null. A finite expiry also applies while suspended. One-shot execution always requests termination after the command finishes, even when its configured lifetime is unlimited.

Startup and network time do not consume the command timeout, but they do consume the VM lifetime and can incur usage. Cloud command responses are synchronous. The public connection closes after 1000 seconds without a response, even with a longer client timeout. For longer work, create a session, start a background process, and poll its status or files with short requests. Local mode has no cloud connection limit. A client disconnect does not prove that a VM has stopped; one-shot cancellation records termination intent for the worker. Activity never extends VM expiry.

Suspend retains reserved capacity. 429 indicates no capacity is available; an uncertain termination does not free capacity.

A successful one-shot response follows confirmed VM termination. Use a session when several commands should share a workspace or a service must remain available. Both modes inherit the template TTL when max_duration_seconds is omitted. A one-shot command timeout returns 504; retrying its key returns 409 because no completed result was stored. A session command reaching its command timeout returns execution data with timed_out: true. If the VM lifetime expires first, the command returns 504 instead.

Cap CPU and disk

Add limits when creating a session to bound the CPU and disk its commands and template service use together. Supply at least one cap:

curl "$VOLCANO_API_URL/projects/$PROJECT_ID/sandbox-sessions" \
  -H "Authorization: Bearer $SERVICE_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"preset":"python3.12","region":"us-east-1","memory_mb":2048,"limits":{"vcpus":2,"disk_mib":4096}}'

Memory-backed (tmpfs) filesystems count against the session's memory, not disk_mib. /dev/shm is one, and holds at most 64 MiB in every session. Omit limits to let a session's processes use all of its vCPUs and disk.

The session applies the caps before it runs any command, then reports what it enforces. Until then, limits.applied is unknown and the session stays starting:

{
  "id": "7cdbb4e3-0419-574e-8017-705734ae8d76",
  "state": "starting",
  "limits": { "applied": "unknown" }
}

Once the session is running, check limits.applied:

{ "state": "running", "limits": { "applied": "enforced", "vcpus": 2, "disk_mib": 4096 } }

Caps bound what code inside the session uses. The session's size is the hard limit on what it can use and what it costs: runtime is charged on memory_mb whatever the caps.

In local mode, Docker enforces the caps. A vcpus cap above 2 enforces 2. disk_mib bounds what /workspace and /tmp can take beyond the template's workspace contents, up to their local sizes of 512 MiB and 128 MiB. Both are memory-backed, so their contents count against memory_mb. When the template's workspace contents leave less memory than that, the session enforces, and reports, a lower disk_mib.

Retry without repeating a command

Creation and command requests require a UUID Idempotency-Key. Keep the same key and body when retrying. Keys are scoped to the project and operation.

An unknown preset returns 400 before reserving the execution key. Repeating that invalid request returns 400 again and never runs a command.

A completed command returns its stored result. Changed intent returns 409. An in-progress command or lost result returns 409 with sandbox execution outcome is unknown; the command will not be repeated. A guest capacity refusal (429 sandbox_command_capacity) leaves its key unused, so retrying the same key can run it once capacity frees. This differs from sandbox_session_not_running, which retains the refusal for that key. Do not use a new key unless you intend to run the command again.

Keep no command output

By default Volcano stores each command's result, so a retry with the same Idempotency-Key returns its output. When output can hold secrets, set keep_output to false. The command's stdout and stderr are returned once, in the response to the request that ran it. Volcano's control plane never stores them in the execution journal, database, logs or traces. Volcano still records the exit code, timings and a keyed digest of the request, so a retry with the same key returns the exit code with empty streams and never runs the command again:

curl "$VOLCANO_API_URL/sandbox-sessions/$SESSION_ID/exec" \
  -H "Authorization: Bearer $SERVICE_KEY" \
  -H "Idempotency-Key: $REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{"command":"./print-token.sh","keep_output":false}'

{
  "stdout": "tok_example\n",
  "stderr": "",
  "exit_code": 0,
  "stdout_truncated": false,
  "stderr_truncated": false,
  "timed_out": false,
  "output_kept": false
}

The same request retried with $REQUEST_ID returns:

{
  "stdout": "",
  "stderr": "",
  "exit_code": 0,
  "stdout_truncated": false,
  "stderr_truncated": false,
  "timed_out": false,
  "output_kept": false
}

The first response uses the same 1 MiB (1,048,576 bytes) cap per stream and the same truncation flags as any other command. One-shot executions accept keep_output too.

This does not cover the Sandbox itself: the Sandbox's memory and a suspended session's snapshot can still hold what the command wrote.

To make every command in a session keep no output, create it with executions.keep_output set to false:

curl "$VOLCANO_API_URL/projects/$PROJECT_ID/sandbox-sessions" \
  -H "Authorization: Bearer $SERVICE_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"preset":"python3.12","region":"us-east-1","executions":{"keep_output":false}}'

The setting is fixed for the session's lifetime, and session reads return it as executions.keep_output. Commands in the session inherit it. A command that sets keep_output to true there is refused before it runs:

{
  "error": "this session keeps no command output; omit keep_output or set it to false",
  "code": "sandbox_session_keeps_no_output"
}

Output a command redirects to a file stays in the session's workspace like any other file. Delete it, or terminate the session, when you are done.

Check the sandboxes.output_not_kept entry in GET /capabilities before you rely on this. While it is unavailable, keep_output: false, executions.keep_output: false, and commands in a session created with it answer 400 with code feature_unavailable. A retry of a command that already ran still returns its exit code. Commands that keep output work either way, and the session can still be read and terminated.

Read and write files

Files are scoped to the session workspace. Content uses base64 and is limited to 8 MiB per operation. Use a relative path such as file.bin or its /workspace/file.bin equivalent. Parent directories must already exist; create them first with an exec command such as mkdir -p nested before writing nested/file.bin. Paths must be canonical: traversal components (..), repeated separators, and paths outside /workspace return 400 in cloud and local mode.

curl "$VOLCANO_API_URL/sandbox-sessions/$SESSION_ID/files/write" \
  -H "Authorization: Bearer $SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"hello.txt","data":"aGVsbG8K"}'

curl "$VOLCANO_API_URL/sandbox-sessions/$SESSION_ID/files/read" \
  -H "Authorization: Bearer $SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"hello.txt"}'

Writing returns 204; reading returns {"data":"aGVsbG8K"}. The written file belongs to the session user, the user commands run as, and only that user can read or write it. A write that does not fit on the session's disk returns 409 with code sandbox_disk_full. In a cloud session with limits.disk_mib, writes run as the session user, so a write into a directory that user cannot write returns 409 with code sandbox_path_conflict. Files survive suspend/resume and are removed with the session.

Upload a directory as a tar archive

Create a file archive to write a whole tree in one request. Send multipart/form-data with project_id, session_id and path, in any order, then the tar archive as the archive part. Volcano extracts it into the directory path names, creating it when missing. path must name a directory below the workspace root: a path that resolves to the root or to /, such as ., ./, /, /workspace or /workspace/., answers sandbox_archive_invalid. The archive may be gzip-compressed; Volcano detects compression itself.

tar -C ./repo -czf repo.tgz .
curl "$VOLCANO_API_URL/sandbox-file-archives" \
  -H "Authorization: Bearer $SERVICE_KEY" \
  -F "project_id=$PROJECT_ID" \
  -F "session_id=$SESSION_ID" \
  -F "path=repo" \
  -F "archive=@repo.tgz"

{
  "project_id": "5b1e…",
  "session_id": "0f6c…",
  "path": "repo",
  "files": 42,
  "bytes": 183020
}

Each request accepts at most 32 MiB of archive, 10,000 files and directories, and 256 MiB uncompressed, and has 2 minutes to send its archive; a slower request fails and writes nothing. Split a larger tree into several archives and send them one after another.

The archive may hold only regular files and directories. A symbolic link, hard link, sparse file, device, absolute name, or .. component refuses the whole archive. Every file and directory the archive writes, including path when Volcano creates it, belongs to the session user. Permission bits are kept; setuid, setgid, and sticky bits are dropped. Volcano checks and stages the whole archive before the workspace changes, so a refused archive writes nothing, and it undoes one that fails part way. If a session process moves or removes a directory while the archive is written, the request answers 409, a file the archive replaced there is kept in a .sandbox-archive-* directory at the workspace root, and files the archive already placed can stay. Volcano never follows a symbolic link already in the workspace. Read-only directories the session user owns still take later archives and file parts, and keep their modes.

A session outside project_id answers 404, like an unknown session.

Write a file larger than 8 MiB

Create file parts to write a file of up to 1 GiB, at most 8 MiB per part. Each part names its offset, the whole file's size, and its lowercase hex sha256:

curl "$VOLCANO_API_URL/sandbox-file-parts" \
  -H "Authorization: Bearer $SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id":"'"$PROJECT_ID"'","session_id":"'"$SESSION_ID"'","path":"cache/pkg.tgz","offset":0,"size":20971520,"sha256":"<sha256 of the whole file>","data":"<first 8 MiB, base64>"}'

{
  "project_id": "5b1e…",
  "session_id": "0f6c…",
  "path": "cache/pkg.tgz",
  "offset": 0,
  "size": 20971520,
  "received": 8388608,
  "complete": false
}

Send the next part with "offset":8388608, and so on. Nothing appears at path until the part that ends at size arrives; that part checks the whole file's size and SHA-256, then moves it into place in one step, and answers "complete": true. Missing parent directories are created. The finished file and the directories created for it belong to the session user, and only that user can read or write the file.

To recover from a failed request, resend that part: a part may start anywhere up to the bytes already received. A part at offset 0 starts the file again. Resending the part that finished the file answers the same completion while the file at path still matches size and sha256.

Parts collect in a hidden file beside path that starts with .sandbox-part-. It stays until the file completes, a part at offset 0 restarts it, or the session ends.

List files

List a workspace directory with each entry's type, size, and permission bits, and optionally a SHA-256 digest of each file. Compare two listings to see what a command changed.

curl -G "$VOLCANO_API_URL/sandbox-session-files" \
  -H "Authorization: Bearer $SERVICE_KEY" \
  --data-urlencode "project_id=$PROJECT_ID" \
  --data-urlencode "session_id=$SESSION_ID" \
  --data-urlencode "path=/workspace" \
  --data-urlencode "include_sha256=true" \
  --data-urlencode "limit=7"

{
  "project_id": "5f0c3a52-8d1e-4b7a-9a43-2f6d1c0e7b19",
  "session_id": "0b8f6a1e-3c2d-4e5f-8a9b-7c6d5e4f3a2b",
  "entries": [
    { "path": "cache", "type": "directory", "size": 0, "mode": 0, "unreadable": true },
    {
      "path": "hello.txt",
      "type": "file",
      "size": 6,
      "mode": 420,
      "sha256": "5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03"
    },
    { "path": "latest", "type": "symlink", "size": 0, "mode": 511 },
    { "path": "logs", "type": "directory", "size": 0, "mode": 493 },
    { "path": "logs/app.log", "type": "file", "size": 4096, "mode": 420, "sha256_skipped": "changing" },
    { "path": "src", "type": "directory", "size": 0, "mode": 448 },
    {
      "path": "src/main.py",
      "type": "file",
      "size": 21,
      "mode": 493,
      "sha256": "2d543015627a771436b30ea79fd0ecda8df8bcd77b3d55661caf5a0d6e809886"
    }
  ],
  "next_cursor": "Xww6Uo0eS3qaQy9tHA57GQuPah48LU5fipt8bV5POitzcmMvbWFpbi5weQ"
}

Each entry has:

• path: relative to the workspace root, ready for the read and write routes.
• type: file, directory, symlink, or other (a FIFO, socket, or device). The listing never follows a symlink, so a symlink's target is never listed or hashed.
• size: bytes for a regular file, 0 for every other type.
• mode: permission bits as a decimal number, including setuid, setgid, and sticky. 420 is 0644, and 493 is 0755.
• sha256: with include_sha256, the digest of a regular file's content.
• sha256_skipped: with include_sha256, why a regular file has no digest. Treat that file as unverified.
• unreadable: true on a directory the session user can't list. The listing doesn't enter it and goes on past it.
• unsupported_names: in a recursive listing, how many names directly inside a directory no entry can carry.

A directory is unreadable when the session user's permission bits on it lack read or execute: the owner bits when the user owns it, the group bits when it belongs to the user's group, and the other bits otherwise.

A name that isn't UTF-8, or whose path would pass 4096 bytes, can't be listed. The listing skips it and everything below it, and counts it in unsupported_names: on the directory's entry, or at the top of every page for path itself. The field is absent when there are none. A listing with any unsupported_names or unreadable directory is incomplete.

A file written in the last 100 milliseconds is hashed once it has gone that long unchanged, so a listing right after a write can take a moment longer.

The listing detects a change from the file's timestamps. A file that changes while it is hashed without its timestamps moving can get a digest of neither the old nor the new content. Two cases cause this: a single write still in progress 100 milliseconds after it began, which a heavily loaded session can cause, and a process writing through a shared memory mapping (mmap). When a digest must match finished content, list after the processes writing the file have finished.

Entries are sorted by path, comparing one path element at a time by bytes, so a directory comes right before its contents. A page ends early when it reaches the limit, about 8 MiB of entries, or 256 MiB of hashed file content. Keep requesting with cursor until the response has no next_cursor. A cursor is valid only for the project and session it came from. A listing is not a snapshot: a file that changes while it runs can appear before or after the change.

A project your credential cannot read answers 404 exactly like one that does not exist, and a session outside project_id answers like an unknown session. A credential for the project that lacks the sandboxes.files.read permission answers 403.

Sessions started on an image built before file listing shipped cannot list files. Start a new session; for a custom template, redeploy it first. This holds in local mode too.

Grant a signed-in user access

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. Project access tokens are restricted to their project and cannot manage end-user grants or issue port credentials. These restrictions also apply through the MCP server. A project auth-user JWT can only read, execute commands, access files, or connect to a session explicitly granted to that user. It cannot create, suspend, resume, terminate, or grant sessions. Anonymous keys are not accepted by these APIs.

An invalid or expired auth-user JWT returns 401; refresh the user's login and retry with the same execution key. A valid user without a matching grant or project scope receives 403, which token refresh does not resolve.

curl -X PUT "$VOLCANO_API_URL/sandbox-sessions/$SESSION_ID/grants/$AUTH_USER_ID" \
  -H "Authorization: Bearer $SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expires_at":"2026-09-23T13:00:00Z"}'

Use DELETE on the same endpoint to revoke the grant. Expiry is bounded by the session lifetime. The user's login must remain active. Scoped service keys also need the corresponding sandboxes.* permission; grant creation requires sandboxes.templates.write, and revocation requires sandboxes.terminate.

A plan-limit hold still allows platform users and service keys to suspend or terminate sessions and revoke grants. Creating or resuming sessions and adding grants remain blocked.

Connect to an HTTP service

Request a credential for one session and one application port:

curl "$VOLCANO_API_URL/sandbox-sessions/$SESSION_ID/access" \
  -H "Authorization: Bearer $SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"port":8080,"expires_in_seconds":300}'

The response contains url, token, and expires_at. Send the token as X-Volcano-Sandbox-Token when requesting that URL. Credentials expire within five minutes, and earlier if the parent login, grant, or session expires. Ports 65533 and above are reserved.

For browser navigation, submit the token in a form POST to {url}_volcano/access. The response sets a secure, HTTP-only, host-only cookie and redirects to /. Keep credentials out of query strings. The guest never receives the access header or reserved cookie. Volcano also removes client-sent X-Volcano-*, Forwarded, and X-Forwarded-* headers, and lookalikes that put _ or . in place of -, such as X_Forwarded_For. Application authorization headers, other headers such as X_Api_Key, and cookies remain available to the application.

Responses keep the application's own headers, such as Content-Security-Policy and X-Frame-Options, so a page loads its styles and images as it would when served directly. Browsers don't run scripts on these pages or frame other origins in them: Volcano adds Content-Security-Policy: script-src 'none'; object-src 'none'; frame-src 'self' to every response. Browsers don't store responses either: Volcano replaces the application's Cache-Control with private, no-store. Volcano also sets Strict-Transport-Security, makes application cookies host-only and secure, and removes Clear-Site-Data and any attempt to set the reserved cookie.

HTTP, WebSocket, SSE, and gRPC use the same authenticated URL. Revocation closes active connections; clients must obtain fresh access and reconnect after expiry.

Save a named Sandbox

POST /projects/{id}/sandboxes creates a named reference to a published preset:

{ "name": "analysis", "preset": "python3.12", "memory_mb": 2048 }

Include the authorization, content type, and idempotency headers shown above. Use the returned ID as sandbox_id in later session or execution requests. A named Sandbox keeps the preset image it was created with. To move to a later preset update, delete it and create it again with a new idempotency key. PATCH /projects/{id}/sandboxes/{sandboxId} changes its name. DELETE stops new sessions and requests termination of its existing sessions. You can reuse the name with a new idempotency key. Replaying the deleted Sandbox’s creation request returns 409 Conflict. Deleting a named Sandbox keeps the shared preset available to other Sandboxes.

List named Sandboxes, sessions, and deployment history with:

• GET /projects/{id}/sandboxes
• GET /projects/{id}/sandbox-sessions
• GET /projects/{id}/sandboxes/{sandboxId}/deployments

Lists return data and pagination. Pass pagination.next_cursor as cursor and keep limit unchanged; the default is 10, with a maximum of 100.

Cloud Sandbox runtime uses the included allowance and pricing described below.

Renaming a sandbox to an existing name in the same project returns 409 Conflict.

Run locally

Start your local environment with volcano start, then use the same Sandbox API at http://localhost:8000. Authenticate with the local service key from volcano status. Anonymous credentials remain rejected; signed-in users still need an explicit session grant.

Local app services still start if the Sandbox service cannot start. Sandbox APIs return 503 until that service is ready. Initialization retries in the background when the Sandbox service becomes available. If the service failed to start, fix local Docker access and run volcano start again. A local reset still requires successful Sandbox cleanup so running containers are not left behind.

Local mode includes python3.12 and node22 presets with 1024 or 2048 MB of memory. Use us-east-1 as the region. Docker Engine API 1.41 or newer is required. Sessions run in separate Docker containers with private workspaces. HTTP URLs use http://<session-id>--<port>.sandboxes.localhost:8000 and require Sandbox access credentials in the X-Volcano-Sandbox-Token request header. Browser cookie redemption requires HTTPS and is unavailable on local HTTP URLs.

Custom templates use the same deployment API and Dockerfile contract in local mode. Volcano builds a local image, validates startup, commands, and suspend/resume, then activates it. A service that exits or fails to become ready within 30 seconds fails validation; the deployment logs include the reason. Build logs and original source downloads remain available through the deployment endpoints. Builds and sessions use your local machine; custom images are removed after replacement or deletion once their sessions end. A local reset also removes custom images. Local mode does not support Git source handover or project source export. Even with LOCAL_MODE_GIT_DEPLOY_WORKER=true, the local Git worker deploys Functions and frontends only; it does not discover or deploy Sandbox directories. Deploy local custom Sandboxes through the API or CLI.

Local sessions and commands default to unlimited time. Set either time field to a positive value to limit it; the cloud eight-hour limit does not apply. Suspending pauses the container and retains its memory and files. Stopping or restarting the local server, restarting the Sandbox service, or running volcano reset terminates existing sessions. Local mode supports up to four sessions per owner and 8 GiB of total reserved memory. Containers share the local Docker kernel; use hosted Sandboxes when you need VM isolation.

Pricing and usage

Runtime is configured baseline memory multiplied by confirmed running time. One GBh is 1 GiB running for one hour. Metering retains millisecond precision; rounding the displayed number does not round the charged usage. Idle running time counts; multiple commands in one session do not multiply the runtime. Automatic resource expansion is allowed and has no additional charge. Readiness alone does not make an uncertain interval billable.

Snapshot creation, restoration and retained suspended storage are included. Suspended time consumes neither runtime allowance nor credits. Local sessions and platform image-validation sessions are not billed. Existing preview sessions stay unbilled; sessions admitted after the pricing release are billed. Preview history is never charged retroactively.

HOBBY exhaustion refuses starts and resumes with 429 sandbox_allowance_exhausted. The worker suspends running sessions on its next allowance check. Enforcement is asynchronous, so observed usage can finish slightly above the allowance without creating HOBBY overage charges. Allowance-paused sessions are retained for up to one hour, bounded by their original expiry, then terminated. Resume explicitly after a new allowance cycle or upgrade; workloads do not restart automatically. Requests exceeding the plan's memory, lifetime or concurrency limit return 403 sandbox_plan_limit_exceeded. Termination remains available.

Platform image-validation sessions do not count toward the plan concurrency limit. They still reserve physical capacity; suspended customer sessions count until termination is confirmed.

SUPERAGENT overage uses the shared credits balance and existing arrears policy. Unused purchased block capacity carries forward; included allowance does not. Account-wide billing usage appears on the billing page. The project counters below also expose unbilled preview and uncertain observations for diagnostics.

Inspect project runtime

curl "$VOLCANO_API_URL/projects/$PROJECT_ID/usage" \
  -H "Authorization: Bearer $VOLCANO_TOKEN"

The metrics array includes these runtime counters. Agents can read the same response with the get_project_usage MCP tool:

These diagnostic counters are not an invoice. Running includes time between commands and idle HTTP requests. Several commands in one session do not multiply its runtime. Paused sessions do not accumulate running usage. Local sessions do not contribute cloud usage.

Totals cover the current UTC calendar month; all_time is cumulative. Hourly and daily series use the same units. Measurements retain milliseconds and round down after aggregation for display. State changes and observation gaps are estimates: unconfirmed transitions and gaps longer than 30 seconds appear as uncertain usage. Usage stops accumulating at the session's expiry, even if cleanup or confirmation takes longer. Elastic CPU/memory consumption, snapshot bytes, build costs, and outbound transfer are not included in these counters.

Use the CLI and SDKs

The CLI exposes the same commands locally and in the cloud:

volcano sandboxes exec --preset python3.12 -- python -c 'print(42)'
volcano cloud sandboxes exec --preset python3.12 -- python -c 'print(42)'

See CLI Sandboxes for sessions, files, saved templates, and request IDs. See JavaScript Sandboxes, Python Sandboxes, and Ruby Sandboxes for the client.sandboxes facade, binary files, scoped HTTP credentials, and automatic session cleanup in each language.

Manage sessions in the Dashboard

Select a project and open Sandboxes. The Sessions view lists each session's state, region, and expiry. Choose a preset, memory size, and region to start a session. Suspend a running session to retain its processes and files; resume it before running another command. Termination requires confirmation and permanently removes the session's files.

The Templates view saves named preset and memory combinations. Deleting a template terminates its sessions and permanently removes their files. Lists support pagination and refresh.

Deploy a custom template

Service keys need sandboxes.deployments.write to upload a deployment and sandboxes.deployments.read to read its status, history, source, and build logs. Template-edit permission alone does not grant deployment access. Where custom templates are not enabled, a deployment request returns 404 with code feature_unavailable.

Place a Dockerfile fragment and its files in a directory. Volcano supplies the base image and supervisor. The base image is Amazon Linux 2023 on arm64 in the cloud; local mode uses your machine's architecture. Compile binaries in a RUN step so they match either one. A binary built elsewhere and copied in must target linux/arm64 for the cloud and your machine's architecture for local mode. Use RUN, COPY, ENV, WORKDIR within /workspace, and CMD; omit FROM, ENTRYPOINT, and USER. Use JSON-array CMD to pass arguments literally, without shell expansion. Shell-form CMD explicitly runs a shell and supports expansion and pipelines. Local builds resolve the startup executable using the template's PATH and pin it in the image; startup runs with the declared arguments and working directory.

RUN dnf install -y python3.12 && dnf clean all
COPY app.py /workspace/app.py
CMD ["python3.12", "/workspace/app.py"]

SANDBOX_ID=$(uuidgen)
REQUEST_ID=$(uuidgen)
tar -czf source.tar.gz Dockerfile app.py
curl -X POST "$VOLCANO_API_URL/projects/$PROJECT_ID/sandboxes/$SANDBOX_ID/deployments" \
  -H "Authorization: Bearer $SERVICE_KEY" \
  -H "Idempotency-Key: $REQUEST_ID" \
  -F name=my-service -F code=@source.tar.gz \
  -F memory_mb=1024 -F 'ports=[8080]'

The archive must be at most 32 MiB compressed and expanded, with at most 4,096 entries. Symlinks, traversal paths, and reserved managed files are rejected. Declared ports must accept connections before the deployment activates. Ports 65533 and 65534 are reserved.

The response is 202 with the deployment's id, status, created_at, and updated_at. Poll GET /projects/{id}/sandboxes/{sandboxId}/deployments/{deploymentId} until status is active. A new template remains unavailable until its first successful activation. Updates preserve the active template and existing sessions while the replacement builds. Reuse the same template ID for updates, with a new idempotency key. Reusing a key for different content returns 409. If an upload is interrupted or returns a temporary error, retry the same key and content. An incomplete upload reserves the template for 30 minutes from the first attempt; a different key returns 409 during that window. After it expires, start a new upload with a new key. The expired upload cannot finish later and replace the new deployment. Exporting the project to Git also releases an incomplete platform upload. Once accepted, retries keep returning the same deployment, even after a platform update.

Git deployments wait for an earlier build to finish, checking less frequently as the wait grows, for up to two hours. An earlier deployment in unknown requires operator recovery, so a new Git deployment fails immediately instead of waiting.

Create sessions with sandbox_id after activation. Sessions retain the exact image they started with even when a later deployment activates.

In the cloud, Volcano starts your CMD service once while it builds the template, then starts every session from a saved copy of that running service, memory included. Anything the service creates at startup is the same in many sessions: random tokens, keys, IDs, and random generators seeded at startup. Create those values when a session first needs them, and read randomness from the operating system at that point, for example with Python secrets or Go crypto/rand. Local mode starts CMD separately in each session.

When a session starts, Volcano reseeds the operating system's random generator, so reads from it differ between sessions. A custom template or named Sandbox keeps the image it was saved with: redeploy the template, or delete and recreate the named Sandbox, to pick this up. A process that was already running when the copy was saved keeps its own in-memory generator, such as OpenSSL's or a language's seeded random module, and can return the same values in many sessions. Start such processes after the session starts, or reseed them then.

Don't build secrets into a template. Its files, ENV values, and startup memory are shared by every session. Pass a secret after the session starts, in the environment field of an exec request or as a file written with the files API.

Read build logs with GET /projects/{id}/sandboxes/{sandboxId}/deployments/{deploymentId}/logs?region=aws-us-east-1. The response contains data entries with timestamp and message. Supply the returned next_cursor as cursor to continue; limit defaults to 100 and accepts up to 1,000 entries. Read each deployment region separately.

Download the retained source with GET /projects/{id}/sandboxes/{sandboxId}/deployments/{deploymentId}/source. A successfully activated custom deployment returns the original tar.gz bytes, without injected platform files. Its source remains available after a newer deployment activates and after its old runtime images are reclaimed, while the template remains available to your project. Project source export includes only each custom template’s active deployment under volcano/sandboxes/<name>/, using the same immutable source version.