Documentation

TypeScript SDK reference

Classes, methods, fields, and return types for @syva/sdk.

Model

Name	Type	Description
Sandbox	`class`	Sandbox instance returned by create, get, and list.
Image	`class`	Immutable image recipe used as a sandbox image input.
sandbox.process	`SandboxProcess`	Foreground and background command namespace.
sandbox.fs	`FileSystem`	Absolute-path filesystem namespace.

Name

Sandbox

Type

class

Description

Sandbox instance returned by create, get, and list.

Name

Image

Type

class

Description

Immutable image recipe used as a sandbox image input.

Name

sandbox.process

Type

SandboxProcess

Description

Foreground and background command namespace.

Name

sandbox.fs

Type

FileSystem

Description

Absolute-path filesystem namespace.

Create Sandboxes

Sandbox.create

operation

Sandbox.create(options?: SandboxCreateOptions, config?: SyvaConfig) -> Promise<Sandbox>

Creates a sandbox and waits for it to become ready or fail.

Name	Type	Description
image default base	`string \| Image`	Syva image reference, or an SDK image recipe that may start from a public registry image.
cpuCores default 1	`number`	Virtual CPU cores.
memoryMb default 1024	`number`	Memory in MiB.
ttlSeconds	`number`	Optional expiry window in seconds.
networkPolicy default allow-all	`"allow-all" \| "deny-all"`	Outbound network policy.
startCommand	`string`	Command started when the sandbox boots.
env	`Record<string, string>`	Default environment variables for commands.
labels	`string[] \| Record<string, string>`	Labels stored with the sandbox.
ports	`Array<number \| { containerPort: number; protocol?: "http" \| "tcp" }>`	Ports exposed through sandbox ingress.
name	`string`	Unique-per-project handle for by-name lookup and resume.
persistent default true	`boolean`	Snapshot the filesystem on stop so the sandbox can resume.
snapshotExpirationSeconds	`number`	Snapshot TTL, reset on each use. 0 keeps snapshots until deleted.
keepLastSnapshots	`number \| KeepLastSnapshots`	Retention policy: count, or {count, expirationSeconds, deleteEvicted}. Default keeps every snapshot.
sourceSnapshotId	`string`	Fork: create from a snapshot instead of an image.
sourceSandbox	`string`	Fork: create from another sandbox's latest snapshot, by id or name.

Name

image

default base

Type

string | Image

Description

Syva image reference, or an SDK image recipe that may start from a public registry image.

Name

cpuCores

default 1

Type

number

Description

Virtual CPU cores.

Name

memoryMb

default 1024

Type

number

Description

Memory in MiB.

Name

ttlSeconds

Type

number

Description

Optional expiry window in seconds.

Name

networkPolicy

default allow-all

Type

"allow-all" | "deny-all"

Description

Outbound network policy.

Name

startCommand

Type

string

Description

Command started when the sandbox boots.

Name

env

Type

Record<string, string>

Description

Default environment variables for commands.

Name

labels

Type

string[] | Record<string, string>

Description

Labels stored with the sandbox.

Name

ports

Type

Array<number | { containerPort: number; protocol?: "http" | "tcp" }>

Description

Ports exposed through sandbox ingress.

Name

name

Type

string

Description

Unique-per-project handle for by-name lookup and resume.

Name

persistent

default true

Type

boolean

Description

Snapshot the filesystem on stop so the sandbox can resume.

Name

snapshotExpirationSeconds

Type

number

Description

Snapshot TTL, reset on each use. 0 keeps snapshots until deleted.

Name

keepLastSnapshots

Type

number | KeepLastSnapshots

Description

Retention policy: count, or {count, expirationSeconds, deleteEvicted}. Default keeps every snapshot.

Name

sourceSnapshotId

Type

string

Description

Fork: create from a snapshot instead of an image.

Name

sourceSandbox

Type

string

Description

Fork: create from another sandbox's latest snapshot, by id or name.

Returns Promise<Sandbox>

Sandbox Object

Name	Type	Description
id	`string`	Sandbox id.
state	`string`	Lifecycle state.
image	`string`	Resolved image ref.
resources	`Record<string, number>`	Allocated CPU, memory, and disk.
networkPolicy	`string`	Outbound network policy.
labels	`string[]`	Labels attached at creation.
ports	`JsonObject[]`	Declared port bindings and preview URLs.
createdAt	`string`	ISO timestamp.
expiresAt	`string \| undefined`	ISO timestamp when an expiry was requested.
error	`string \| undefined`	Terminal error when present.
name	`string \| undefined`	Unique sandbox name when assigned.
persistent	`boolean`	Whether stop snapshots the filesystem.
currentSnapshotId	`string \| undefined`	Snapshot the next start resumes from.
lastSnapshot	`Snapshot \| undefined`	Snapshot captured by the most recent stop().
fs	`FileSystem`	Filesystem namespace.
process	`SandboxProcess`	Command namespace.

Name

Type

string

Description

Sandbox id.

Name

state

Type

string

Description

Lifecycle state.

Name

image

Type

string

Description

Resolved image ref.

Name

resources

Type

Record<string, number>

Description

Allocated CPU, memory, and disk.

Name

networkPolicy

Type

string

Description

Outbound network policy.

Name

labels

Type

string[]

Description

Labels attached at creation.

Name

ports

Type

JsonObject[]

Description

Declared port bindings and preview URLs.

Name

createdAt

Type

string

Description

ISO timestamp.

Name

expiresAt

Type

string | undefined

Description

ISO timestamp when an expiry was requested.

Name

error

Type

string | undefined

Description

Terminal error when present.

Name

name

Type

string | undefined

Description

Unique sandbox name when assigned.

Name

persistent

Type

boolean

Description

Whether stop snapshots the filesystem.

Name

currentSnapshotId

Type

string | undefined

Description

Snapshot the next start resumes from.

Name

lastSnapshot

Type

Snapshot | undefined

Description

Snapshot captured by the most recent stop().

Name

Type

FileSystem

Description

Filesystem namespace.

Name

process

Type

SandboxProcess

Description

Command namespace.

Sandbox.configure(config)

Sets default baseUrl, apiKey, retry, timeout, or fetch implementation.

Returns: void

Sandbox.create(options, config)

Creates a sandbox and waits for it to become ready or fail.

Returns: Promise<Sandbox>

Sandbox.get(sandboxId, config)

Fetches an existing sandbox.

Returns: Promise<Sandbox>

Sandbox.list(options, config)

Lists sandboxes for the API key.

Returns: Promise<Sandbox[]>

sandbox.refresh()

Reloads sandbox state.

Returns: Promise<Sandbox>

Sandbox.getByName(name, config)

Fetches a sandbox by its unique name.

Returns: Promise<Sandbox>

Sandbox.getOrCreate(options, config)

Resumes the named sandbox, or creates it when missing.

Returns: Promise<Sandbox>

sandbox.destroy()

Permanently deletes the sandbox, its snapshots, and frees its name.

Returns: Promise<Sandbox>

sandbox.stop()

Stops the sandbox; persistent sandboxes snapshot their filesystem first.

Returns: Promise<Sandbox>

sandbox.start()

Resumes a stopped persistent sandbox from its latest snapshot.

Returns: Promise<Sandbox>

sandbox.snapshot(options)

Takes a manual snapshot; the sandbox stops.

Returns: Promise<Snapshot | undefined>

sandbox.snapshots()

Lists this sandbox's live snapshots.

Returns: Promise<Snapshot[]>

sandbox.fork(options)

Creates a new sandbox from this sandbox's latest snapshot.

Returns: Promise<Sandbox>

sandbox.update(options)

Updates persistence, expiration, retention, or rolls back via currentSnapshotId.

Returns: Promise<Sandbox>

Snapshot.list(options, config)

Lists snapshots in the project.

Returns: Promise<Snapshot[]>

Snapshot.delete(snapshotId, config)

Deletes a snapshot and its stored data.

Returns: Promise<Snapshot>

sandbox.kill()

Alias for destroy.

Returns: Promise<Sandbox>

sandbox.extendTtl(options)

Sets or extends the expiry window.

Returns: Promise<Sandbox>

sandbox.extendTimeout(durationMs)

Extends the expiry window by milliseconds.

Returns: Promise<Sandbox>

sandbox.wait(options)

Polls until the sandbox reaches a lifecycle state.

Returns: Promise<Sandbox>

sandbox.domain(port)

Returns the preview URL for an exposed port.

Returns: string

Snapshots

Persistent sandboxes snapshot their filesystem on stop() and resume with start(). See the Snapshots guide.

Name	Type	Description
id	`string`	Snapshot id.
state	`string`	created, deleted, or failed.
source	`string`	auto (taken on stop) or manual.
sandboxId	`string \| undefined`	Owning sandbox.
sizeBytes	`number`	Stored (compressed) bytes; the billing basis.
expiresAt	`string \| undefined`	Expiry, refreshed each time the snapshot is used.

Name

Type

string

Description

Snapshot id.

Name

state

Type

string

Description

created, deleted, or failed.

Name

source

Type

string

Description

auto (taken on stop) or manual.

Name

sandboxId

Type

string | undefined

Description

Owning sandbox.

Name

sizeBytes

Type

number

Description

Stored (compressed) bytes; the billing basis.

Name

expiresAt

Type

string | undefined

Description

Expiry, refreshed each time the snapshot is used.

Commands

sandbox.runCommand

operation

sandbox.runCommand(command, options) -> Promise<CommandFinished | Command>

Runs foreground commands by default. Set detached to start a background command.

Name	Type	Description
args	`string[]`	Arguments passed after the command.
cwd	`string`	Working directory inside the sandbox.
timeoutMs	`number`	Command timeout in milliseconds.
env	`Record<string, string>`	Environment variables for this command.
detached	`boolean`	Return a Command immediately instead of waiting for completion.

Name

args

Type

string[]

Description

Arguments passed after the command.

Name

cwd

Type

string

Description

Working directory inside the sandbox.

Name

timeoutMs

Type

number

Description

Command timeout in milliseconds.

Name

env

Type

Record<string, string>

Description

Environment variables for this command.

Name

detached

Type

boolean

Description

Return a Command immediately instead of waiting for completion.

Returns Promise<CommandFinished | Command>

sandbox.runCommand(command, options)

Runs a command. Set detached to return immediately.

Returns: Promise<CommandFinished | Command>

sandbox.process.exec(command, options)

Runs a foreground command.

Returns: Promise<CommandFinished>

sandbox.process.start(command, options)

Starts a background command.

Returns: Promise<Command>

sandbox.process.get(commandId)

Fetches the latest command state.

Returns: Promise<Command>

sandbox.process.output(commandId)

Returns stdout and stderr snapshot.

Returns: Promise<CommandOutput>

sandbox.process.logs(commandId, options)

Returns stdout, stderr, or combined log text.

Returns: Promise<string>

sandbox.process.stream(commandId)

Streams stdout, stderr, and final status events.

Returns: AsyncIterable<CommandOutputEvent>

sandbox.process.stop(commandId)

Stops a running command.

Returns: Promise<Command>

sandbox.process.list(options)

Lists recent commands.

Returns: Promise<Command[]>

command.refresh()

Reloads command state.

Returns: Promise<Command>

command.wait(options)

Waits for command completion.

Returns: Promise<Command>

command.output()

Returns stdout and stderr snapshot.

Returns: Promise<CommandOutput>

command.readLogs(stream)

Returns stdout, stderr, or combined log text.

Returns: Promise<string>

command.stream(options)

Streams command output events.

Returns: AsyncIterable<CommandOutputEvent>

CommandFinished

Name	Type	Description
exitCode	`number`	Process exit code.
stdout	`string`	Captured stdout.
stderr	`string`	Captured stderr.
durationMs	`number`	Runtime duration.
timedOut	`boolean`	True when the timeout killed the command.

Name

exitCode

Type

number

Description

Process exit code.

Name

stdout

Type

string

Description

Captured stdout.

Name

stderr

Type

string

Description

Captured stderr.

Name

durationMs

Type

number

Description

Runtime duration.

Name

timedOut

Type

boolean

Description

True when the timeout killed the command.

Filesystem

Top-level helpers default to /workspace. sandbox.fs uses absolute paths.

sandbox.writeFile(path, data, options)

Writes under /workspace unless path is absolute.

Returns: Promise<void>

sandbox.writeFiles(files, options)

Writes multiple files under /workspace unless paths are absolute.

Returns: Promise<void>

sandbox.readFile(path, options)

Returns a readable stream, or null when missing.

Returns: Promise<ReadableStream | null>

sandbox.readFileToBuffer(path, options)

Reads bytes into memory, or null when missing.

Returns: Promise<Uint8Array | null>

sandbox.mkDir(path, options)

Creates a directory under /workspace unless path is absolute.

Returns: Promise<FileInfo>

sandbox.fs.writeFile(path, data, options)

Writes bytes or text to an absolute path.

Returns: Promise<void>

sandbox.fs.writeFiles(files)

Writes multiple absolute-path files.

Returns: Promise<void>

sandbox.fs.readFile(path)

Reads bytes from an absolute path.

Returns: Promise<Uint8Array>

sandbox.fs.stat(path)

Returns path metadata.

Returns: Promise<FileInfo>

sandbox.fs.list(path)

Lists directory entries.

Returns: Promise<FileInfo[]>

sandbox.fs.find(path, options)

Finds files and directories by type or pattern.

Returns: Promise<FileInfo[]>

sandbox.fs.grep(query, options)

Searches file contents and returns matching lines.

Returns: Promise<GrepMatch[]>

sandbox.fs.mkdir(path, options)

Creates a directory.

Returns: Promise<FileInfo>

sandbox.fs.rm(path, options)

Removes a file or directory.

Returns: Promise<void>

Images

String images are Syva image refs. Public registry refs such as node:22 should be wrapped with Image.fromRegistry; Sandbox.create builds that recipe into a reusable Syva image before launch.

Image recipes are immutable. Every mutating method returns a new Image.

new Image(reference)

Creates a base image recipe from a Syva base ref.

Returns: Image

Image.fromRegistry(reference)

Starts a recipe from a public Docker or OCI registry image.

Returns: Image

image.python(version)

Adds Python tooling.

Returns: Image

image.aptInstall(packages)

Installs Debian packages.

Returns: Image

image.pipInstall(packages)

Installs Python packages.

Returns: Image

image.npmInstall(packages, options)

Installs npm packages.

Returns: Image

image.runCmd(command)

Adds a build-time command.

Returns: Image

image.env(values)

Adds default environment variables.

Returns: Image

image.workdir(path)

Sets the default workdir.

Returns: Image

image.user(user)

Sets the default user.

Returns: Image

image.copy(src, dest, options)

Copies files into the build context.

Returns: Image

image.setStartCommand(command, readyCommand)

Sets boot and optional readiness commands.

Returns: Image

image.digest()

Returns a stable recipe digest.

Returns: string

Errors

Name	Type	Description
message	`string`	Human-readable error.
code	`string \| undefined`	Stable Syva error code.
status	`number \| undefined`	HTTP status when available.
sandboxId	`string \| undefined`	Related sandbox id when available.
retryable	`boolean \| undefined`	Whether retrying may succeed.

Name

message

Type

string

Description

Human-readable error.

Name

code

Type

string | undefined

Description

Stable Syva error code.

Name

status

Type

number | undefined

Description

HTTP status when available.

Name

sandboxId

Type

string | undefined

Description

Related sandbox id when available.

Name

retryable

Type

boolean | undefined

Description

Whether retrying may succeed.