> ## 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 runtime

> Run isolated workspace sessions for commands, files, jobs, and agent tools.

A sandbox runtime is an isolated workspace for project work.

Use it when work needs files, shell commands, or long-running execution.

## Use this for

| Work                  | Needs                                 |
| --------------------- | ------------------------------------- |
| Repository inspection | Filesystem and shell access.          |
| Code generation       | Read, write, and test files.          |
| File transformation   | Workspace-local reads and writes.     |
| Browser automation    | Runtime tools and command execution.  |
| Agent tools           | Isolated command and file operations. |

## Lifecycle

| State          | Meaning                                           |
| -------------- | ------------------------------------------------- |
| `pending`      | Veryfront accepted the request.                   |
| `provisioning` | The runtime is starting.                          |
| `running`      | The runtime accepts commands and file operations. |
| `error`        | The runtime failed or became unavailable.         |
| `deleting`     | The session is closing.                           |

Close sessions when work finishes so runtime capacity returns to the pool.

## Work surfaces

| Surface             | Use it for                                            |
| ------------------- | ----------------------------------------------------- |
| Terminal            | Interactive debugging and exploratory commands.       |
| Synchronous command | Short commands with buffered output.                  |
| Async command job   | Long-running commands with durable status and output. |
| File access         | Read, write, and inspect workspace files.             |

## Agent and tool use

Agents use sandboxes when they need a real filesystem, command-line tools, or external runtimes.

Create a session when an agent tool first needs one.

Pass project context so billing, isolation, and audit trails stay attached to the right project.

## Security

* Keep auth tokens server-side.
* Scope sessions to the project that owns the work.
* Reject paths outside the workspace.
* Close idle sessions.
* Store only artifacts the project needs after the session ends.

## API reference

| API                          | Start here                                       |
| ---------------------------- | ------------------------------------------------ |
| [REST](/cloud/rest)          | Sandbox sessions and command jobs.               |
| [GraphQL](/cloud/graphql)    | Sandbox session queries and mutations.           |
| [MCP](/cloud/mcp)            | Sandbox tools for assistants.                    |
| [Code](/code/guides/sandbox) | Use `veryfront/sandbox` in a Veryfront Code app. |