> ## Documentation Index
> Fetch the complete documentation index at: https://veryfront.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox API

> How isolated sessions connect commands, files, terminals, and lifetime policies.

The Sandbox API provides isolated command environments and filesystems. Use a session for repository inspection, code execution, file processing, or an agent tool that needs a workspace.

## Sessions and lifetime

The session ID connects commands, files, and terminal access to the same environment. A created session must become ready before it can accept work.

| State | Meaning |
| - | - |
| `pending` | The request was accepted. |
| `provisioning` | The runtime is starting. |
| `running` | Commands and file operations are available. |
| `error` | The runtime failed or became unavailable. |
| `deleting` | The session is closing. |

A lifetime policy limits how long the session remains available. A heartbeat updates activity for idle-timeout handling; it does not replace that policy. Copy out artifacts you need before the session is deleted or expires.

## Commands and terminals

A command can run synchronously, stream output, or continue in the background. Background commands have IDs for reading status and output or requesting cancellation. A WebSocket terminal provides interactive access to the same environment.

Command streams use newline-delimited JSON (`application/x-ndjson`). They are separate from the SSE run-event streams in the [Execution API](/docs/cloud/apis/execution).

## Files and project context

File operations address the selected session's filesystem. Session files are separate from project source and uploads, which belong to the [Projects API](/docs/cloud/apis/projects).

Project context identifies the billing project. An environment can supply a snapshot of variables at session creation; later configuration changes do not automatically update an existing session.

For example, a support agent can use a sandbox to inspect an attached file. The session holds the working files, while the agent run records execution progress. Their IDs, lifetimes, and results remain separate.

## Get started

[Run a command in a sandbox](/docs/cloud/runtime) covers session creation, readiness, execution, and cleanup. The [Veryfront Code sandbox guide](/docs/code/guides/sandbox) shows application-level usage.

## API references

* [REST endpoints](/docs/cloud/rest/apis/sandbox-api)
* [GraphQL queries and mutations](/docs/cloud/graphql/apis/sandbox)
* [MCP tools](/docs/cloud/mcp/apis/sandbox)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.