veryfront/sandbox

Import

import {
  createAgentServiceSandboxClient,
  createAgentServiceSandboxTools,
  createProjectScopedExecOptions,
  createSandboxShellTools,
  normalizeBashToolSet,
  renameSandboxFileTools,
} from "veryfront/sandbox";

Examples

import { Sandbox } from "veryfront/sandbox";

const sandbox = await Sandbox.create();
const result = await sandbox.executeCommand("echo hello");
console.log(result.stdout); // "hello\n"
await sandbox.close();

API

`Sandbox.create()`

Create a new sandbox session. Claims a warm pod or creates a new one. Returns: Promise<Sandbox>

`Sandbox.get(id, )`

Reconnect to an existing sandbox session. Returns: Promise<Sandbox>

`Sandbox.attach(attachment)`

Attach to an already-known sandbox session and endpoint without a reconnect lookup. Returns: Sandbox

`Sandbox.list()`

List sandbox sessions with optional pagination. Returns: Promise<SandboxListResult>

`Sandbox.createLazy()`

Create a lazily-provisioned sandbox session with automatic heartbeats. Returns: LazySandbox

`sandbox.executeCommand(command, options)`

Execute a bash command in the sandbox and return buffered result. Returns: Promise<ExecResult>

`sandbox.executeStream(command, options)`

Execute a bash command with streaming output (NDJSON). Returns: AsyncGenerator<ExecStreamEvent>

`sandbox.readFile(path)`

Read a file from the sandbox workspace. Returns: Promise<string>

`sandbox.writeFiles(files)`

Write files to the sandbox workspace. Returns: Promise<void>

`sandbox.startBackgroundCommand(command, options)`

Start an async background command in the sandbox. Returns: Promise<BackgroundCommand>

`sandbox.getBackgroundCommand(commandId)`

Get the status of an async background command. Returns: Promise<BackgroundCommand>

`sandbox.getBackgroundCommandOutput(commandId)`

Get the output of an async background command. Returns: Promise<BackgroundCommandOutput>

`sandbox.listBackgroundCommands()`

List all background commands in the sandbox. Returns: Promise<BackgroundCommand[]>

`sandbox.cancelBackgroundCommand(commandId)`

Cancel an async background command. Returns: Promise<BackgroundCommand>

`sandbox.heartbeat()`

Send a heartbeat to prevent idle timeout. Returns: Promise<void>

`sandbox.close()`

Close the sandbox session and mark for deletion. Returns: Promise<void>

`sandbox.id`

Get the session ID. Returns: string

`sandbox.url`

Get the sandbox endpoint URL. Returns: string

Type Reference

`SandboxOptions`

Options for creating a sandbox session.

Property	Type	Description	Source
`apiUrl?`	`string`	Base URL of the Veryfront API. Defaults to VERYFRONT_API_URL, then the Veryfront Cloud API.	source
`authToken?`	`string`	Explicit Veryfront auth token or API key override.	source
`projectId?`	`string`	Optional project context for project-billed / project-scoped sandbox sessions.	source

`ExecResult`

Result of a command execution: stdout, stderr, and exit code.

Property	Type	Description	Source
`stdout`	`string`	Buffered standard output from command execution.	source
`stderr`	`string`	Buffered standard error from command execution.	source
`exitCode`	`number`	Process exit code.	source

`ExecStreamEvent`

Streaming event emitted during command execution.

Property	Type	Description	Source
`type`	`"stdout" \| "stderr" \| "exit" \| "error"`	Event type (`stdout`, `stderr`, `exit`, `error`).	source
`data?`	`string`	Chunk payload for stdout/stderr/error events.	source
`exitCode?`	`number`	Exit code for `exit` events.	source

Exports

Functions

Name	Description	Source
`createAgentServiceSandboxClient`	Create agent service sandbox client.	source
`createAgentServiceSandboxTools`	Create agent service sandbox tools.	source
`createProjectScopedExecOptions`	Options accepted by create project scoped exec.	source
`createSandboxShellTools`	Create sandbox shell tools.	source
`normalizeBashToolSet`	Normalizes bash tool set.	source
`renameSandboxFileTools`	Rename sandbox file tools.	source
`resolveDefaultSandboxRuntimeEndpoint`	Resolves default sandbox runtime endpoint.	source
`unwrapSandboxWorkingDirectoryCommand`	Unwrap sandbox working directory command.	source

Classes

Name	Description	Source
`LazySandbox`	Lazily provisions sandbox sessions and keeps them alive while in use.	source
`Sandbox`	Client for isolated ephemeral compute environments with command execution and file I/O.	source

Types

Name	Description	Source
`AgentServiceSandboxBackgroundCommandClient`	Public API contract for agent service sandbox background command client.	source
`AgentServiceSandboxClient`	Public API contract for agent service sandbox client.	source
`AgentServiceSandboxClientOptions`	Options accepted by agent service sandbox client.	source
`AgentServiceSandboxToolsOptions`	Options accepted by agent service sandbox tools.	source
`AgentServiceSandboxToolsResult`	Result returned from agent service sandbox tools.	source
`BackgroundCommand`	An async background command running in a sandbox.	source
`BackgroundCommandHeartbeatStatus`	Heartbeat health status for a background command.	source
`BackgroundCommandOutput`	A background command with its captured output.	source
`BackgroundCommandStatus`	Status of an async background command.	source
`BashToolSandboxLike`	Public API contract for sandbox shell client.	source
`CreateSandboxBashTool`	Public API contract for sandbox shell tools provider.	source
`ExecOptions`	Options for command execution: working directory, timeout, environment variables, and optional project reference.	source
`ExecResult`	Result of a command execution: stdout, stderr, and exit code.	source
`ExecStreamEvent`	Streaming event emitted during command execution.	source
`HostedSandboxBackgroundCommandClient`	Public API contract for hosted sandbox background command client.	source
`HostedSandboxClient`	Public API contract for hosted sandbox client.	source
`HostedSandboxClientOptions`	Options accepted by hosted sandbox client.	source
`HostedSandboxToolsOptions`	Options accepted by hosted sandbox tools.	source
`HostedSandboxToolsResult`	Result returned from hosted sandbox tools.	source
`LazySandboxOptions`	Options accepted by lazy sandbox.	source
`SandboxAttachment`	Known sandbox session connection details used to attach without a lookup round-trip.	source
`SandboxListOptions`	Options for listing sandbox sessions.	source
`SandboxListResult`	Paginated result of sandbox sessions.	source
`SandboxOptions`	Options for creating a sandbox session.	source
`SandboxSession`	A sandbox session summary returned by list.	source
`SandboxShellToolDefinition`	Definition for sandbox shell tool.	source
`SandboxShellToolSet`	Public API contract for sandbox shell tool set.	source

Constants

Name	Description	Source
`createHostedSandboxClient`	Create hosted sandbox client.	source
`createHostedSandboxTools`	Create hosted sandbox tools.	source

Getting Started

Concepts

Guides

API Reference

Import

Examples

API

`Sandbox.create()`

`Sandbox.get(id, )`

`Sandbox.attach(attachment)`

`Sandbox.list()`

`Sandbox.createLazy()`

`sandbox.executeCommand(command, options)`

`sandbox.executeStream(command, options)`

`sandbox.readFile(path)`

`sandbox.writeFiles(files)`

`sandbox.startBackgroundCommand(command, options)`

`sandbox.getBackgroundCommand(commandId)`

`sandbox.getBackgroundCommandOutput(commandId)`

`sandbox.listBackgroundCommands()`

`sandbox.cancelBackgroundCommand(commandId)`

`sandbox.heartbeat()`

`sandbox.close()`

`sandbox.id`

`sandbox.url`

Type Reference

`SandboxOptions`

`ExecResult`

`ExecStreamEvent`

Exports

Functions

Classes

Types

Constants

​Import

​Examples

​API

​Sandbox.create()

​Sandbox.get(id, )

​Sandbox.attach(attachment)

​Sandbox.list()

​Sandbox.createLazy()

​sandbox.executeCommand(command, options)

​sandbox.executeStream(command, options)

​sandbox.readFile(path)

​sandbox.writeFiles(files)

​sandbox.startBackgroundCommand(command, options)

​sandbox.getBackgroundCommand(commandId)

​sandbox.getBackgroundCommandOutput(commandId)

​sandbox.listBackgroundCommands()

​sandbox.cancelBackgroundCommand(commandId)

​sandbox.heartbeat()

​sandbox.close()

​sandbox.id

​sandbox.url

​Type Reference

​SandboxOptions

​ExecResult

​ExecStreamEvent

​Exports

​Functions

​Classes

​Types

​Constants

Import

Examples

API

`Sandbox.create()`

`Sandbox.get(id, )`

`Sandbox.attach(attachment)`

`Sandbox.list()`

`Sandbox.createLazy()`

`sandbox.executeCommand(command, options)`

`sandbox.executeStream(command, options)`

`sandbox.readFile(path)`

`sandbox.writeFiles(files)`

`sandbox.startBackgroundCommand(command, options)`

`sandbox.getBackgroundCommand(commandId)`

`sandbox.getBackgroundCommandOutput(commandId)`

`sandbox.listBackgroundCommands()`

`sandbox.cancelBackgroundCommand(commandId)`

`sandbox.heartbeat()`

`sandbox.close()`

`sandbox.id`

`sandbox.url`

Type Reference

`SandboxOptions`

`ExecResult`

`ExecStreamEvent`

Exports

Functions

Classes

Types

Constants