veryfront/sandbox

Import

ts
import {
  createAgentServiceSandboxClient,
  createAgentServiceSandboxTools,
  createHostedSandboxClient,
  createHostedSandboxTools,
  createSandboxShellTools,
  normalizeBashToolSet,
} from "veryfront/sandbox";

Examples

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: <code>Promise<Sandbox></code>

Sandbox.get(id, )

Reconnect to an existing sandbox session.

Returns: <code>Promise<Sandbox></code>

Sandbox.attach(attachment)

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

Returns: Sandbox

Sandbox.capabilities()

Get platform features or selected-project creation eligibility. Creation rechecks capacity.

Returns: <code>Promise<SandboxCapabilities></code>

sandbox.checkHealth()

Check runtime health without recording activity.

Returns: <code>Promise<SandboxRuntimeCheck></code>

sandbox.checkReadiness()

Check command readiness without recording activity.

Returns: <code>Promise<SandboxRuntimeCheck></code>

sandbox.getEnvironment()

Get environment variable names with redacted values.

Returns: <code>Promise<SandboxEnvironment></code>

sandbox.listFiles()

Read one directory page. Supply pageInfo.next as cursor for another page.

Returns: <code>Promise<SandboxFileListResult></code>

sandbox.updateLifetime(input)

Update cleanup policy without changing access or storage.

Returns: <code>Promise<SandboxDetails></code>

Sandbox.list()

List sandboxes with optional pagination.

Returns: <code>Promise<SandboxListResult></code>

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: <code>Promise<CommandResult></code>

sandbox.streamCommand(command, options)

Execute a bash command in the sandbox and stream newline-delimited JSON (NDJSON) output events as they arrive.

Returns: <code>AsyncGenerator<CommandStreamEvent></code>

sandbox.readFile(path)

Read a file from the sandbox workspace.

Returns: <code>Promise<string></code>

sandbox.writeFiles(files, options)

Write one or more files to the sandbox workspace.

Returns: <code>Promise<void></code>

sandbox.startBackgroundCommand(command, options)

Start an async background command in the sandbox.

Returns: <code>Promise<BackgroundCommand></code>

sandbox.getBackgroundCommand(commandId)

Get the status of an async background command.

Returns: <code>Promise<BackgroundCommand></code>

sandbox.getBackgroundCommandOutput(commandId)

Get the output of an async background command.

Returns: <code>Promise<BackgroundCommandOutput></code>

sandbox.listBackgroundCommands()

List all background commands in the sandbox.

Returns: <code>Promise<BackgroundCommand[]></code>

sandbox.cancelBackgroundCommand(commandId, )

Cancel an async background command.

Returns: <code>Promise<BackgroundCommand></code>

sandbox.heartbeat()

Record activity for idle cleanup. Fixed expiry does not change.

Returns: <code>Promise<void></code>

sandbox.close()

Close the client. Existing and persistent sandboxes remain; temporary sandboxes created by this client are deleted.

Returns: <code>Promise<void></code>

sandbox.delete()

Delete the sandbox and its workspace files.

Returns: <code>Promise<void></code>

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.

PropertyTypeDescriptionSource
apiUrl?stringBase URL of the Veryfront API. Set apiUrl or VERYFRONT_API_URL outside a scoped Veryfront Cloud context.source
authToken?stringExplicit Veryfront auth token or API key override.source
getAuthToken?<code>() => string</code>Read the current credential before each request when the host renews it.source
signal?AbortSignalCancel sandbox provisioning and readiness polling.source
projectReference?stringProject UUID or slug used for billing.source
accessScope?SandboxAccessScopeProject access or creator-only access. Defaults to project.source
ttlMode?SandboxLifetimeModeCleanup policy. Defaults to default.source
ttlHours?numberRequired only for duration cleanup.source
environmentId?stringEnvironment whose variables are copied once.source

CommandResult

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

CommandStreamEvent

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
createHostedSandboxClientCreate hosted sandbox client.source
createHostedSandboxToolsCreate hosted sandbox tools.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
LazySandboxProvisions a sandbox when first used and records activity while the client is active.source
SandboxClient for isolated coding workspaces with command execution and file I/O.source

Types

NameDescriptionSource
AgentServiceSandboxBackgroundCommandClientPublic API contract for agent service sandbox background command client.source
AgentServiceSandboxClientPublic API contract for agent service sandbox client.source
AgentServiceSandboxClientOptionsOptions accepted by agent service sandbox client.source
AgentServiceSandboxToolsOptionsOptions accepted by agent service sandbox tools.source
AgentServiceSandboxToolsResultResult returned from agent service sandbox tools.source
BackgroundCommandAn async background command running in a sandbox.source
BackgroundCommandHeartbeatStatusHeartbeat health status for a background command.source
BackgroundCommandOutputA background command with its captured output.source
BackgroundCommandStatusStatus of an async background command.source
BashToolSandboxLikePublic API contract for sandbox shell client.source
CommandOptionsOptions for command execution: working directory, timeout, environment variables.source
CommandResultResult of a command execution: stdout, stderr, and exit code.source
CommandStreamEventStreaming event emitted during command execution.source
CreateSandboxBashToolPublic API contract for sandbox shell tools provider.source
HostedSandboxBackgroundCommandClientPublic API contract for hosted sandbox background command client.source
HostedSandboxClientPublic API contract for hosted sandbox client.source
HostedSandboxClientOptionsOptions accepted by hosted sandbox client.source
HostedSandboxToolsOptionsOptions accepted by hosted sandbox tools.source
HostedSandboxToolsResultResult returned from hosted sandbox tools.source
LazySandboxOptionsOptions accepted by lazy sandbox.source
SandboxAccessScopeSandbox access, storage and lifetime policies.source
SandboxAttachmentKnown sandbox connection details used to attach without a lookup round-trip.source
SandboxCapabilitiesSandbox creation options, limits and defaults. A project selector opts into caller eligibility.source
SandboxCapabilitiesOptionsOptions for discovering caller creation capabilities in a billing project.source
SandboxClientOptionssource
SandboxDetailsA sandbox summary returned by list.source
SandboxEnvironmentSnapshot of environment variable names with redacted values.source
SandboxFileEntryDirectory entry metadata, without file contents.source
SandboxFileListOptionsDirectory listing options.source
SandboxFileListResultOne directory page. Follow pageInfo.next to request another page.source
SandboxLifetimeInputSandbox cleanup policy. Duration requires hours; other policies accept no duration.source
SandboxLifetimeModesource
SandboxListOptionsOptions for listing sandboxes.source
SandboxListResultPaginated result of sandboxes.source
SandboxOptionsOptions for creating a sandbox.source
SandboxRuntimeCheckRuntime health or readiness result. A false check is a result, not a transport error.source
SandboxShellToolDefinitionDefinition for sandbox shell tool.source
SandboxShellToolSetPublic API contract for sandbox shell tool set.source
SandboxStatusObserved sandbox runtime state.source
SandboxWorkspaceStoragesource