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.
A sandbox is an isolated runtime workspace for project operations that need a shell, files, or long-running command execution without sharing state with the main application process.
Use sandboxes for code generation, repository inspection, file transformation, browser automation, document processing, and agent tools that need a temporary workspace.
Lifecycle
A sandbox session starts as a project-scoped runtime allocation, moves through provisioning, becomes running when its runtime is ready, and closes when the caller deletes it or the platform reclaims it.
| State | Meaning |
|---|
pending | Veryfront accepted the session request and queued runtime allocation. |
provisioning | The runtime is starting and preparing the workspace. |
running | The runtime accepts commands, jobs, file operations, and terminal connections. |
error | The runtime failed to start or became unavailable. |
deleting | The session is closing and no longer accepts new work. |
Runtime status
Use runtime status to decide which actions to show. A running session can still be temporarily unready while the runtime starts services or recovers from a transient error.
Check readiness before long commands, file operations, or terminal handoff. Show provisioning and error states inline so users know whether to wait, retry, or create a new session.
Terminal access
Terminal access opens an interactive shell inside the sandbox workspace. Use it for exploratory debugging, one-off inspection, or workflows where streamed command output is easier to follow than a buffered command result.
Keep terminal access project-scoped and authenticated. Don’t expose sandbox endpoints or tokens to unauthenticated browser contexts.
Command execution
Synchronous command execution runs a shell command and returns buffered stdout, stderr, and exitCode. Use it for short commands where the caller can wait for the complete result.
Use synchronous execution for:
- Inspecting a directory or file
- Running a formatter on a small set of files
- Checking tool availability
- Running a quick validation command
Set a timeout for commands that can hang. For long-running commands, use async jobs instead.
Async jobs
Async command jobs start work in the sandbox and return a job record that can be listed, inspected, and canceled later. Use jobs for commands that take longer than an interactive request budget or need durable progress tracking.
| Job action | Use |
|---|
| Start | Queue a long-running command in the sandbox runtime. |
| List | Show recent jobs for the selected session. |
| Output | Read captured stdout, stderr, and exit status. |
| Cancel | Stop a running job when the work is no longer needed. |
File access and directory browsing
Sandbox file access is rooted in the workspace. Paths resolve through the runtime path guard and cannot traverse outside the workspace.
Use file operations for:
- Listing workspace directories
- Reading generated files
- Writing input files before a command runs
- Inspecting job output artifacts
Directory browsing returns each entry’s name, path, type, and file size when available. Use directory rows to open deeper paths, and file rows to read exact file content or reuse a path in write and command workflows.
Agents use sandboxes when they need a real filesystem, command-line tools, or external runtimes. A sandbox tool can create a session lazily, run commands, write files, inspect results, and close the session when the agent run ends.
Prefer lazy session creation for agents that may not need runtime work on every turn. Pass project context so billing, isolation, and audit trails stay attached to the right project.
Security and isolation
Sandbox sessions are ephemeral and authenticated. Treat them as project runtime resources, not public compute endpoints.
- Keep auth tokens server-side.
- Scope sessions to the project that owns the work.
- Reject path traversal and absolute paths that leave the workspace.
- Close idle sessions when work completes.
- Store only artifacts that the project needs after the session ends.
API surfaces
Next
- Runtime: Find where sandboxes fit with jobs, tasks, workflows, and runs.
- Code sandbox guide: Use the sandbox client from application code.
- MCP: Expose sandbox operations to MCP clients.
