Skip to main content

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.

​
veryfront/sandbox

Sandbox module for ephemeral compute environments. Provides the Sandbox class for creating and interacting with isolated execution environments.

​
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.startCommandJob(command, options)

Start an async command job in the sandbox. Returns: Promise<CommandJob>

​
sandbox.getCommandJob(jobId)

Get the status of an async command job. Returns: Promise<CommandJob>

​
sandbox.getCommandJobOutput(jobId)

Get the output of an async command job. Returns: Promise<CommandJobOutput>

​
sandbox.listCommandJobs()

List all command jobs in the sandbox. Returns: Promise<CommandJob[]>

​
sandbox.cancelCommandJob(jobId)

Cancel an async command job. Returns: Promise<CommandJob>

​
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.
PropertyTypeDescriptionSource
apiUrl?stringBase URL of the Veryfront API. Defaults to VERYFRONT_API_URL, then the Veryfront Cloud API.source
authToken?stringExplicit Veryfront auth token or API key override.source
projectId?stringOptional project context for project-billed / project-scoped sandbox sessions.source

​
ExecResult

Result of a command execution: stdout, stderr, and exit code.
PropertyTypeDescriptionSource
stdoutstringBuffered standard output from command execution.source
stderrstringBuffered standard error from command execution.source
exitCodenumberProcess exit code.source

​
ExecStreamEvent

Streaming event emitted during command execution.
PropertyTypeDescriptionSource
type"stdout" | "stderr" | "exit" | "error"Event type (stdout, stderr, exit, error).source
data?stringChunk payload for stdout/stderr/error events.source
exitCode?numberExit code for exit events.source

​
Exports

​
Functions

NameDescriptionSource
createAgentServiceSandboxClientCreate agent service sandbox client.source
createAgentServiceSandboxToolsCreate agent service sandbox tools.source
createProjectScopedExecOptionsOptions accepted by create project scoped exec.source
createSandboxShellToolsCreate sandbox shell tools.source
normalizeBashToolSetNormalizes bash tool set.source
renameSandboxFileToolsRename sandbox file tools.source
resolveDefaultSandboxRuntimeEndpointResolves default sandbox runtime endpoint.source
unwrapSandboxWorkingDirectoryCommandUnwrap sandbox working directory command.source

​
Classes

NameDescriptionSource
LazySandboxLazily provisions sandbox sessions and keeps them alive while in use.source
SandboxClient for isolated ephemeral compute environments with command execution and file I/O.source

​
Types

NameDescriptionSource
AgentServiceSandboxClientPublic API contract for agent service sandbox client.source
AgentServiceSandboxClientOptionsOptions accepted by agent service sandbox client.source
AgentServiceSandboxJobClientPublic API contract for agent service sandbox job client.source
AgentServiceSandboxToolsOptionsOptions accepted by agent service sandbox tools.source
AgentServiceSandboxToolsResultResult returned from agent service sandbox tools.source
BashToolSandboxLikePublic API contract for sandbox shell client.source
CommandJobAn async command job running in a sandbox.source
CommandJobHeartbeatStatusHeartbeat health status for a command job.source
CommandJobOutputA command job with its captured output.source
CommandJobStatusStatus of an async command job.source
CreateSandboxBashToolPublic API contract for sandbox shell tools provider.source
ExecOptionsOptions for command execution: working directory, timeout, environment variables, and optional project reference.source
ExecResultResult of a command execution: stdout, stderr, and exit code.source
ExecStreamEventStreaming event emitted during command execution.source
HostedSandboxClientPublic API contract for hosted sandbox client.source
HostedSandboxClientOptionsOptions accepted by hosted sandbox client.source
HostedSandboxJobClientPublic API contract for hosted sandbox job client.source
HostedSandboxToolsOptionsOptions accepted by hosted sandbox tools.source
HostedSandboxToolsResultResult returned from hosted sandbox tools.source
LazySandboxOptionsOptions accepted by lazy sandbox.source
SandboxAttachmentKnown sandbox session connection details used to attach without a lookup round-trip.source
SandboxListOptionsOptions for listing sandbox sessions.source
SandboxListResultPaginated result of sandbox sessions.source
SandboxOptionsOptions for creating a sandbox session.source
SandboxSessionA sandbox session summary returned by list.source
SandboxShellToolDefinitionDefinition for sandbox shell tool.source
SandboxShellToolSetPublic API contract for sandbox shell tool set.source

​
Constants

NameDescriptionSource
createHostedSandboxClientCreate hosted sandbox client.source
createHostedSandboxToolsCreate hosted sandbox tools.source
Reference modules: User guides:
  • sandbox: Run code in isolated sandbox environments
Architecture: