TypeScript SDK

TypeScript SDK installation and full reference

The Sail TypeScript SDK (@sailresearch/sdk on npm) runs on Node 22+ and Bun. It shares one engine with the Python and Rust SDKs, so behavior matches across languages.

Install

npm

npm install @sailresearch/sdk

Prebuilt native binaries are published per platform (Linux, macOS, Windows) and selected automatically at install time.

The Sail API warns when your SDK version is nearing the end of its support window. The SDK prints that warning to stderr once per process. A version past the end of its support window is rejected with an upgrade error before any operation runs. Upgrade with npm install @sailresearch/sdk@latest.

Configure

Set SAIL_API_KEY in the environment; the SDK also reads the credential sail auth login stores under ~/.sail. The statics on Sailbox, App, and Volume use this configuration by default, or construct a Client explicitly with Client.fromConfig({ apiKey }). See Configuration.

Quickstart

import { App, Sailbox } from "@sailresearch/sdk";

// Look up (or create) the app your sandboxes belong to.
const app = await App.find("example-app", { mintIfMissing: true });

// Boot a sandbox.
const sb = await Sailbox.create({ app, name: "worker-1" });

// Run a command and stream its output.
const proc = await sb.exec("echo hello && ls /");
for await (const chunk of proc.stdout) process.stdout.write(chunk);
const result = await proc.wait();
console.log("exit code:", result.exitCode);

// Move files.
await sb.fs.write("/tmp/note.txt", "hi\n");
const contents = await sb.fs.read("/tmp/note.txt");

// Expose a port and wait until it is reachable.
await sb.expose(8080, { protocol: "http" });
const listener = await sb.waitForListener(8080);
if (listener.endpoint?.kind === "http") {
  console.log("reachable at:", listener.endpoint.url);
}

// Clean up (see also pause / sleep / resume / checkpoint).
await sb.terminate();

Errors

Every failure the SDK recognizes extends SailError, so one catch (e) { if (e instanceof SailError) } handles them; a truly unexpected native error surfaces unchanged. Subclasses like NotFoundError and SailboxExecutionError match specific failures, every error carries an advisory retryable flag, and isSailError() is the realm-safe check. See Errors.

Reference

The docs below are auto-generated.

Sailbox

A sandbox (Sailbox): the primary object agent harnesses work with. Create one with Sailbox.create, run commands with exec, move files with fs, expose ports with expose, and manage its lifecycle. The statics use a default env-configured client unless you pass one.

Example

import { App, Sailbox } from "@sailresearch/sdk";

const app = await App.find("example-app", { mintIfMissing: true });
const box = await Sailbox.create({ app, name: "worker-1" });
const proc = await box.exec(["bash", "-lc", "echo hello"]);
console.log(await proc.stdout.text());
await box.terminate();

Accessors

appId

Get Signature

get appId(): string | undefined

Identifier of the owning app.

Returns

string | undefined

appName

Get Signature

get appName(): string | undefined

Name of the owning app.

Returns

string | undefined

architecture

Get Signature

get architecture(): string | undefined

CPU architecture (for example arm64).

Returns

string | undefined

checkpointGeneration

Get Signature

get checkpointGeneration(): number | undefined

Checkpoint generation counter as of the snapshot.

Returns

number | undefined

client

Get Signature

get client(): Client

The underlying Client.

Returns

Client

cpuRequestedVcpu

Get Signature

get cpuRequestedVcpu(): number | undefined

Requested CPU, in vCPUs.

Returns

number | undefined

cpuUsedVcpu

Get Signature

get cpuUsedVcpu(): number | undefined

Current CPU usage, in vCPUs, as of the snapshot.

Returns

number | undefined

createdAt

Get Signature

get createdAt(): Date | undefined

When the Sailbox was created.

Returns

Date | undefined

createdByUserId

Get Signature

get createdByUserId(): string | undefined

The user whose credential created this Sailbox (for a fork or restore, the user who ran it). undefined for service-key creates.

Returns

string | undefined

deprecation

Get Signature

get deprecation(): SailboxDeprecation | undefined

Actionable runtime deprecation notice, when an upgrade is needed.

Returns

SailboxDeprecation | undefined

diskRequestedBytes

Get Signature

get diskRequestedBytes(): number | undefined

Requested disk, in bytes.

Returns

number | undefined

diskUsedBytes

Get Signature

get diskUsedBytes(): number | undefined

Current disk usage, in bytes, as of the snapshot.

Returns

number | undefined

errorMessage

Get Signature

get errorMessage(): string | undefined

Failure detail when the status is failed.

Returns

string | undefined

fs

Get Signature

get fs(): SailboxFs

Filesystem operations on this Sailbox’s guest: read and write files (buffered or streaming), and directory helpers.

Returns

SailboxFs

guestSchemaVersion

Get Signature

get guestSchemaVersion(): number | undefined

The Sailbox runtime schema version the Sailbox last booted with.

Returns

number | undefined

imageId

Get Signature

get imageId(): string | undefined

Identifier of the image the Sailbox was created from.

Returns

string | undefined

lastCheckpointedAt

Get Signature

get lastCheckpointedAt(): Date | undefined

When the most recent checkpoint was taken.

Returns

Date | undefined

memoryMib

Get Signature

get memoryMib(): number | undefined

Configured memory, in MiB.

Returns

number | undefined

memoryRequestedBytes

Get Signature

get memoryRequestedBytes(): number | undefined

Requested memory, in bytes.

Returns

number | undefined

memoryUsedBytes

Get Signature

get memoryUsedBytes(): number | undefined

Current memory usage, in bytes, as of the snapshot.

Returns

number | undefined

name

Get Signature

get name(): string

The Sailbox name.

Returns

string

sailboxId

Get Signature

get sailboxId(): string

The Sailbox’s stable identifier.

Returns

string

startedAt

Get Signature

get startedAt(): Date | undefined

When the Sailbox first started running. A resume does not rewrite it.

Returns

Date | undefined

stateDiskSizeGib

Get Signature

get stateDiskSizeGib(): number | undefined

Configured state-disk size, in GiB.

Returns

number | undefined

status

Get Signature

get status(): SailboxStatus

The lifecycle status as of the call that produced this handle (updated by lifecycle calls on this instance). Use Sailbox.get for a fresh snapshot.

Returns

SailboxStatus

updatedAt

Get Signature

get updatedAt(): Date | undefined

When the Sailbox last changed.

Returns

Date | undefined

vcpuCount

Get Signature

get vcpuCount(): number | undefined

Configured number of vCPUs.

Returns

number | undefined

visibility

Get Signature

get visibility(): string | undefined

"private" when access is restricted to the creator; undefined/"org" is the default org-wide access.

Returns

string | undefined

Methods

checkpoint()

checkpoint(options?): Promise<SailboxCheckpoint>

Take a checkpoint of this Sailbox. The returned handle carries expiresAt, after which starting a Sailbox from it fails.

Parameters

Parameter	Type
options	CheckpointOptions

Returns

Promise<SailboxCheckpoint>

enableSsh()

enableSsh(options?): Promise<SshEndpoint | null>

Enable SSH on this Sailbox: trust the org SSH CA, start sshd, and expose guest port 22 as TCP once the CA-only daemon owns it. Org members connect with a short-lived certificate (fetched by the sail box ssh CLI); a private Sailbox accepts only its creator’s certificates. Safe to re-run. With wait (the default), polls until the endpoint is reachable and returns it, throwing TimeoutError if it is not within timeoutSeconds; with wait: false, skips the probe and resolves null.

Parameters

Parameter	Type
options	EnableSshOptions

Returns

Promise<SshEndpoint | null>

exec()

exec(command, options?): Promise<ExecProcess>

Run a command and return a handle to the live process. A string command is run via /bin/sh -lc; a string[] is exec’d directly. options can set a working directory or detach the command (see ExecOptions). Stopping the command is the caller’s job via ExecProcess.cancel.

Parameters

Parameter	Type
command	string | readonly string[]
options?	ExecOptions

Returns

Promise<ExecProcess>

expose()

expose(guestPort, options?): Promise<Listener>

Expose a guest port at runtime. Re-exposing a port under the same protocol sets its allowlist to what you pass, so pass the whole list every time; passing none clears the restriction and reopens the port. The returned listener carries the resolved endpoint but an "unknown" route status: the response confirms configuration, not reachability; waitForListener confirms the route is live.

Parameters

Parameter	Type
guestPort	number
options	ExposeOptions

Returns

Promise<Listener>

fork()

fork(options?): Promise<Sailbox>

Fork this Sailbox into a new running child in one call. The child copies this Sailbox’s memory and writable disk as they are now, branching from the parent’s current state, and the parent is left as it was. The copy is transient: no durable checkpoint is created. To branch from a saved point in time instead, pair checkpoint with Sailbox.fromCheckpoint, which works even after the parent is gone. Because the memory comes across, processes the parent was running carry on in the child. Commands started with exec stop in the child, though their writes up to the fork are kept, and one started with background: true keeps running there. Start the other execs the child needs. Sometimes the child comes up cold instead, with the disk intact and nothing running, and a child that mounts a volume always does. Volumes are mounted on the child at the same paths as on the parent, and they are the same volumes, so both Sailboxes read and write the same files.

Parameters

Parameter	Type
options	ForkSailboxOptions

Returns

Promise<Sailbox>

ingressAuthHeaders()

ingressAuthHeaders(): Promise<Record<string, string>>

Ingress-identity headers for this Sailbox, as a name→value map.

Returns

Promise<Record<string, string>>

listener()

listener(guestPort): Promise<Listener>

Fetch one listener by guest port without waking the Sailbox.

Parameters

Parameter	Type
guestPort	number

Returns

Promise<Listener>

listeners()

listeners(): Promise<Listener[]>

List this Sailbox’s listeners without waking it.

Returns

Promise<Listener[]>

pause()

pause(): Promise<void>

Pause this Sailbox in memory.

Returns

Promise<void>

resume()

resume(): Promise<void>

Resume this Sailbox (updates status).

Returns

Promise<void>

run()

run(command, options?): Promise<ExecResult>

Run a command to completion and return its buffered result: a one-shot convenience over exec followed by ExecProcess.wait. A string command runs via /bin/sh -lc; a string[] is exec’d directly. Set env in options to add environment variables; cwd sets the working directory (string commands only, like exec); signal force-cancels the command on abort (see RunOptions). The result’s stdout/stderr are the buffered output (capped, drop-oldest); for unbounded output, stream it live via exec instead. openStdin, pty, and background are excluded from RunOptions and rejected at runtime: run() waits for the command to finish and buffers its output, so an interactive command would hang and a backgrounded one would return the launcher’s result, not the command’s; use exec for those.

Parameters

Parameter	Type
command	string | readonly string[]
options?	RunOptions

Returns

Promise<ExecResult>

shell()

shell(command?, options?): Promise<number>

Open an interactive pty session on this Sailbox, bridged to the local terminal. With no command, runs a login shell; pass a command to run that under a pty instead (e.g. a REPL or an editor). Blocks until the remote process exits and resolves with its exit code. Requires an interactive terminal (stdin and stdout TTYs) on a Unix machine. While the session is open, browser opens, localhost servers, paste, drag-and-drop, and clipboard are forwarded to your machine (the clipboard is two-way on devbox images); see ShellOptions.noForward.

Parameters

Parameter	Type
command?	string
options?	ShellOptions

Returns

Promise<number>

sleep()

sleep(wakeAt?): Promise<Date | undefined>

Sleep this Sailbox to disk (wakes on traffic), optionally scheduling a wall-clock wake first. wakeAt, when given, records the wake before the sleep starts and the returned value is the effective wake time: the sooner of this request and any wake already scheduled. If the Sailbox is sleeping when that moment arrives, Sail restores it. The wake can fire a little after the time you set, so treat it as approximate. Sleeping an already-sleeping Sailbox succeeds and just updates the scheduled wake.

Parameters

Parameter	Type
wakeAt?	Date

Returns

Promise<Date | undefined>

terminate()

terminate(): Promise<void>

Terminate (delete) this Sailbox (updates status).

Returns

Promise<void>

unexpose()

unexpose(guestPort): Promise<void>

Remove a runtime ingress port.

Parameters

Parameter	Type
guestPort	number

Returns

Promise<void>

upgrade()

upgrade(): Promise<UpgradeResult>

Upgrade this Sailbox’s runtime.

Returns

Promise<UpgradeResult>

waitForListener()

waitForListener(guestPort, options?): Promise<Listener>

Block until the listener on guestPort is reachable end to end and return it, or throw TimeoutError after timeoutSeconds. An HTTP listener is ready once the guest server answers; a TCP listener once the guest sends bytes or holds the connection open. A connectivity check, not an application health check.

Parameters

Parameter	Type
guestPort	number
options	WaitForListenerOptions

Returns

Promise<Listener>

create()

static create(options): Promise<Sailbox>

Create a new Sailbox.

A custom image definition passed as image is built first, following the image contract (see Client.buildImageDefinition): the image may boot hidden at build time and periodically while in active use, sharing those boots’ state with every Sailbox created from it via a start snapshot, so generate per-instance identity at runtime, not in boot-time jobs.

Sail may sleep a fully idle Sailbox; it wakes transparently on traffic or the next operation.

Parameters

Parameter	Type
options	CreateSailboxOptions

Returns

Promise<Sailbox>

fromCheckpoint()

static fromCheckpoint(options): Promise<Sailbox>

Create a new running Sailbox from a durable checkpoint handle. The new Sailbox restores the memory saved in the checkpoint as well as the writable disk, so processes the original was running carry on here, and it runs independently of the Sailbox that took the checkpoint. Commands started with Sailbox.exec stop here, though their writes up to the checkpoint are kept, and one started with background: true keeps running. Start the other execs the new Sailbox needs. Sometimes it comes up cold instead, with the disk intact and nothing running, and a Sailbox that mounts a volume always does. Volumes are mounted on it at the same paths as on the original, and they are the same volumes, so both Sailboxes read and write the same files.

Parameters

Parameter	Type
options	FromCheckpointOptions

Returns

Promise<Sailbox>

fromId()

static fromId(sailboxId, options?): Sailbox

Bind a handle to an existing Sailbox id without a network call.

The returned handle carries no snapshot fields (its name and status are empty), just the operable surface. The id is not verified to exist: operations on an unknown or inaccessible id reject with NotFoundError. Use get to validate the id and fetch a fresh snapshot instead.

Parameters

Parameter	Type
sailboxId	string
options	ClientOptions

Returns

Sailbox

get()

static get(sailboxId, options?): Promise<Sailbox>

Fetch an existing Sailbox by id.

Parameters

Parameter	Type
sailboxId	string
options	ClientOptions

Returns

Promise<Sailbox>

list()

static list(params?): Promise<Sailbox[]>

List the Sailboxes that match the filters, fetching pages internally until every match (or limit of them) is collected; use listPage to page through results manually instead. limit caps the total returned, bounding the fetch for large orgs. A client can ride along in the query object.

Parameters

Parameter	Type
params	ListSailboxesOptions

Returns

Promise<Sailbox[]>

listPage()

static listPage(params?): Promise<SailboxPage>

List one page of Sailboxes alongside the pagination envelope (total/hasMore). Takes the same filters as list, plus limit and offset to select the page.

Parameters

Parameter	Type
params	ListSailboxesPageOptions

Returns

Promise<SailboxPage>

---

App

An app: the billing/ownership scope a Sailbox belongs to. Look one up (or mint it) with App.find, then pass it (or its App.id) to Sailbox.create.

Properties

Property	Modifier	Type	Description
createdAt	readonly	Date	Creation time.
id	readonly	string	Stable app id.
name	readonly	string	App name.

Methods

find()

static find(name, options?): Promise<App>

Find an app by name, optionally minting it if missing.

Parameters

Parameter	Type
name	string
options	FindAppOptions

Returns

Promise<App>

list()

static list(options?): Promise<App[]>

Every app the current org owns, newest first.

Parameters

Parameter	Type
options	ClientOptions

Returns

Promise<App[]>

---

Image

A custom image definition. Immutable and fluent: each method returns a new Image. Local files/dirs are recorded here and hashed + uploaded by the core when the image is resolved to a spec (at Sailbox.create, or via toSpec), so chaining stays synchronous.

Example

const image = Image.debian("arm64")
  .aptInstall("git")
  .pipInstall("numpy")
  .addLocalDir("./app", "/app", { ignore: ["*.pyc", "__pycache__/"] })
  .runCommand("pip install -e /app");
const box = await Sailbox.create({ app, name: "w", image });

Methods

addLocalDir()

addLocalDir(localPath, remotePath, options?): Image

Bake a local directory tree into the image at path. Each regular file is hashed + uploaded at resolve; symlinks are skipped and file modes preserved. ignore takes gitignore-style patterns.

Parameters

Parameter	Type
localPath	string
remotePath	string
options	AddLocalDirOptions

Returns

Image

addLocalFile()

addLocalFile(localPath, remotePath, options?): Image

Bake one local file into the image at path (absolute POSIX path; a trailing / appends the source basename). Hashed + uploaded at resolve.

Parameters

Parameter	Type
localPath	string
remotePath	string
options	AddLocalFileOptions

Returns

Image

aptInstall()

aptInstall(…packages): Image

Install system packages with apt.

Parameters

Parameter	Type
…packages	string[]

Returns

Image

build()

build(options?): Promise<ImageSpec>

Upload any local files and build the image, waiting until it is ready. Returns the resolved ImageSpec. Sailbox.create calls this for a custom image before creating the Sailbox (the backend serves the content-addressed built image); a bare base image skips the build. Local files are re-hashed on every call, so edits always reach the build, and rebuilding an unchanged, already-built image returns quickly.

Parameters

Parameter	Type
options	ImageBuildOptions

Returns

Promise<ImageSpec>

env()

env(env): Image

Bake environment variables into the image (keys are trimmed).

Parameters

Parameter	Type
env	Readonly<Record<string, string>>

Returns

Image

pipInstall()

pipInstall(…packages): Image

Install Python packages with pip.

Parameters

Parameter	Type
…packages	string[]

Returns

Image

runCommand()

runCommand(command): Image

Run a shell command during the build.

Parameters

Parameter	Type
command	string

Returns

Image

toSpec()

toSpec(client?): Promise<ImageSpec>

Resolve to an ImageSpec: walks local files/dirs (honoring gitignore), hashes them, and uploads their content via client (defaults to the env client). Sailbox.create calls this for you; use it directly only if you need the raw spec.

Parameters

Parameter	Type
client?	Client

Returns

Promise<ImageSpec>

debian()

static debian(architecture?): Image

A Debian base image (defaults to arm64).

Parameters

Parameter	Type	Default value
architecture	ImageArchitecture	"arm64"

Returns

Image

devbox()

static devbox(architecture?): Image

The devbox base image (defaults to arm64): a prebuilt Debian base with a baked development layer. Prebuilt-only, so it does not support build steps or env; start from Image.debian to customize.

Parameters

Parameter	Type	Default value
architecture	ImageArchitecture	"arm64"

Returns

Image

---

ExecProcess

A live command running in a Sailbox. Stream stdout/stderr, write to writeStdin, and wait for the result. Not killed on GC; call close to detach, or cancel to stop the command.

Example

const proc = await box.exec(["bash", "-lc", "echo hi"]);
for await (const line of proc.stdout) process.stdout.write(line);
const result = await proc.wait();
console.log(result.exitCode);

Properties

Property	Modifier	Type	Description
stderr	readonly	ExecStream	Stderr stream: string iteration by default, .raw() for bytes.
stdout	readonly	ExecStream	Stdout stream: string iteration by default, .raw() for bytes.

Accessors

execRequestId

Get Signature

get execRequestId(): string

The durable exec request id.

Returns

string

idempotencyKey

Get Signature

get idempotencyKey(): string

The idempotency key used to launch the command.

Returns

string

output

Get Signature

get output(): ExecStream

Alias for stdout: under a pty the two output streams merge onto stdout, and output names that merged terminal stream.

Returns

ExecStream

Methods

[asyncDispose]()

[asyncDispose](): Promise<void>

await using support: detaches on scope exit.

Returns

Promise<void>

[dispose]()

[dispose](): void

using support: detaches on scope exit.

Returns

void

cancel()

cancel(options?): Promise<void>

Cancel the command (SIGINT by default, SIGKILL with force). Transient failures are retried briefly, covering the window right after the command starts when the guest cannot accept signals for it yet.

Parameters

Parameter	Type
options	CancelOptions

Returns

Promise<void>

close()

close(): void

Stop the output pump and detach (does not kill the command). Call this on early exit from streaming a long-running command so the stream is not held until GC.

Returns

void

closeStdin()

closeStdin(): Promise<void>

Close the command’s stdin (send EOF).

Returns

Promise<void>

poll()

poll(): number | null

The exit code if the exit frame has arrived on the stream, else null. Throws for a host-lost exec (no real exit code), as wait does.

Returns

number | null

resize()

resize(cols, rows): Promise<void>

Resize the pty (no-op without one).

Parameters

Parameter	Type
cols	number
rows	number

Returns

Promise<void>

resync()

resync(): Promise<void>

Ask a pty exec to repaint its current screen (no-op without a pty). A command runs at full speed and never waits for a slow reader, so if you fall far behind the oldest output is dropped. Call this after that happens to receive the current screen instead of a broken, partial one. Advisory and best-effort.

Returns

Promise<void>

wait()

wait(): Promise<ExecResult>

Await the authoritative result (exit code, buffered output, flags).

Returns

Promise<ExecResult>

waitStreamEnded()

waitStreamEnded(timeoutSeconds): Promise<boolean>

Wait up to timeoutSeconds for the streams to end; returns whether they did. Infinity waits indefinitely.

Parameters

Parameter	Type
timeoutSeconds	number

Returns

Promise<boolean>

writeStdin()

writeStdin(data): Promise<void>

Write to the command’s stdin (requires openStdin).

Parameters

Parameter	Type
data	string | Buffer<ArrayBufferLike> | Uint8Array<ArrayBufferLike>

Returns

Promise<void>

---

ExecStream

An async-iterable view of one exec stream (stdout or stderr). Default iteration yields string chunks, incrementally decoded as UTF-8 (a multibyte character split across chunks is carried until complete); use raw for the unmodified byte stream.

Example

for await (const chunk of proc.stdout) process.stdout.write(chunk);

Implements

• AsyncIterable<string>

Methods

[asyncIterator]()

[asyncIterator](): AsyncIterator<string>

Returns

AsyncIterator<string>

Implementation of

AsyncIterable.[asyncIterator]

bytes()

bytes(): Promise<Buffer<ArrayBufferLike>>

Collect the whole raw byte stream into a single Buffer.

Returns

Promise<Buffer<ArrayBufferLike>>

raw()

raw(): AsyncIterableIterator<Buffer<ArrayBufferLike>>

Iterate the raw byte stream, exactly as the command wrote it (escape sequences and binary payloads included).

Returns

AsyncIterableIterator<Buffer<ArrayBufferLike>>

text()

text(): Promise<string>

Collect the whole stream into a single string.

Returns

Promise<string>

toReadable()

toReadable(): Readable

Adapt to a Node Readable of string chunks (e.g. to .pipe() it).

Returns

Readable

---

SailboxFs

Filesystem operations on a Sailbox’s guest, reached via Sailbox.fs. File I/O streams bytes to/from the guest; the directory helpers create, remove, and test paths.

Methods

exists()

exists(path): Promise<boolean>

Whether path exists in the guest. Follows symlinks (like test -e), so a dangling symlink reports false even though ls lists it.

Parameters

Parameter	Type
path	string

Returns

Promise<boolean>

ls()

ls(path): Promise<DirEntry[]>

List a directory’s immediate entries as DirEntry records (no recursion). A missing path throws, as does a path that is not a directory and a listing too large for the exec output cap. An entry whose name is not valid UTF-8 fails the listing, since the path API cannot address it.

Parameters

Parameter	Type
path	string

Returns

Promise<DirEntry[]>

mkdir()

mkdir(path): Promise<void>

Create a directory and any missing parents (like mkdir -p); a no-op if it already exists.

Parameters

Parameter	Type
path	string

Returns

Promise<void>

read()

read(path): Promise<Buffer<ArrayBufferLike>>

Read a guest file fully into memory (convenience over readStream).

Parameters

Parameter	Type
path	string

Returns

Promise<Buffer<ArrayBufferLike>>

readStream()

readStream(path): Promise<FileStream>

Open a streaming read of a guest file.

Parameters

Parameter	Type
path	string

Returns

Promise<FileStream>

remove()

remove(path): Promise<void>

Remove a file or directory tree (like rm -rf); a no-op if it is already absent.

Parameters

Parameter	Type
path	string

Returns

Promise<void>

write()

write(path, data, options?): Promise<void>

Write bytes (a string is encoded as UTF-8) to a guest file, creating it and any missing parent directories (convenience over writeStream; pass createParents: false to opt out).

Parameters

Parameter	Type
path	string
data	string | Buffer<ArrayBufferLike> | Uint8Array<ArrayBufferLike>
options?	WriteOptions

Returns

Promise<void>

writeStream()

writeStream(path, options?): Promise<FileWriter>

Open a streaming upload to a guest file.

Parameters

Parameter	Type
path	string
options?	WriteOptions

Returns

Promise<FileWriter>

---

FileWriter

A streaming write to a guest file. Push chunks with write, then confirm with finish; only finish commits the write. A writer that goes away without finishing (abort, an error path, or garbage collection) cancels the transfer instead; the guest file state is then unspecified.

Methods

[asyncDispose]()

[asyncDispose](): Promise<void>

await using support; same semantics as the synchronous form.

Returns

Promise<void>

[dispose]()

[dispose](): void

using support: aborts the write if it was never finished, so leaving scope on an error path cancels instead of committing a partial file. abort is synchronous, so the plain form suffices.

Returns

void

abort()

abort(): void

Abort the write: cancel the RPC so the server does not commit it. Idempotent. A later finish reports the abort instead of succeeding; the guest file state after an abort is unspecified.

Returns

void

finish()

finish(): Promise<void>

Confirm the write, creating an empty file if nothing was written.

Returns

Promise<void>

toWritable()

toWritable(): Writable

Adapt to a Node Writable: end() runs finish (only that commits the write), destroying the stream aborts it, and backpressure follows the underlying transfer since each chunk’s callback fires when the core accepts the bytes.

Returns

Writable

write()

write(data): Promise<void>

Write bytes (a string is encoded as UTF-8). The core splits them into transport-sized chunks.

Parameters

Parameter	Type
data	string | Buffer<ArrayBufferLike> | Uint8Array<ArrayBufferLike>

Returns

Promise<void>

---

FileStream

An async-iterable download of a guest file. Chunks are Buffers; iteration ends at end of file. The underlying stream is released when iteration finishes or is abandoned (via a generator finally), or explicitly via close.

Implements

• AsyncIterable<Buffer>

Methods

[asyncDispose]()

[asyncDispose](): Promise<void>

await using support.

Returns

Promise<void>

[asyncIterator]()

[asyncIterator](): AsyncIterator<Buffer<ArrayBufferLike>>

Returns

AsyncIterator<Buffer<ArrayBufferLike>>

Implementation of

AsyncIterable.[asyncIterator]

bytes()

bytes(): Promise<Buffer<ArrayBufferLike>>

Collect the whole file into a single Buffer.

Returns

Promise<Buffer<ArrayBufferLike>>

close()

close(): Promise<void>

Release the underlying download stream (idempotent).

Returns

Promise<void>

toReadable()

toReadable(): Readable

Adapt to a Node Readable.

Returns

Readable

---

Volume

A managed NFS volume that can be mounted into Sailboxes. Look one up (or mint it) with Volume.find, then pass it (or its Volume.id) in a Sailbox’s volumes mapping.

Volumes are currently in Alpha. To pilot them, reach out in the Sail Slack: https://join.slack.com/t/sailresearchcrew/shared_invite/zt-41pdcym9j-UU0Ey~A~r6n2H0DQVQsQHQ.

Properties

Property	Modifier	Type	Default value	Description
backend	readonly	string	undefined	Storage backend serving the volume.
createdAt	readonly	Date | undefined	undefined	Creation time, if reported.
id	readonly	string	undefined	Stable volume id.
mountPath	readonly	string | undefined	undefined	Guest mount path, when loaded via Volume.fromMount.
name	readonly	string	undefined	Volume name.
status	readonly	string	undefined	Lifecycle status.
updatedAt	readonly	Date | undefined	undefined	Last-update time, if reported.

Methods

delete()

delete(options?): Promise<boolean>

Delete this volume. Resolves true if it was deleted, false if it was already gone (only possible with allowMissing).

Parameters

Parameter	Type
options	DeleteVolumeOptions

Returns

Promise<boolean>

find()

static find(name, options?): Promise<Volume>

Look up an NFS volume by name, optionally minting it if missing.

Parameters

Parameter	Type
name	string
options	FindVolumeOptions

Returns

Promise<Volume>

fromMount()

static fromMount(path): Volume

Guest-side: load the volume handle for a path mounted into this Sailbox (reads the mount’s metadata; only available inside a guest).

Parameters

Parameter	Type
path	string

Returns

Volume

list()

static list(options?): Promise<Volume[]>

List NFS volumes in the current org.

Parameters

Parameter	Type
options	ListVolumesOptions

Returns

Promise<Volume[]>

---

ingressAuthHeaders()

ingressAuthHeaders(): Record<string, string>

Guest-side: headers that authenticate this Sailbox as an ingress allowlist source (only available inside a Sailbox guest).

Returns

Record<string, string>

---

Client

A configured Sail client: the low-level surface over the native core (one config snapshot; env vars are read at construction). Every client operation is here. The object-model API (Sailbox, App, Volume) is built on top of it.

Construct with Client.fromEnv or Client.fromConfig.

Methods

buildImageDefinition()

buildImageDefinition(def, timeoutSeconds): Promise<ImageSpec>

Resolve an image definition and build it to ready, returning the content-addressed ImageSpec to create Sailboxes from. A bare builtin base skips the build; timeoutSeconds bounds the whole pipeline (hashing, uploads, and the build).

Sail may boot the image outside of any Sailbox — once as the final stage of the build, and again periodically while the image is in active use — to capture and refresh a start snapshot so Sailboxes created from it skip the cold boot. Boot-time initialization therefore runs at times you don’t control, and anything it writes becomes part of the snapshot shared by every Sailbox created from this image — generate per-instance identity (machine IDs, nonces, cached credentials) at runtime, not during boot. Per-Sailbox environment, networking, and credentials are injected at create time either way. See “Hidden boots and start snapshots” in the Sailbox images guide.

Parameters

Parameter	Type
def	ImageDefinition
timeoutSeconds	number

Returns

Promise<ImageSpec>

buildSpecToReady()

buildSpecToReady(spec, timeoutSeconds): Promise<ImageBuild>

Build an already-resolved spec to ready (submit + poll), bounded by timeoutSeconds.

Parameters

Parameter	Type
spec	ImageSpec
timeoutSeconds	number

Returns

Promise<ImageBuild>

checkpointSailbox()

checkpointSailbox(sailboxId, options?): Promise<SailboxCheckpoint>

Take a checkpoint of a Sailbox. name sets the handle’s display name; ttlSeconds, when given, overrides the server’s default retention window.

Parameters

Parameter	Type
sailboxId	string
options	CheckpointOptions

Returns

Promise<SailboxCheckpoint>

createFromCheckpoint()

createFromCheckpoint(params): Promise<SailboxHandle>

Create a new Sailbox from a checkpoint.

Parameters

Parameter	Type
params	FromCheckpointRequest

Returns

Promise<SailboxHandle>

createSailbox()

createSailbox(req, timeoutSeconds?): Promise<SailboxHandle>

Create a Sailbox. timeoutSeconds bounds each create attempt (default 600s); pass 0 for no client-side timeout. A timed-out attempt is retried, and a retry usually reattaches to the Sailbox already coming up rather than starting another. When the overall budget is exhausted the Sailbox may still be coming up server-side: find or terminate it by name. image defaults to a plain Debian base.

Parameters

Parameter	Type	Default value
req	CreateSailboxRequest	undefined
timeoutSeconds	number	600

Returns

Promise<SailboxHandle>

deleteVolume()

deleteVolume(volumeId, allowMissing?): Promise<VolumeInfo | null>

Delete a volume by id. allowMissing tolerates an already-deleted volume, resolving null instead of throwing.

Parameters

Parameter	Type	Default value
volumeId	string	undefined
allowMissing	boolean	false

Returns

Promise<VolumeInfo | null>

enableSsh()

enableSsh(sailboxId, options?): Promise<SshEndpoint | null>

Enable SSH on a Sailbox: trust the org SSH CA, start sshd, and expose guest port 22 as TCP once the CA-only daemon owns it. A non-empty allowlist restricts port 22 to those source addresses or ranges, replacing any existing restriction. With wait (the default), polls until the endpoint is reachable and returns it, throwing TimeoutError if it is not within timeoutSeconds; with wait: false, skips the probe and resolves null.

Parameters

Parameter	Type
sailboxId	string
options	EnableSshOptions

Returns

Promise<SshEndpoint | null>

exec()

exec(sailboxId, command, options?): Promise<ExecProcess>

Run a command in a Sailbox and return a handle to the live process. A string command is run via /bin/sh -lc; a string[] is exec’d directly. cwd/background apply to string commands (see ExecOptions). Stopping the command is the caller’s job via ExecProcess.cancel.

Parameters

Parameter	Type
sailboxId	string
command	string | readonly string[]
options	ExecOptions

Returns

Promise<ExecProcess>

exposeListener()

exposeListener(sailboxId, guestPort, protocol?, allowlist?): Promise<Listener>

Expose a guest port at runtime. Re-exposing a port under the same protocol sets its allowlist to what you pass, so pass the whole list every time; an empty one clears the restriction and reopens the port. The route status starts “unknown”: the response confirms configuration, not reachability.

Parameters

Parameter	Type	Default value
sailboxId	string	undefined
guestPort	number	undefined
protocol	IngressProtocol	"http"
allowlist	readonly string[]	[]

Returns

Promise<Listener>

findApp()

findApp(name, mintIfMissing?): Promise<AppInfo>

Find an app by name; mintIfMissing creates it when absent.

Parameters

Parameter	Type	Default value
name	string	undefined
mintIfMissing	boolean	false

Returns

Promise<AppInfo>

forkSailbox()

forkSailbox(sailboxId, options?): Promise<SailboxHandle>

Fork a Sailbox into a new running child: a copy of its memory and writable disk as they are now, with no durable checkpoint created (see Sailbox.fork). Sometimes the child comes up cold instead, with the disk intact and nothing running, and a child that mounts a volume always does. The parent may be running, sleeping, or paused.

Parameters

Parameter	Type
sailboxId	string
options	ForkSailboxOptions

Returns

Promise<SailboxHandle>

getListener()

getListener(sailboxId, guestPort): Promise<Listener>

Fetch one listener by guest port without waking the Sailbox.

Parameters

Parameter	Type
sailboxId	string
guestPort	number

Returns

Promise<Listener>

getSailbox()

getSailbox(sailboxId): Promise<SailboxInfo>

Fetch one Sailbox by id.

Parameters

Parameter	Type
sailboxId	string

Returns

Promise<SailboxInfo>

getVolume()

getVolume(name, mintIfMissing?): Promise<VolumeInfo>

Look up an NFS volume by name; mintIfMissing creates it when absent.

Parameters

Parameter	Type	Default value
name	string	undefined
mintIfMissing	boolean	false

Returns

Promise<VolumeInfo>

ingressAuthHeaders()

ingressAuthHeaders(sailboxId): Promise<Record<string, string>>

Ingress-identity headers for this Sailbox, as a name→value map.

Parameters

Parameter	Type
sailboxId	string

Returns

Promise<Record<string, string>>

isBuiltinBaseSpec()

isBuiltinBaseSpec(spec): boolean

Whether a spec is a bare builtin base the backend ships prebuilt (no build needed).

Parameters

Parameter	Type
spec	ImageSpec

Returns

boolean

listApps()

listApps(): Promise<AppInfo[]>

Every app the current org owns, newest first.

Returns

Promise<AppInfo[]>

listDir()

listDir(sailboxId, path): Promise<DirEntry[]>

List a directory’s immediate entries as structured records.

Parameters

Parameter	Type
sailboxId	string
path	string

Returns

Promise<DirEntry[]>

listListeners()

listListeners(sailboxId): Promise<Listener[]>

List a Sailbox’s listeners without waking it.

Parameters

Parameter	Type
sailboxId	string

Returns

Promise<Listener[]>

listSailboxes()

listSailboxes(params?): Promise<SailboxInfoPage>

List one page of Sailboxes in the current org.

Parameters

Parameter	Type
params	ListSailboxesQuery

Returns

Promise<SailboxInfoPage>

listVolumes()

listVolumes(maxObjects?): Promise<VolumeInfo[]>

List NFS volumes in the current org.

Parameters

Parameter	Type
maxObjects?	number

Returns

Promise<VolumeInfo[]>

makeDir()

makeDir(sailboxId, path): Promise<void>

Create a directory and any missing parents (like mkdir -p); a no-op if it already exists.

Parameters

Parameter	Type
sailboxId	string
path	string

Returns

Promise<void>

orgSshCaPublicKey()

orgSshCaPublicKey(): Promise<string>

Fetch (creating on first use) the org SSH certificate authority public key. Used to preflight SSH before a Sailbox is provisioned.

Returns

Promise<string>

pathExists()

pathExists(sailboxId, path): Promise<boolean>

Whether path exists in the guest.

Parameters

Parameter	Type
sailboxId	string
path	string

Returns

Promise<boolean>

pauseSailbox()

pauseSailbox(sailboxId): Promise<void>

Pause a Sailbox in memory.

Parameters

Parameter	Type
sailboxId	string

Returns

Promise<void>

readStream()

readStream(sailboxId, path): Promise<FileStream>

Open a streaming read of a guest file.

Parameters

Parameter	Type
sailboxId	string
path	string

Returns

Promise<FileStream>

removePath()

removePath(sailboxId, path): Promise<void>

Remove a file or directory tree (like rm -rf); a no-op if it is already absent.

Parameters

Parameter	Type
sailboxId	string
path	string

Returns

Promise<void>

resolveImage()

resolveImage(def): Promise<ImageSpec>

Resolve an image definition into a content-addressed ImageSpec: the core walks local directories (gitignore-style ignore), hashes every file, and uploads content the server does not already have.

Parameters

Parameter	Type
def	ImageDefinition

Returns

Promise<ImageSpec>

resumeSailbox()

resumeSailbox(sailboxId): Promise<SailboxHandle>

Resume a paused or sleeping Sailbox.

Parameters

Parameter	Type
sailboxId	string

Returns

Promise<SailboxHandle>

shell()

shell(sailboxId, command?, options?): Promise<number>

Open an interactive pty session on a Sailbox, bridged to the local terminal: raw keystrokes reach the remote process, output renders locally, and resizes propagate. Resolves with the remote process’s exit code. Requires an interactive terminal (stdin and stdout TTYs).

Parameters

Parameter	Type
sailboxId	string
command?	string
options?	ShellOptions

Returns

Promise<number>

sleepSailbox()

sleepSailbox(sailboxId, wakeAt?): Promise<string | null>

Sleep a Sailbox to disk (wakes on traffic), optionally scheduling a wall-clock wake first. wakeAt is an RFC 3339 timestamp; the returned value is the effective (sooner) wake time, or null when no wake was requested. Most callers use Sailbox.sleep, which takes and returns Date.

Parameters

Parameter	Type
sailboxId	string
wakeAt?	string

Returns

Promise<string | null>

terminateSailbox()

terminateSailbox(sailboxId): Promise<void>

Terminate a Sailbox (idempotent).

Parameters

Parameter	Type
sailboxId	string

Returns

Promise<void>

unexposeListener()

unexposeListener(sailboxId, guestPort): Promise<void>

Remove a runtime ingress port.

Parameters

Parameter	Type
sailboxId	string
guestPort	number

Returns

Promise<void>

upgradeSailbox()

upgradeSailbox(sailboxId): Promise<UpgradeResult>

Upgrade a Sailbox’s runtime (now if running, else at next wake).

Parameters

Parameter	Type
sailboxId	string

Returns

Promise<UpgradeResult>

waitForListener()

waitForListener(sailboxId, guestPort, timeoutSeconds): Promise<Listener>

Block until the listener on guestPort is reachable end to end and return it, throwing TimeoutError after timeoutSeconds. An HTTP listener is ready once the guest server answers; a TCP listener once the guest sends bytes or holds the connection open. A connectivity check, not an application health check.

Parameters

Parameter	Type
sailboxId	string
guestPort	number
timeoutSeconds	number

Returns

Promise<Listener>

writeStream()

writeStream(sailboxId, path, options?): Promise<FileWriter>

Open a streaming upload to a guest file.

Parameters

Parameter	Type
sailboxId	string
path	string
options	WriteOptions

Returns

Promise<FileWriter>

fromConfig()

static fromConfig(config): Client

Build a client from an explicit ClientConfig.

Parameters

Parameter	Type
config	ClientConfig

Returns

Client

fromEnv()

static fromEnv(): Client

Build a client from the environment (SAIL_API_KEY, …).

Returns

Client

---

defaultClient()

defaultClient(): Client

The process-wide client used by the object-model statics (Sailbox, App, Volume) when no explicit client is passed. Created lazily from the environment on first use.

Returns

Client

---

setDefaultClient()

setDefaultClient(client): void

Override (or clear, with undefined) the process-wide default client. Useful for tests or to point the object-model API at an explicitly configured client.

Parameters

Parameter	Type
client	Client | undefined

Returns

void

---

resolveConfig()

resolveConfig(): ResolvedConfig

Resolve the SDK config from the environment (SAIL_API_KEY, SAIL_API_URL, SAILBOX_API_URL, …) and ~/.sail, without requiring an API key. The core is the single source of truth for endpoint resolution.

Returns

ResolvedConfig

---

isSailError()

isSailError(err): err is SailError

Whether err is a SailError, matched on the stable shape (code string plus retryable boolean) rather than the prototype chain. Use it where instanceof can lie: across realms (worker threads, vm contexts) or when two copies of the SDK are loaded. It does not survive structuredClone or postMessage serialization, which strip an Error’s custom fields; send { name, message, code, retryable } yourself when an error must cross a serialization boundary.

Parameters

Parameter	Type
err	unknown

Returns

err is SailError

Types

Plain data types accepted by and returned from the calls above.

AddLocalDir

A tree of local files copied into the image.

Properties

Property	Type	Description
files?	AddLocalDirFile[]	The files to place under remotePath.
remotePath?	string	Absolute guest path of the directory root.

---

AddLocalDirFile

One file within an addLocalDir step.

Properties

Property	Type	Description
contentSha256?	string	SHA-256 of the (already uploaded) file content.
mode?	number	Permission bits (low 9).
relativePath?	string	Path relative to the directory root.

---

AddLocalDirOptions

Options for Image.addLocalDir.

Properties

Property	Type	Description
ignore?	readonly string[]	Gitignore-style patterns to skip (e.g. "*.pyc", "__pycache__/").
ignoreFile?	string	A gitignore-style file whose patterns to skip (e.g. .gitignore).

---

AddLocalFile

One local file copied into the image, referenced by content hash.

Properties

Property	Type	Description
contentSha256?	string	SHA-256 of the (already uploaded) file content.
mode?	number	Permission bits (low 9); 0 means the builder default (0644).
remotePath?	string	Absolute guest path to place the file at.

---

AddLocalFileOptions

Options for Image.addLocalFile.

Properties

Property	Type	Description
mode?	number	Unix mode bits (low 9); omitted uses the builder default (0644).

---

AppInfo

A Sail app.

Properties

Property	Type	Description
createdAt	string	Creation time (RFC 3339).
id	string	Stable app id.
name	string	App name.

---

BaseImage

BaseImage = "debian" | "devbox"

---

CancelOptions

Options for cancelling an exec.

Properties

Property	Type	Description
force?	boolean	Send SIGKILL instead of SIGINT.

---

CheckpointOptions

Options for Sailbox.checkpoint.

Properties

Property	Type	Description
name?	string	Display name for the checkpoint handle.
ttlSeconds?	number	Retention override in whole seconds (must be positive). Set it when you keep a checkpoint to reuse as a template, so the handle does not expire while you still need it; omitted uses the server default.

---

ClientConfig

Explicit client configuration (an alternative to environment resolution).

Extends

• Omit<native.ClientConfig, "mode">

Properties

Property	Type	Description	Inherited from
apiKey	string	Bearer API key. Required.	Omit.apiKey
apiUrl?	string	Override the Sail API URL.	Omit.apiUrl
imagebuilderUrl?	string	Override the image-build endpoint (host:port).	Omit.imagebuilderUrl
ingressUrl?	string	Override the listener ingress base URL (what SAILBOX_INGRESS_URL sets from the environment), for custom or self-hosted Sailbox stacks.	Omit.ingressUrl
sailboxApiUrl?	string	Override the sailbox-API URL.	Omit.sailboxApiUrl

---

ClientOptions

Options for statics that select which Client to use.

Extended by

• FindAppOptions
• FindVolumeOptions
• ListVolumesOptions
• CreateSailboxOptions
• FromCheckpointOptions
• ListSailboxesOptions
• ListSailboxesPageOptions

Properties

Property	Type	Description
client?	Client	Use a specific client instead of the default (env) one.

---

CreateSailboxOptions

Options for Sailbox.create: the create request plus a per-attempt timeout and an optional explicit client. image defaults to a Debian base.

Extends

• Omit<CreateSailboxRequest, "image" | "appId" | "volumeMounts" | "ingressPorts">.ClientOptions

Properties

Property	Type	Description	Overrides	Inherited from
app	string | App	The owning app, or its id.	-	-
client?	Client	Use a specific client instead of the default (env) one.	-	ClientOptions.client
diskLimitGib?	number	Disk limit in whole GiB within the size’s range; the size’s default when omitted.	-	Omit.diskLimitGib
image?	ImageSpec | Image	Image spec, or an Image builder (built and resolved at create). Defaults to a plain Debian base.	-	-
imageBuildTimeoutSeconds?	number	Timeout in seconds for building a custom Image before create (1800).	Omit.imageBuildTimeoutSeconds	-
ingressPorts?	readonly (number | IngressPortInput)[]	Guest ports to expose: a bare number is HTTP shorthand.	-	-
memoryLimitGib?	number	Memory limit in whole GiB within the size’s range; the size’s default when omitted.	-	Omit.memoryLimitGib
name	string	The Sailbox name.	-	Omit.name
private?	boolean	By default a Sailbox is org-wide: any credential in the org can exec, copy files, SSH, or run lifecycle operations on it. true restricts all of that to the creating user. An org admin can override that with a recorded reason for exec, files, setting a wake time, and the pause, sleep, resume, terminate, and upgrade operations. SSH, exposing or removing listeners, and fork/checkpoint/restore stay creator-only. Requires a user-scoped API key.	-	Omit.private
size?	SailboxSize	Resource size; "m" when omitted.	-	CreateSailboxRequest.size
ssh?	boolean	Enable SSH on the new Sailbox after create: trust the org SSH CA, start sshd, and expose guest port 22 as TCP once the CA-only daemon owns it (an explicit port-22 ingress entry contributes just its allowlist). Equivalent to calling Sailbox.enableSsh after create.	Omit.ssh	-
timeoutSeconds?	number	Bounds each create attempt (default 600s); pass 0 for no client-side timeout. A timed-out attempt is retried, and a retry usually reattaches to the Sailbox already coming up rather than starting another. When the overall budget is exhausted the Sailbox may still be coming up server-side: find or terminate it by name.	-	-
volumes?	Readonly<Record<string, string | Volume>>	Shared volumes to mount, mapping an absolute guest path to a Volume or volume id. Volumes are currently in Alpha. To pilot them, reach out in the Sail Slack: https://join.slack.com/t/sailresearchcrew/shared_invite/zt-41pdcym9j-UU0Ey~A~r6n2H0DQVQsQHQ.	-	-

---

CreateSailboxRequest

Extends

• Omit<native.CreateSailboxRequest, "image" | "ingressPorts" | "size" | "volumeMounts">

Properties

Property	Type	Description	Inherited from
appId	string	Identifier of the owning app.	Omit.appId
diskLimitGib?	number	Disk limit in whole GiB within the size’s range; the size’s default when omitted.	Omit.diskLimitGib
image?	ImageSpec	Image to boot; defaults to a plain Debian base when omitted.	-
imageBuildTimeoutSeconds?	number	Budget in seconds for rebuilding the image if Sail needs to rebuild it before the Sailbox is created; the default build budget applies when omitted.	Omit.imageBuildTimeoutSeconds
ingressPorts?	readonly IngressPortInput[]	Guest ports to reserve for ingress.	-
memoryLimitGib?	number	Memory limit in whole GiB within the size’s range; the size’s default when omitted.	Omit.memoryLimitGib
name	string	The Sailbox name.	Omit.name
private?	boolean	By default a Sailbox is org-wide: any credential in the org can exec, copy files, SSH, or run lifecycle operations on it. true restricts all of that to the creating user. An org admin can override that with a recorded reason for exec, files, setting a wake time, and the pause, sleep, resume, terminate, and upgrade operations. SSH, exposing or removing listeners, and fork/checkpoint/restore stay creator-only. Requires a user-scoped API key.	Omit.private
size?	SailboxSize	Resource size; "m" when omitted.	-
ssh?	boolean	Enable SSH on the new Sailbox after create: trust the org SSH CA, start sshd, and expose guest port 22 as TCP once the CA-only daemon owns it (an explicit port-22 ingress entry contributes just its allowlist).	Omit.ssh
volumeMounts?	readonly VolumeMountInput[]	NFS volumes to mount.	-

---

DeleteVolumeOptions

Options for Volume.delete.

Properties

Property	Type	Description
allowMissing?	boolean	Tolerate a volume that is already gone instead of throwing.

---

DirEntry

One entry in a directory listing from Sailbox.fs.ls. The shape comes from the core, with type narrowed to the closed set the SDK emits; the generated declaration widens it to string.

Extends

• Omit<native.DirEntry, "type">

Properties

Property	Type	Description	Inherited from
mode	number	Unix permission bits, e.g. 0o644. The file-type bits are not included.	Omit.mode
modifiedTime	number	Last-modified time as a Unix timestamp in seconds (with a fractional part).	Omit.modifiedTime
name	string	The entry’s base name, with no directory prefix.	Omit.name
size	number	Size in bytes as reported by the guest.	Omit.size
type	DirEntryType	-	-

---

DirEntryType

DirEntryType = "file" | "directory" | "symlink" | "other"

The kind of a directory entry, reported for the entry itself: a symlink is "symlink" regardless of what it points at.

---

EnableSshOptions

Options for enabling SSH on a Sailbox.

Properties

Property	Type	Description
allowlist?	readonly string[]	Source addresses or ranges allowed to reach port 22, replacing any existing restriction. Left empty, a first enable opens the port to any source, and a re-enable leaves an existing restriction unchanged.
timeoutSeconds?	number	Give up waiting after this many seconds (default 60; Infinity waits indefinitely).
wait?	boolean	Poll until the SSH route is ready (default true).

---

ExecOptions

Options for starting an exec (see the field docs on the generated ExecStartOptions).

Extends

• Omit<native.ExecStartOptions, "env">

Properties

Property	Type	Description	Inherited from
background?	boolean	Detach the command so it keeps running and the call returns immediately; output is discarded (shell commands only, incompatible with openStdin/pty).	Omit.background
cols?	number	Initial pty width in columns.	Omit.cols
cwd?	string	Working directory to run the command in (shell commands only).	Omit.cwd
env?	Readonly<Record<string, string>>	Extra environment for the command. Entries override the guest’s defaults and the image env, but a few reserved variables that identify the Sailbox (such as SAILBOX_ID) cannot be overridden.	-
idempotencyKey?	string	Stable key so a reconnect reattaches to the same command.	Omit.idempotencyKey
openStdin?	boolean	Leave stdin open for writeStdin.	Omit.openStdin
pty?	boolean	Allocate a pseudo-terminal.	Omit.pty
rows?	number	Initial pty height in rows.	Omit.rows
term?	string	TERM value for the pty.	Omit.term
timeoutSeconds?	number	Wall-clock limit in seconds before the server kills the command.	Omit.timeoutSeconds

---

ExecResult

The authoritative result of a finished exec.

The buffered stdout/stderr are a capped, drop-oldest tail (the server keeps a bounded ring). To capture the complete output of a large-output command, stream it live and consult the *Truncated/*Complete flags.

Properties

Property	Type	Description
exitCode	number	The command’s exit code.
stderr	string	Buffered stderr (a capped tail; see stderrTruncated/stderrComplete).
stderrComplete	boolean	True if the live stream delivered stderr through to exit (see stdoutComplete).
stderrTruncated	boolean	True if buffered stderr dropped its oldest bytes (ring overflow).
stdout	string	Buffered stdout (a capped tail; see stdoutTruncated/stdoutComplete).
stdoutComplete	boolean	True if the live stream delivered stdout through to exit: a consumer that streamed live already has the complete stdout even if stdout here is truncated.
stdoutTruncated	boolean	True if buffered stdout dropped its oldest bytes (ring overflow).
timedOut	boolean	Whether the command was killed for exceeding its timeout.

---

ExposeOptions

Options for Sailbox.expose.

Properties

Property	Type	Description
allowlist?	readonly string[]	Sources allowed to reach the port: an address or a range, or a Sail app name on an http listener. An app name cannot read as an address or a range, and cannot contain a /. An address must not carry an IPv6 zone, such as fe80::1%eth0, which names an interface on one machine rather than a source. Empty allows all.
protocol?	IngressProtocol	Wire protocol to expose (default "http").

---

FindAppOptions

Options for App.find.

Extends

• ClientOptions

Properties

Property	Type	Description	Inherited from
client?	Client	Use a specific client instead of the default (env) one.	ClientOptions.client
mintIfMissing?	boolean	Create the app when it does not exist yet.	-

---

FindVolumeOptions

Options for Volume.find.

Extends

• ClientOptions

Properties

Property	Type	Description	Inherited from
client?	Client	Use a specific client instead of the default (env) one.	ClientOptions.client
mintIfMissing?	boolean	Create the volume when it does not exist yet.	-

---

ForkSailboxOptions

Options for Sailbox.fork.

Properties

Property	Type	Description
name?	string	Display name for the child Sailbox; the server derives one when omitted.
timeoutSeconds?	number	Whole seconds, positive when given. Accepted and ignored: the call blocks until the fork finishes, so apply your own deadline if you need one.

---

FromCheckpointOptions

Options for Sailbox.fromCheckpoint.

Extends

• FromCheckpointRequest.ClientOptions

Properties

Property	Type	Description	Inherited from
checkpointId	string	The checkpoint to restore from.	FromCheckpointRequest.checkpointId
client?	Client	Use a specific client instead of the default (env) one.	ClientOptions.client
name?	string	Name for the new Sailbox. Defaults to the name of the Sailbox the checkpoint came from with -fork appended.	FromCheckpointRequest.name
timeoutSeconds?	number	Whole seconds, positive when given. Accepted and ignored: the call blocks until the restore finishes, so apply your own deadline if you need one.	FromCheckpointRequest.timeoutSeconds

---

FromCheckpointRequest

The create-from-checkpoint request.

Extended by

• FromCheckpointOptions

Properties

Property	Type	Description
checkpointId	string	The checkpoint to restore from.
name?	string	Name for the new Sailbox. Defaults to the name of the Sailbox the checkpoint came from with -fork appended.
timeoutSeconds?	number	Whole seconds, positive when given. Accepted and ignored: the call blocks until the restore finishes, so apply your own deadline if you need one.

---

HttpEndpoint

The routable HTTPS address of an http listener.

Properties

Property	Type	Description
kind	"http"	-
url	string	The HTTPS URL to reach the guest service.

---

ImageArchitecture

ImageArchitecture = "amd64" | "arm64"

---

ImageBuild

The state of a custom image build.

Extends

• Omit<native.ImageBuild, "status">

Properties

Property	Type	Description	Inherited from
errorMessage?	string	Human-readable failure detail; present when status is failed.	Omit.errorMessage
imageId	string	The content-addressed image id.	Omit.imageId
status	ImageBuildStatus	-	-

---

ImageBuildOptions

Options for Image.build.

Properties

Property	Type	Description
client?	Client	Use a specific client instead of the default (env) one.
timeoutSeconds?	number	Timeout in seconds bounding the whole pipeline: hashing, uploads, and the build (default 1800).

---

ImageBuildStatus

ImageBuildStatus = "unknown" | "queued" | "building" | "ready" | "failed"

The status of a custom image build.

---

ImageBuildStep

ImageBuildStep = { addLocalDir?: never; addLocalFile?: never; aptInstall: PackageInstall; pipInstall?: never; runCommand?: never; } | { addLocalDir?: never; addLocalFile?: never; aptInstall?: never; pipInstall: PackageInstall; runCommand?: never; } | { addLocalDir?: never; addLocalFile?: never; aptInstall?: never; pipInstall?: never; runCommand: RunCommand; } | { addLocalDir?: never; addLocalFile: AddLocalFile; aptInstall?: never; pipInstall?: never; runCommand?: never; } | { addLocalDir: AddLocalDir; addLocalFile?: never; aptInstall?: never; pipInstall?: never; runCommand?: never; }

One build step: exactly one operation. Each union member never-types the other operations, so a step that sets two of them is a compile error (a bare union of the operations would accept it).

---

ImageDefinition

A custom image definition: a base image plus ordered build steps, where local-file steps still reference paths on this machine.

Properties

Property	Type	Description
architecture?	string	Target CPU architecture: amd64 or arm64; unset lets the backend choose.
base?	string	Base image to build on: debian or devbox.
env?	Record<string, string>	Environment variables baked into the image.
pythonVersion?	string	Exact Python version to install as python3; unset uses the builder default.
steps?	ImageDefinitionStep[]	Ordered build steps.

---

ImageDefinitionStep

One image-definition step. Exactly one of the fields must be set.

Properties

Property	Type	Description
addLocalDir?	LocalDirInput	Bake a local directory tree into the image.
addLocalFile?	LocalFileInput	Bake one local file into the image.
aptInstall?	string[]	Install system packages with apt.
pipInstall?	string[]	Install Python packages with pip.
runCommand?	string	Run a shell command during the build.

---

ImageSpec

A Sailbox image: a base image plus ordered build steps.

Extends

• Omit<native.ImageSpec, "base" | "buildSteps" | "architecture" | "filesystem">

Properties

Property	Type	Description	Inherited from
architecture?	ImageArchitecture	Target CPU architecture; unset lets the backend choose.	-
base?	BaseImage	Base image to build on.	-
buildSteps?	ImageBuildStep[]	Ordered build steps applied on top of the base image.	-
env?	Record<string, string>	Environment variables baked into the image.	Omit.env
pythonVersion?	string	Exact Python version to install as python3; unset uses the builder default.	Omit.pythonVersion

---

IngressPortInput

A guest port to reserve for ingress at create time.

Extends

• Omit<native.IngressPortInput, "protocol" | "allowlist">

Properties

Property	Type	Description	Inherited from
allowlist?	readonly string[]	Sources allowed to reach the port: an address or a range, or a Sail app name on an http listener. An app name cannot read as an address or a range, and cannot contain a /. An address must not carry an IPv6 zone, such as fe80::1%eth0, which names an interface on one machine rather than a source. Empty allows all.	-
guestPort	number	The in-guest port to expose (1-65535).	Omit.guestPort
protocol	IngressProtocol	http or tcp.	-

---

IngressProtocol

IngressProtocol = "tcp" | "http"

The protocol you request when exposing a port.

---

IngressScheme

IngressScheme = "path" | "subdomain"

How a listener’s URL is addressed under ingressBase.

---

ListSailboxesOptions

Options for Sailbox.list: the server-side filters, a total-cap limit, and an optional client.

Extends

• Omit<ListSailboxesQuery, "limit" | "offset">.ClientOptions

Properties

Property	Type	Description	Inherited from
appId?	string	Filter to one app by its id.	Omit.appId
client?	Client	Use a specific client instead of the default (env) one.	ClientOptions.client
limit?	number	Cap on the total number of Sailboxes returned, bounding the fetch for large orgs; omit to fetch every match.	-
order?	SailboxListOrder	Result ordering; "newest_active" (most recently active first) when omitted; "newest_created" lists the newest-created first.	ListSailboxesQuery.order
search?	string	Substring filter on the Sailbox name.	Omit.search
status?	SailboxStatusFilter	Filter by lifecycle status.	ListSailboxesQuery.status

---

ListSailboxesPageOptions

Options for Sailbox.listPage: the same filters as ListSailboxesOptions, plus limit/offset page selection and an optional client.

Extends

• ListSailboxesQuery.ClientOptions

Properties

Property	Type	Description	Inherited from
appId?	string	Filter to one app by its id.	Omit.appId
client?	Client	Use a specific client instead of the default (env) one.	ClientOptions.client
limit?	number	Page size.	Omit.limit
offset?	number	Page offset.	Omit.offset
order?	SailboxListOrder	Result ordering; "newest_active" (most recently active first) when omitted; "newest_created" lists the newest-created first.	ListSailboxesQuery.order
search?	string	Substring filter on the Sailbox name.	Omit.search
status?	SailboxStatusFilter	Filter by lifecycle status.	ListSailboxesQuery.status

---

ListSailboxesQuery

Filters for listing Sailboxes.

Extends

• Omit<native.ListSailboxesQuery, "status" | "order">

Properties

Property	Type	Description	Inherited from
appId?	string	Filter to one app by its id.	Omit.appId
limit?	number	Page size.	Omit.limit
offset?	number	Page offset.	Omit.offset
order?	SailboxListOrder	Result ordering; "newest_active" (most recently active first) when omitted; "newest_created" lists the newest-created first.	-
search?	string	Substring filter on the Sailbox name.	Omit.search
status?	SailboxStatusFilter	Filter by lifecycle status.	-

---

ListVolumesOptions

Options for Volume.list.

Extends

• ClientOptions

Properties

Property	Type	Description	Inherited from
client?	Client	Use a specific client instead of the default (env) one.	ClientOptions.client
maxObjects?	number	Maximum number of volumes to return.	-

---

Listener

An exposed guest port and how to reach it.

Properties

Property	Type	Description
endpoint?	ListenerEndpoint	How to reach the port; undefined until the listener is routable.
guestPort	number	The in-guest port traffic is forwarded to.
protocol	Protocol	Wire protocol exposed.
routeStatus	ListenerRouteStatus	Status of the listener’s ingress route.

---

ListenerEndpoint

ListenerEndpoint = HttpEndpoint | TcpEndpoint

How to reach an exposed listener; discriminate on kind.

---

ListenerRouteStatus

ListenerRouteStatus = "unknown" | "pending" | "active" | "restoring" | "unavailable" | string & object

Status of a listener’s ingress route (open: tolerates unknown values).

---

LocalDirInput

A local directory tree to bake into the image (walked, hashed, and uploaded at resolve; symlinks skipped, file modes preserved).

Properties

Property	Type	Description
ignore?	string[]	Gitignore-style patterns to skip.
ignoreFile?	string	A gitignore-style file whose patterns to skip (e.g. .gitignore).
localPath	string	Path on this machine.
remotePath	string	Absolute POSIX path of the directory root inside the image.

---

LocalFileInput

One local file to bake into the image (hashed and uploaded at resolve).

Properties

Property	Type	Description
localPath	string	Path on this machine.
mode?	number	Permission bits (low 9); omitted uses the builder default (0644).
remotePath	string	Absolute POSIX path inside the image; a trailing / appends the source basename.

---

PackageInstall

A set of packages to install (apt or pip).

Properties

Property	Type	Description
packages?	string[]	Package names.

---

Protocol

Protocol = "tcp" | "http" | string & object

The protocol reported on a listener (open: tolerates unknown values).

---

ResolvedConfig

The config resolved from the environment and ~/.sail.

Extends

• Omit<native.ResolvedConfig, "ingressScheme" | "mode">

Properties

Property	Type	Description	Inherited from
apiKey?	string	The resolved API key; absent when none is configured.	Omit.apiKey
apiUrl	string	Sail API URL.	Omit.apiUrl
imagebuilderUrl	string	Image-build endpoint (host:port).	Omit.imagebuilderUrl
ingressBase	string	Base host/URL public listeners are addressed under.	Omit.ingressBase
ingressScheme	IngressScheme	-	-
sailboxApiUrl	string	Sailbox-API URL.	Omit.sailboxApiUrl

---

RunCommand

A shell command to run during the build.

Properties

Property	Type	Description
command?	string	The command, run via the builder’s shell.

---

RunOptions

Options for Sailbox.run: the subset of ExecOptions that fits a buffered, run-to-completion command.

Extends

• Pick<ExecOptions, "timeoutSeconds" | "cwd" | "env" | "idempotencyKey">

Properties

Property	Type	Description	Inherited from
check?	boolean	Reject with CommandFailedError (carrying the completed result) when the command exits nonzero or times out, instead of resolving.	-
cwd?	string	Working directory to run the command in (shell commands only).	Pick.cwd
env?	Readonly<Record<string, string>>	Extra environment for the command. Entries override the guest’s defaults and the image env, but a few reserved variables that identify the Sailbox (such as SAILBOX_ID) cannot be overridden.	ExecOptions.env
idempotencyKey?	string	Stable key so a reconnect reattaches to the same command.	Pick.idempotencyKey
signal?	AbortSignal	Aborting rejects with the signal’s reason and force-cancels the remote command (SIGKILL, like ExecProcess.cancel with force), briefly retrying transient failures. Best effort: the kill is sent once the submission settles (an abort mid-submission cancels the command as soon as its launch is confirmed), and a kill that still fails leaves the command running.	-
timeoutSeconds?	number	Wall-clock limit in seconds before the server kills the command.	Pick.timeoutSeconds

---

SailboxCheckpoint

A durable checkpoint handle.

Extends

• Omit<native.SailboxCheckpoint, "status" | "expiresAt">

Properties

Property	Type	Description	Inherited from
checkpointGeneration	number	Checkpoint generation captured by this checkpoint.	Omit.checkpointGeneration
checkpointId	string	The checkpoint id.	Omit.checkpointId
expiresAt?	Date	When the checkpoint expires: seven days out unless a TTL asked for a different window. Starting a Sailbox from it after that fails.	-
sailboxId	string	The Sailbox the checkpoint was taken from.	Omit.sailboxId
status	SailboxStatus	-	-

---

SailboxDeprecation

SailboxDeprecation = native.SailboxDeprecation

Actionable notice that a Sailbox’s runtime should be upgraded: a deadline date and a message with upgrade instructions.

---

SailboxHandle

Returned by create / resume / fromCheckpoint: the Sailbox’s identity and lifecycle status.

Properties

Property	Type	Description
name	string	The caller-supplied Sailbox name.
sailboxId	string	The Sailbox’s stable identifier.
status	SailboxStatus	Lifecycle status at the time the operation completed.

---

SailboxInfo

A read snapshot of a Sailbox (get / list). Timestamps are RFC 3339 strings.

Extends

• Omit<native.SailboxInfo, "status">

Properties

Property	Type	Description	Inherited from
appId	string	Identifier of the owning app.	Omit.appId
appName	string	Name of the owning app.	Omit.appName
architecture	string	CPU architecture (for example arm64).	Omit.architecture
checkpointGeneration	number	Monotonic checkpoint generation counter.	Omit.checkpointGeneration
cpuRequestedVcpu	number	Requested CPU, in vCPUs.	Omit.cpuRequestedVcpu
cpuUsedVcpu	number	Current CPU usage, in vCPUs.	Omit.cpuUsedVcpu
createdAt	string	When the Sailbox was created (RFC 3339).	Omit.createdAt
createdByUserId?	string	The user whose credential created this Sailbox (for a fork or restore, the user who ran it). Absent for service-key creates.	Omit.createdByUserId
deprecation?	SailboxDeprecation	Actionable runtime deprecation notice, when an upgrade is needed.	Omit.deprecation
diskRequestedBytes	number	Requested disk, in bytes.	Omit.diskRequestedBytes
diskUsedBytes	number	Current disk usage, in bytes.	Omit.diskUsedBytes
errorMessage?	string	Human-readable error detail when the Sailbox is in an error state.	Omit.errorMessage
guestSchemaVersion?	number	The Sailbox runtime schema version the Sailbox last booted with.	Omit.guestSchemaVersion
imageId	string	Identifier of the image the Sailbox was created from.	Omit.imageId
lastCheckpointedAt?	string	When the most recent checkpoint was taken, if any (RFC 3339).	Omit.lastCheckpointedAt
memoryMib	number	Configured memory, in MiB.	Omit.memoryMib
memoryRequestedBytes	number	Requested memory, in bytes.	Omit.memoryRequestedBytes
memoryUsedBytes	number	Current memory usage, in bytes.	Omit.memoryUsedBytes
name	string	The Sailbox name.	Omit.name
sailboxId	string	The Sailbox id.	Omit.sailboxId
startedAt?	string	When the Sailbox first started running, if it ever has (RFC 3339). A resume does not rewrite it.	Omit.startedAt
stateDiskSizeGib	number	Configured state-disk size, in GiB.	Omit.stateDiskSizeGib
status	SailboxStatus	-	-
updatedAt	string	When the Sailbox was last updated (RFC 3339).	Omit.updatedAt
vcpuCount	number	Configured number of vCPUs.	Omit.vcpuCount
visibility?	string	"private" when access is restricted to the creator; absent/"org" is the default org-wide access.	Omit.visibility

---

SailboxInfoPage

One page of list results plus the pagination envelope.

Extends

• Omit<native.SailboxInfoPage, "items">

Properties

Property	Type	Description	Inherited from
hasMore	boolean	Whether more results exist past this page.	Omit.hasMore
items	SailboxInfo[]	-	-
limit	number	The page size that was applied.	Omit.limit
offset	number	The offset that was applied.	Omit.offset
total	number	Total matching Sailboxes across all pages.	Omit.total

---

SailboxListOrder

SailboxListOrder = "newest_active" | "newest_created"

Result ordering for a Sailbox list: most recently active first, or newest created first.

---

SailboxPage

One page of Sailbox instances plus the pagination envelope.

Extends

• Omit<SailboxInfoPage, "items">

Properties

Property	Type	Description	Inherited from
hasMore	boolean	Whether more results exist past this page.	Omit.hasMore
items	Sailbox[]	-	-
limit	number	The page size that was applied.	Omit.limit
offset	number	The offset that was applied.	Omit.offset
total	number	Total matching Sailboxes across all pages.	Omit.total

---

SailboxSize

SailboxSize = "s" | "m" | "l"

Named resource size; each sets the vCPU count plus default memory/disk.

---

SailboxStatus

SailboxStatus = "running" | "paused" | "sleeping" | "failed" | "terminated" | string & object

Lifecycle status of a Sailbox. Open: tolerates values added server-side.

---

SailboxStatusFilter

SailboxStatusFilter = "running" | "paused" | "sleeping" | "failed" | "terminated"

The closed set of statuses accepted as a list filter.

---

ShellOptions

Options for Sailbox.shell.

Properties

Property	Type	Description
cwd?	string	Working directory for the session.
noForward?	boolean	While attached, the Sailbox’s browser opens and localhost servers reach your machine, files dragged onto the terminal upload and paste as guest paths, and Ctrl+V forwards your clipboard. On devbox images the clipboard is two-way (pastes land on the Sailbox’s clipboard, and what you copy inside the Sailbox comes back); other images upload a pasted image as a file and paste its path. Set true to turn all of it off, for example for an untrusted or automated session.
noForwardBrowser?	boolean	Set true to keep everything forwarded except browser opens. Ignored when noForward is set.
shell?	string	Login shell to run when no command is given (default: the guest’s $SHELL, else /bin/bash). Ignored when a command is given.
term?	string	$TERM for the remote pty (default: the local $TERM).
timeoutSeconds?	number	Wall-clock limit for the session in seconds; omit for no limit.

---

SshEndpoint

The public TCP endpoint a Sailbox’s SSH listener is reachable at.

Properties

Property	Type	Description
host	string	Hostname to dial.
port	number	Port to dial.

---

TcpEndpoint

The address to dial for a tcp listener.

Properties

Property	Type	Description
host	string	Hostname to dial.
kind	"tcp"	-
port	number	Port to dial.

---

UpgradeResult

The outcome of a Sailbox runtime upgrade.

Extends

• Omit<native.UpgradeResult, "status">

Properties

Property	Type	Description	Inherited from
applied	boolean	True when no upgrade is left to apply, either because the Sailbox took one just now or because it was already current. False when the upgrade is recorded and takes effect the next time the Sailbox wakes.	Omit.applied
status	SailboxStatus	-	-

---

VolumeInfo

A managed NFS volume. Timestamps are RFC 3339 strings.

Properties

Property	Type	Description
backend	string	Storage backend serving the volume.
createdAt?	string	Creation time (RFC 3339), if reported.
name	string	The volume name.
status	string	Lifecycle status.
updatedAt?	string	Last-update time (RFC 3339), if reported.
volumeId	string	The volume id.

---

VolumeMountInput

An NFS volume to mount at create time.

Properties

Property	Type	Description
mountPath	string	Absolute guest path to mount at.
volumeId	string	The volume id (from getVolume/listVolumes).

---

WaitForListenerOptions

Options for Sailbox.waitForListener.

Properties

Property	Type	Description
signal?	AbortSignal	Aborting stops the wait and rejects with the signal’s reason. An abandoned in-flight probe winds down on its own (by timeoutSeconds at the latest); it does not touch the listener. Because the wind-down relies on the timeout, signal requires a finite timeoutSeconds.
timeoutSeconds?	number	Give up waiting after this many seconds (default 60; Infinity waits indefinitely).

---

WriteOptions

Options for uploading a file.

Properties

Property	Type	Description
createParents?	boolean	Create missing parent directories.
mode?	number	Unix mode bits for the written file.

Errors

Errors thrown by this SDK surface. All of them extend SailError, so an instanceof SailError check matches everything below.

SailError

Base class for every error surfaced by the SDK.

Extends

• Error

Extended by

• InvalidArgumentError
• InternalError
• NotFoundError
• PermissionDeniedError
• FileNotFoundError
• BrokenPipeError
• TimeoutError
• TransportError
• ApiError
• SailboxCreationError
• ImageBuildError
• SailboxExecutionError

Constructors

Constructor

new SailError(message, code?, details?): SailError

Parameters

Parameter	Type	Default value
message	string	undefined
code	string	"SailError"
details	SailErrorDetails	{}

Returns

SailError

Overrides

Error.constructor

Properties

Property	Modifier	Type	Description
code	readonly	string	Stable, language-neutral error code (e.g. "NotFound").
retryable	readonly	boolean	Advisory: true when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient RPC failure). false when the failure is deterministic (bad argument, missing resource, permission). The SDK’s built-in retry already covers the transient window for most calls; this classifies what leaks past it.

---

ApiError

A non-2xx API response.

Extends

• SailError

Constructors

Constructor

new ApiError(message, details?): ApiError

Parameters

Parameter	Type
message	string
details	SailErrorDetails

Returns

ApiError

Overrides

SailError.constructor

Properties

Property	Modifier	Type	Description	Inherited from
body?	readonly	unknown	Parsed response body from the failed request, when available.	-
code	readonly	string	Stable, language-neutral error code (e.g. "NotFound").	SailError.code
retryable	readonly	boolean	Advisory: true when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient RPC failure). false when the failure is deterministic (bad argument, missing resource, permission). The SDK’s built-in retry already covers the transient window for most calls; this classifies what leaks past it.	SailError.retryable
status?	readonly	number	HTTP status code returned by the API, when the failure carries one.	-

---

BrokenPipeError

A stream (e.g. exec stdin) was closed and can no longer be written.

Extends

• SailError

Constructors

Constructor

new BrokenPipeError(message, details?): BrokenPipeError

Parameters

Parameter	Type
message	string
details	SailErrorDetails

Returns

BrokenPipeError

Overrides

SailError.constructor

Properties

Property	Modifier	Type	Description	Inherited from
code	readonly	string	Stable, language-neutral error code (e.g. "NotFound").	SailError.code
retryable	readonly	boolean	Advisory: true when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient RPC failure). false when the failure is deterministic (bad argument, missing resource, permission). The SDK’s built-in retry already covers the transient window for most calls; this classifies what leaks past it.	SailError.retryable

---

CommandFailedError

Thrown by Sailbox.run with check when the command exits nonzero or times out. Carries the completed result as result.

Extends

• SailboxExecutionError

Constructors

Constructor

new CommandFailedError(message, result): CommandFailedError

Parameters

Parameter	Type
message	string
result	ExecResult

Returns

CommandFailedError

Overrides

SailboxExecutionError.constructor

Properties

Property	Modifier	Type	Description	Inherited from
code	readonly	string	Stable, language-neutral error code (e.g. "NotFound").	SailboxExecutionError.code
result	readonly	ExecResult	-	-
retryable	readonly	boolean	Advisory: true when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient RPC failure). false when the failure is deterministic (bad argument, missing resource, permission). The SDK’s built-in retry already covers the transient window for most calls; this classifies what leaks past it.	SailboxExecutionError.retryable
rpcStatus	readonly	string	RPC status classifying the failure (for example "unavailable"), empty when the failure carries no status. Distinct from code, which stays the taxonomy discriminator on every SailError.	SailboxExecutionError.rpcStatus

---

FileNotFoundError

A remote file path does not exist.

Extends

• SailError

Constructors

Constructor

new FileNotFoundError(message, details?): FileNotFoundError

Parameters

Parameter	Type
message	string
details	SailErrorDetails

Returns

FileNotFoundError

Overrides

SailError.constructor

Properties

Property	Modifier	Type	Description	Inherited from
code	readonly	string	Stable, language-neutral error code (e.g. "NotFound").	SailError.code
retryable	readonly	boolean	Advisory: true when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient RPC failure). false when the failure is deterministic (bad argument, missing resource, permission). The SDK’s built-in retry already covers the transient window for most calls; this classifies what leaks past it.	SailError.retryable

---

ImageBuildError

A custom image could not be built or its local content could not be uploaded.

Extends

• SailError

Constructors

Constructor

new ImageBuildError(message, details?): ImageBuildError

Parameters

Parameter	Type
message	string
details	SailErrorDetails

Returns

ImageBuildError

Overrides

SailError.constructor

Properties

Property	Modifier	Type	Description	Inherited from
code	readonly	string	Stable, language-neutral error code (e.g. "NotFound").	SailError.code
retryable	readonly	boolean	Advisory: true when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient RPC failure). false when the failure is deterministic (bad argument, missing resource, permission). The SDK’s built-in retry already covers the transient window for most calls; this classifies what leaks past it.	SailError.retryable

---

InternalError

An unexpected internal SDK/core failure.

Extends

• SailError

Constructors

Constructor

new InternalError(message, details?): InternalError

Parameters

Parameter	Type
message	string
details	SailErrorDetails

Returns

InternalError

Overrides

SailError.constructor

Properties

Property	Modifier	Type	Description	Inherited from
code	readonly	string	Stable, language-neutral error code (e.g. "NotFound").	SailError.code
retryable	readonly	boolean	Advisory: true when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient RPC failure). false when the failure is deterministic (bad argument, missing resource, permission). The SDK’s built-in retry already covers the transient window for most calls; this classifies what leaks past it.	SailError.retryable

---

InvalidArgumentError

Invalid arguments or configuration (bad request, missing/invalid API key).

Extends

• SailError

Constructors

Constructor

new InvalidArgumentError(message, details?): InvalidArgumentError

Parameters

Parameter	Type
message	string
details	SailErrorDetails

Returns

InvalidArgumentError

Overrides

SailError.constructor

Properties

Property	Modifier	Type	Description	Inherited from
code	readonly	string	Stable, language-neutral error code (e.g. "NotFound").	SailError.code
retryable	readonly	boolean	Advisory: true when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient RPC failure). false when the failure is deterministic (bad argument, missing resource, permission). The SDK’s built-in retry already covers the transient window for most calls; this classifies what leaks past it.	SailError.retryable

---

NotFoundError

The Sailbox, volume, or other resource does not exist (or is another org’s).

Extends

• SailError

Constructors

Constructor

new NotFoundError(message, details?): NotFoundError

Parameters

Parameter	Type
message	string
details	SailErrorDetails

Returns

NotFoundError

Overrides

SailError.constructor

Properties

Property	Modifier	Type	Description	Inherited from
code	readonly	string	Stable, language-neutral error code (e.g. "NotFound").	SailError.code
retryable	readonly	boolean	Advisory: true when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient RPC failure). false when the failure is deterministic (bad argument, missing resource, permission). The SDK’s built-in retry already covers the transient window for most calls; this classifies what leaks past it.	SailError.retryable

---

PermissionDeniedError

The credential is not permitted to perform the operation.

Extends

• SailError

Constructors

Constructor

new PermissionDeniedError(message, details?): PermissionDeniedError

Parameters

Parameter	Type
message	string
details	SailErrorDetails

Returns

PermissionDeniedError

Overrides

SailError.constructor

Properties

Property	Modifier	Type	Description	Inherited from
code	readonly	string	Stable, language-neutral error code (e.g. "NotFound").	SailError.code
retryable	readonly	boolean	Advisory: true when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient RPC failure). false when the failure is deterministic (bad argument, missing resource, permission). The SDK’s built-in retry already covers the transient window for most calls; this classifies what leaks past it.	SailError.retryable

---

SailboxCreationError

A Sailbox could not be created (provisioning failed).

Extends

• SailError

Constructors

Constructor

new SailboxCreationError(message, details?): SailboxCreationError

Parameters

Parameter	Type
message	string
details	SailErrorDetails

Returns

SailboxCreationError

Overrides

SailError.constructor

Properties

Property	Modifier	Type	Description	Inherited from
body?	readonly	unknown	Parsed response body from the failed create request, when available.	-
code	readonly	string	Stable, language-neutral error code (e.g. "NotFound").	SailError.code
retryable	readonly	boolean	Advisory: true when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient RPC failure). false when the failure is deterministic (bad argument, missing resource, permission). The SDK’s built-in retry already covers the transient window for most calls; this classifies what leaks past it.	SailError.retryable
status?	readonly	number	HTTP status code returned by the create request, when the failure carries one.	-

---

SailboxExecRequestNotFoundError

The exec request could not be found (for example after the Sailbox moved machines).

Extends

• SailboxExecutionError

Constructors

Constructor

new SailboxExecRequestNotFoundError(message, details?): SailboxExecRequestNotFoundError

Parameters

Parameter	Type
message	string
details	SailErrorDetails

Returns

SailboxExecRequestNotFoundError

Overrides

SailboxExecutionError.constructor

Properties

Property	Modifier	Type	Description	Inherited from
code	readonly	string	Stable, language-neutral error code (e.g. "NotFound").	SailboxExecutionError.code
retryable	readonly	boolean	Advisory: true when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient RPC failure). false when the failure is deterministic (bad argument, missing resource, permission). The SDK’s built-in retry already covers the transient window for most calls; this classifies what leaks past it.	SailboxExecutionError.retryable
rpcStatus	readonly	string	RPC status classifying the failure (for example "unavailable"), empty when the failure carries no status. Distinct from code, which stays the taxonomy discriminator on every SailError.	SailboxExecutionError.rpcStatus

---

SailboxExecutionError

Base class for failures during an exec.

Extends

• SailError

Extended by

• CommandFailedError
• SailboxTerminatedError
• SailboxExecRequestNotFoundError
• SailboxHostLostError

Constructors

Constructor

new SailboxExecutionError(message, code?, details?): SailboxExecutionError

Parameters

Parameter	Type	Default value
message	string	undefined
code	string	"SailboxExecutionError"
details	SailErrorDetails	{}

Returns

SailboxExecutionError

Overrides

SailError.constructor

Properties

Property	Modifier	Type	Description	Inherited from
code	readonly	string	Stable, language-neutral error code (e.g. "NotFound").	SailError.code
retryable	readonly	boolean	Advisory: true when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient RPC failure). false when the failure is deterministic (bad argument, missing resource, permission). The SDK’s built-in retry already covers the transient window for most calls; this classifies what leaks past it.	SailError.retryable
rpcStatus	readonly	string	RPC status classifying the failure (for example "unavailable"), empty when the failure carries no status. Distinct from code, which stays the taxonomy discriminator on every SailError.	-

---

SailboxHostLostError

The machine hosting the Sailbox was lost while an exec was in flight.

Extends

• SailboxExecutionError

Constructors

Constructor

new SailboxHostLostError(message, details?): SailboxHostLostError

Parameters

Parameter	Type
message	string
details	SailErrorDetails

Returns

SailboxHostLostError

Overrides

SailboxExecutionError.constructor

Properties

Property	Modifier	Type	Description	Inherited from
code	readonly	string	Stable, language-neutral error code (e.g. "NotFound").	SailboxExecutionError.code
retryable	readonly	boolean	Advisory: true when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient RPC failure). false when the failure is deterministic (bad argument, missing resource, permission). The SDK’s built-in retry already covers the transient window for most calls; this classifies what leaks past it.	SailboxExecutionError.retryable
rpcStatus	readonly	string	RPC status classifying the failure (for example "unavailable"), empty when the failure carries no status. Distinct from code, which stays the taxonomy discriminator on every SailError.	SailboxExecutionError.rpcStatus

---

SailboxTerminatedError

The Sailbox was terminated while an exec was in flight.

Extends

• SailboxExecutionError

Constructors

Constructor

new SailboxTerminatedError(message, details?): SailboxTerminatedError

Parameters

Parameter	Type
message	string
details	SailErrorDetails

Returns

SailboxTerminatedError

Overrides

SailboxExecutionError.constructor

Properties

Property	Modifier	Type	Description	Inherited from
code	readonly	string	Stable, language-neutral error code (e.g. "NotFound").	SailboxExecutionError.code
retryable	readonly	boolean	Advisory: true when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient RPC failure). false when the failure is deterministic (bad argument, missing resource, permission). The SDK’s built-in retry already covers the transient window for most calls; this classifies what leaks past it.	SailboxExecutionError.retryable
rpcStatus	readonly	string	RPC status classifying the failure (for example "unavailable"), empty when the failure carries no status. Distinct from code, which stays the taxonomy discriminator on every SailError.	SailboxExecutionError.rpcStatus

---

TimeoutError

A request exceeded its timeout.

Extends

• SailError

Constructors

Constructor

new TimeoutError(message, details?): TimeoutError

Parameters

Parameter	Type
message	string
details	SailErrorDetails

Returns

TimeoutError

Overrides

SailError.constructor

Properties

Property	Modifier	Type	Description	Inherited from
code	readonly	string	Stable, language-neutral error code (e.g. "NotFound").	SailError.code
retryable	readonly	boolean	Advisory: true when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient RPC failure). false when the failure is deterministic (bad argument, missing resource, permission). The SDK’s built-in retry already covers the transient window for most calls; this classifies what leaks past it.	SailError.retryable

---

TransportError

A network/connection transport failure.

Extends

• SailError

Constructors

Constructor

new TransportError(message, details?): TransportError

Parameters

Parameter	Type
message	string
details	SailErrorDetails

Returns

TransportError

Overrides

SailError.constructor

Properties

Property	Modifier	Type	Description	Inherited from
code	readonly	string	Stable, language-neutral error code (e.g. "NotFound").	SailError.code
retryable	readonly	boolean	Advisory: true when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient RPC failure). false when the failure is deterministic (bad argument, missing resource, permission). The SDK’s built-in retry already covers the transient window for most calls; this classifies what leaks past it.	SailError.retryable