veryfront/sandbox - Veryfront

Import

sandbox.ts

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

Examples

sandbox.ts

import { Sandbox } from "veryfront/sandbox";

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

API

`Sandbox.create()`

Create an isolated sandbox workspace. Returns: Promise<Sandbox>

`Sandbox.get(id, )`

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

`Sandbox.attach(attachment)`

Attach to an existing sandbox. Closing detaches; use delete() to remove it. Returns: Sandbox

`Sandbox.capabilities()`

Get sandbox capabilities, limits and defaults for the current caller. Returns: Promise<SandboxCapabilities>

`sandbox.checkHealth()`

Check runtime health without recording activity. Returns: Promise<SandboxRuntimeCheck>

`sandbox.checkReadiness()`

Check command readiness without recording activity. Returns: Promise<SandboxRuntimeCheck>

`sandbox.getEnvironment()`

Get environment variable names with redacted values. Returns: Promise<SandboxEnvironment>

`sandbox.listFiles()`

Read one directory page. Supply pageInfo.next as cursor for another page. Returns: Promise<SandboxFileListResult>

`sandbox.updateLifetime(input)`

Update cleanup policy without changing access or storage. Returns: Promise<SandboxDetails>

`Sandbox.list()`

List sandboxes with optional pagination. Returns: Promise<SandboxListResult>

`Sandbox.createLazy()`

Create a client that provisions its sandbox when first used. Returns: LazySandbox

`sandbox.runCommand(command, options)`

Execute a bash command in the sandbox and return buffered stdout/stderr plus the exit code. Returns: Promise<CommandResult>

`sandbox.streamCommand(command, options)`

Execute a bash command in the sandbox and stream newline-delimited JSON (NDJSON) output events as they arrive. Returns: AsyncGenerator<CommandStreamEvent>

`sandbox.readFile(path)`

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

`sandbox.writeFiles(files)`

Write one or more 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()`

Record activity for idle cleanup. Fixed expiry does not change. Returns: Promise<void>

`sandbox.close()`

Close the client. Existing and persistent sandboxes remain; temporary sandboxes created by this client are deleted. Returns: Promise<void>

`sandbox.delete()`

Delete the sandbox and its workspace files. Returns: Promise<void>

`sandbox.id`

Get the sandbox ID. Returns: string

`sandbox.url`

Get the sandbox endpoint URL. Returns: string

Type Reference

`SandboxOptions`

Options for creating a sandbox.

Property	Type	Description	Source
`apiUrl?`	`string`	Base URL of the Veryfront API. Set apiUrl or VERYFRONT_API_URL outside a scoped Veryfront Cloud context.	source
`authToken?`	`string`	Explicit Veryfront auth token or API key override.	source
`projectReference?`	`string`	Project UUID or slug used for billing.	source
`accessScope?`	`SandboxAccessScope`	Project access or creator-only access. Defaults to project.	source
`ttlMode?`	`SandboxLifetimeMode`	Cleanup policy. Defaults to default.	source
`ttlHours?`	`number`	Required only for duration cleanup.	source
`environmentId?`	`string`	Environment whose variables are copied once.	source

`CommandResult`

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

`CommandStreamEvent`

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
`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`	Provisions a sandbox when first used and records activity while the client is active.	source
`Sandbox`	Client for isolated coding workspaces 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
`CommandOptions`	Options for command execution: working directory, timeout, environment variables.	source
`CommandResult`	Result of a command execution: stdout, stderr, and exit code.	source
`CommandStreamEvent`	Streaming event emitted during command execution.	source
`CreateSandboxBashTool`	Public API contract for sandbox shell tools provider.	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
`SandboxAccessScope`	Sandbox access, storage and lifetime policies.	source
`SandboxAttachment`	Known sandbox connection details used to attach without a lookup round-trip.	source
`SandboxCapabilities`	Sandbox creation capabilities, limits and defaults for the current caller.	source
`SandboxClientOptions`		source
`SandboxDetails`	A sandbox summary returned by list.	source
`SandboxEnvironment`	Snapshot of environment variable names with redacted values.	source
`SandboxFileEntry`	Directory entry metadata, without file contents.	source
`SandboxFileListOptions`	Directory listing options.	source
`SandboxFileListResult`	One directory page. Follow pageInfo.next to request another page.	source
`SandboxLifetimeInput`	Sandbox cleanup policy. Duration requires hours; other policies accept no duration.	source
`SandboxLifetimeMode`		source
`SandboxListOptions`	Options for listing sandboxes.	source
`SandboxListResult`	Paginated result of sandboxes.	source
`SandboxOptions`	Options for creating a sandbox.	source
`SandboxRuntimeCheck`	Runtime health or readiness result. A false check is a result, not a transport error.	source
`SandboxShellToolDefinition`	Definition for sandbox shell tool.	source
`SandboxShellToolSet`	Public API contract for sandbox shell tool set.	source
`SandboxStatus`	Observed sandbox runtime state.	source
`SandboxWorkspaceStorage`		source

Constants

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

​Import

​Examples

​API

​Sandbox.create()

​Sandbox.get(id, )

​Sandbox.attach(attachment)

​Sandbox.capabilities()

​sandbox.checkHealth()

​sandbox.checkReadiness()

​sandbox.getEnvironment()

​sandbox.listFiles()

​sandbox.updateLifetime(input)

​Sandbox.list()

​Sandbox.createLazy()

​sandbox.runCommand(command, options)

​sandbox.streamCommand(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.delete()

​sandbox.id

​sandbox.url

​Type Reference

​SandboxOptions

​CommandResult

​CommandStreamEvent

​Exports

​Functions

​Classes

​Types

​Constants