TypeScript SDK

TypeScript SDK installation and full reference

The Sail TypeScript SDK (@sailresearch/sdk on npm) runs on Node 22+ and Bun. Sail also provides Python and Rust SDKs.

Install

npm

npm install @sailresearch/sdk

The SDK supports Linux x64/arm64 (glibc and musl), macOS x64/arm64, and Windows x64.

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 error is rethrown 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.

sailboxId is the stable identifier. Every other property is a snapshot of what Sailbox.get or Sailbox.list last returned. A lifecycle call on this object, such as pause, updates status, and setAutoSleep and setEgressPolicy update their property. Nothing else changes on this object; Sailbox.get returns a fresh snapshot. The object create and fromCheckpoint return starts with only the id, name, and status.

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

autoSleep

Get Signature

get autoSleep(): AutoSleep | undefined

When Sail may sleep this Sailbox on its own; see AutoSleep.

Returns

AutoSleep | 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 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

egressPolicy

Get Signature

get egressPolicy(): SailboxEgressPolicy | undefined

The egress policy the Sailbox is running under: its document and, when a saved policy was applied, that policy’s id and name.

const sb = await Sailbox.get(id);
sb.egressPolicy?.document.allowlist; // e.g. ["pypi.org"], or undefined for every host
sb.egressPolicy?.name; // the saved policy's name, when one is attached

Returns

SailboxEgressPolicy | undefined

errorMessage

Get Signature

get errorMessage(): string | undefined

Failure detail when the status is failed.

Returns

string | undefined

expiresAt

Get Signature

get expiresAt(): Date | undefined

Termination deadline, checked periodically. Undefined means unlimited lifetime or a handle without a fetched snapshot; use Sailbox.get for fresh state.

Returns

Date | 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 (for example running).

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

volumeMounts

Get Signature

get volumeMounts(): SailboxVolumeMount[] | undefined

Volumes attached to this Sailbox and the paths they are mounted at.

Returns

SailboxVolumeMount[] | undefined

Methods

checkpoint()

checkpoint(options?): Promise<SailboxCheckpoint>

Take a checkpoint of this Sailbox and prepare its clean start state. The returned handle carries expiresAt, after which starting a Sailbox from it fails. Sailboxes with volume mounts are not supported. Upgrade a Sailbox that uses an older guest payload before creating a checkpoint handle.

Parameters

Parameter	Type
options	CheckpointOptions

Returns

Promise<SailboxCheckpoint>

clearEgressPolicy()

clearEgressPolicy(): Promise<SailboxEgressPolicy>

Remove this Sailbox’s egress policy, so it can reach every host and no rules apply: the empty policy {}. The same as Sailbox.setEgressPolicy with EgressPolicy.allowAll.

Returns

Promise<SailboxEgressPolicy>

composeUp()

composeUp(options?): Promise<ExecResult>

Start the Docker Compose project this Sailbox’s image was built from.

The image, from Image.fromCompose, holds a copy of the project at /root/<its directory name> and the image Sail built for each service. composeUp runs docker compose up there. Calling it again on a running project restarts the services whose definition changed.

Resolves once every service is running, and healthy where it declares a healthcheck. A start that fails, or outlasts timeoutSeconds (unlimited by default), rejects with CommandFailedError carrying Compose’s output.

Parameters

Parameter	Type
options	ComposeUpOptions

Returns

Promise<ExecResult>

Example

const image = Image.fromCompose("./project");
const box = await Sailbox.create({ app, name: "compose", image });
await box.composeUp();

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. By default a stream you are consuming pauses the command when you fall behind, so nothing is lost until a cancel or the exec timeout ends the pauses, and a stream you are not consuming keeps only its most recent 1 MiB; start consuming right after this call returns to get every byte. outputMode and outputBufferBytes in options change that (see ExecProcess). options can also 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>

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 and stderr hold only the most recent outputBufferBytes of each stream (1 MiB by default, up to 64 MiB), with stdoutTruncated and stderrTruncated set when older output was dropped; the command never pauses for unread output. While the first call is still running, a second call with the same idempotencyKey takes over its output stream, and the earlier call’s result may come back truncated. To get every byte, use exec and consume the stream (see ExecProcess). openStdin, pty, background, and outputMode: "pipe" 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, a backgrounded one would return the launcher’s result, not the command’s, and a pipe would pause forever with nobody consuming it; use exec for those.

Parameters

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

Returns

Promise<ExecResult>

setAutoSleep()

setAutoSleep(autoSleep): Promise<void>

Replace when Sail may sleep this Sailbox on its own.

Each call replaces the whole setting: switching to { automatic: false } clears any minimum wait set earlier, and switching back does not restore it. Calling Sailbox.sleep yourself is unaffected, and so are pause, resume, and scheduled wakes.

Parameters

Parameter	Type
autoSleep	AutoSleep

Returns

Promise<void>

setEgressPolicy()

setEgressPolicy(policy): Promise<SailboxEgressPolicy>

Replace this Sailbox’s egress policy. Accepts a saved EgressPolicy (or its id or listing summary) or a document object such as EgressPolicy.allowOnly’s result. Returns the new policy.

await sb.setEgressPolicy(EgressPolicy.allowOnly("api.github.com"));
await sb.clearEgressPolicy();

The change applies to connections this Sailbox opens after the call. A document passed directly cannot reference secrets; save it as an EgressPolicy first. Fails with an ApiError (status 409) when the new document is EgressPolicy.noNetwork and the Sailbox has exposed ports or SSH.

Parameters

Parameter	Type
policy	EgressPolicyLike

Returns

Promise<SailboxEgressPolicy>

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. A dropped connection does not end the session: the shell keeps reconnecting and redraws the screen once the Sailbox is reachable again. If the Sailbox goes to sleep, the next key pressed wakes it and resumes the same session. If it is paused, the shell says so when a key is pressed and sends the keys once the Sailbox is resumed. Pressing Ctrl-D while disconnected or paused leaves the session. The session runs as the image’s USER when the image sets one, root otherwise; see ShellOptions.user. 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.

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 uses the checkpoint’s writable disk and cleaned memory state, so background processes continue and the new Sailbox runs independently of the source. Commands started with Sailbox.exec stop, though their writes up to the checkpoint remain. Host-specific identity and network routes are removed before the checkpoint handle becomes ready. A Sailbox with volume mounts cannot create a reusable checkpoint. The new Sailbox keeps the original’s egress policy and auto-sleep setting.

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 Sailbox image: a base, registry, Dockerfile, or Compose image plus ordered build steps. Immutable and fluent: each method returns a new Image. Local files/dirs are recorded here and hashed and uploaded when the image is resolved to a spec (at Sailbox.create, or via toSpec), so chaining stays synchronous.

Example

const image = Image.debian()
  .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. Creating Sailboxes from the returned spec needs no further build. For an image imported with Image.fromRegistry through a tag, the spec is also pinned to the exact version the build resolved the tag to, even if the tag later moves upstream. ImageBuildOptions.forceBuild looks the tag up again and moves the tag’s meaning for your whole organization. For an image built with Image.fromDockerfile or Image.fromCompose, the returned spec is likewise pinned to the versions the build resolved for its FROM and COPY --from images or the image of each service it pulls; ImageBuildOptions.forceBuild moves those pins for your whole organization, while specs built earlier keep their pinned versions.

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 amd64).

Parameters

Parameter	Type	Default value
architecture	ImageArchitecture	"amd64"

Returns

Image

devbox()

static devbox(architecture?): Image

The devbox base image (defaults to amd64): a prebuilt Debian base with a baked development layer. Docker is included, and its daemon starts automatically when the Sailbox boots and keeps running across sleeps. The daemon can take a few seconds to accept commands right after boot. If it stops, it is not restarted automatically. Prebuilt-only, so it does not support build steps or env; start from Image.debian to customize.

Parameters

Parameter	Type	Default value
architecture	ImageArchitecture	"amd64"

Returns

Image

fromCompose()

static fromCompose(projectDir, options?): Image

Build a Docker Compose project into a Sailbox image.

projectDir is the directory you would run docker compose in. It is read and uploaded when the image is built, so edits up to that point reach the build. The image has Docker, every service image the project needs, and a copy of the directory at /root/<its directory name>, minus what its root .dockerignore excludes. Sailbox.composeUp starts the project from that copy. The project’s own .env, name:, and COMPOSE_FILE apply, as they do locally.

Every service needs a build inside projectDir or an image to pull from a supported public registry (docker.io, ghcr.io, public.ecr.aws, or quay.io). A pulled image’s tag is pinned for your organization the first time a build uses it, like a Dockerfile FROM; forceBuild on Image.build looks the tags up again. See the images guide for the compose features Sail supports.

Parameters

Parameter	Type
projectDir	string
options	FromComposeOptions

Returns

Image

Example

const image = Image.fromCompose("./project");
const box = await Sailbox.create({ app, name: "compose", image });
await box.composeUp();

fromDockerfile()

static fromDockerfile(dockerfile, options?): Image

Build your own Dockerfile into a Sailbox image, with everything Sail needs layered on top. Pass the path to a Dockerfile on this machine, or its literal text wrapped as { contents }. The result behaves like any other image: build steps, env, and pip/apt installs work the same as on Image.debian.

Pass contextDir to give the Dockerfile’s COPY and ADD instructions a build context; if omitted, the build runs without one. A .dockerignore in that directory is honored, and ignore patterns are applied after it, so they take precedence on conflict. A file named after the Dockerfile, like Dockerfile.dockerignore, sitting next to it is used instead of the context’s .dockerignore, as it is with Docker. The files the ignore rules keep are hashed and uploaded when the image is built, so edits up to that point reach the build. File modes, empty directories, and symbolic links are carried into the build.

Every image a FROM (or COPY --from) instruction names must live on a supported public registry (docker.io, ghcr.io, public.ecr.aws, or quay.io); a short name like python:3.12 means docker.io/library/python:3.12. Each named image is pinned to the version its tag pointed at the first time your organization used it, and those pinned versions become part of the built image’s identity, so rebuilding the same spec reuses the same image even after a tag moves. Pass forceBuild to Image.build to look the tags up again and build what they point at now. The Dockerfile must produce a Debian- or Ubuntu-based filesystem.

A # syntax= line can declare docker/dockerfile:1 or a release from 1.4 through 1.22.0. A file that declares anything else is rejected. The declared release does not change how the file is built.

Multi-stage Dockerfiles work, and target names the stage to stop at, like docker build --target. A RUN --mount of type cache, secret, or ssh is rejected; tmpfs mounts work, and bind mounts work when they read from the build context or another build stage. Mount options must be literal text, and ONBUILD is not supported, in the Dockerfile or in an image a FROM names.

The built image’s environment variables, working directory, and USER become the defaults for commands you run with Sailbox.exec or Sailbox.run; per-call env, cwd, and user override them (pass user: "0:0" to run as root on an image that sets USER). The image’s ENTRYPOINT and CMD are not run: a Sailbox manages its own processes, and your commands say what to execute. Build steps you chain onto the image (such as aptInstall) and SSH sessions still run as root.

Parameters

Parameter	Type
dockerfile	string | { contents: string; }
options	FromDockerfileOptions

Returns

Image

Example

const image = Image.fromDockerfile("./envs/task1/Dockerfile", {
  contextDir: "./envs/task1",
});

fromRegistry()

static fromRegistry(ref, options?): Image

Your own image as the Sailbox root filesystem, with everything Sail needs layered on top. The result behaves like any other image: build steps, env, and pip/apt installs work the same as on Image.debian.

Reference an image on a supported public registry (docker.io, ghcr.io, public.ecr.aws, or quay.io), written as you would for docker pull: python:3.13 means docker.io/library/python:3.13 and acme/tool means docker.io/acme/tool; name the registry for the others, as in ghcr.io/acme/tool. You can pass a tag, a @sha256:... digest, or just the name, which means the latest tag. The image must be Debian- or Ubuntu-based.

Your Sailbox runs on the CPU architecture the image was built for. An image published for both amd64 and arm64 runs on amd64. Pass architecture to require one instead, and building fails if the image was not built for it.

A tag is pinned for your organization once an image has been built from it: later builds keep using that image even after the tag moves upstream. Call build({ forceBuild: true }) to look the tag up again and build the version it points at now for your whole organization; see ImageBuildOptions.forceBuild for how the switch propagates. A digest names exactly one image, so it never moves.

The image’s environment variables, working directory, and USER become the defaults for commands you run with Sailbox.exec or Sailbox.run; per-call env, cwd, and user override them (pass user: "0:0" to run as root on an image that sets USER). The image’s ENTRYPOINT and CMD are not run: a Sailbox manages its own processes, and your commands say what to execute. Build steps you chain onto the image (such as aptInstall) and SSH sessions still run as root.

Parameters

Parameter	Type
ref	string
options	FromRegistryOptions

Returns

Image

Example

const image = Image.fromRegistry(
  "docker.io/library/python:3.13"
).aptInstall("git");

---

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.

Each stream has a buffer, 1 MiB by default (outputBufferBytes), and the outputMode says what happens when it fills. With the default "auto": if you are not consuming a stream, the command never pauses and the stream keeps only its most recent bytes; if you are consuming a stream and fall behind, the command pauses when the buffer fills and resumes as you read, like a pipe. Consuming a stream is how you get every byte, and it slows the command when you cannot keep up. "pipe" holds both streams from the start, so a consumer that starts late still gets every byte; "tail" never pauses the command for you. See OutputMode.

With "auto", start consuming right after exec() returns to get every byte. You can consume stdout without holding stderr, or the reverse; the stream you are not holding keeps its most recent bytes and never pauses the command when it fills. If you hold both, consume them at the same time (Promise.all). The exit code is available from poll once the streams end and from wait.

Accessing proc.stdout or proc.stderr claims nothing. A stream is claimed when you start iterating it (for await, ExecStream.raw, ExecStream.text, ExecStream.bytes) or call ExecStream.toReadable, and released when the iteration finishes or you leave it (break, return, a thrown error), when .text() or .bytes() reaches the end, or when the Readable is destroyed. Each stream can be claimed once; a second attempt rejects with InvalidArgumentError.

wait returns each stream’s buffer, its most recent output, with stdoutTruncated / stderrTruncated set when older output was dropped. close, or your process exiting, releases both streams; the command keeps running, and wait() rejects after close() unless it already resolved a result. Sail may reattach after an interruption, but reattachment does not guarantee exact output replay. A pty command never pauses; resync requests a fresh screen.

Example

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

Accessors

execRequestId

Get Signature

get execRequestId(): string

The durable exec request id: the launch’s idempotency key as Sail recorded it (yours, or the one Sail generated when you did not supply one; read it here to learn the generated value). Reading it marks a generated identity as shareable: a second handle started with it takes over the stream, so from then on this handle no longer reclaims the stream after any interruption, a clean end or a dropped connection alike, and resolves from the recorded result instead. Reading back a key you supplied changes nothing.

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

stderr

Get Signature

get stderr(): ExecStream

The sole stderr stream: string iteration by default, .raw() for bytes. Claimed and released the same way as stdout.

Returns

ExecStream

stdout

Get Signature

get stdout(): ExecStream

The sole stdout stream: string iteration by default, .raw() for bytes. Accessing this property claims nothing; the stream is claimed when you start consuming it and released when the iteration finishes or you leave it (see ExecStream).

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

Abandon the handle without killing the command. It releases both streams. The command keeps running and never pauses, and Sail keeps only the most recent output of each stream. Call cancel instead if the command should stop. wait rejects after close() unless it already resolved a result.

Returns

void

closeStdin()

closeStdin(): Promise<void>

Close the command’s stdin (send EOF).

Returns

Promise<void>

poll()

poll(): number | null

The exit code once the output stream has ended, else null. Never blocks and never drops output. If the connection was lost for good mid-command, the stream ends early with the outcome still unknown: poll() stays null and wait fetches the result Sail recorded. A host-lost exec (the machine running the Sailbox was lost mid-command) has no real exit code: wait always throws SailboxHostLostError for one, and poll() throws it when that loss is what ended the stream.

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>

Wait for the command to finish and return its result.

stdout and stderr on the result hold each stream’s buffer, its most recent output (1 MiB by default), with stdoutTruncated / stderrTruncated set when older output was dropped; to get every byte, consume the stream (see ExecProcess). wait() itself never pauses the command and may run alongside an active consumer. With outputMode: "pipe", a stream nobody consumes pauses the command when its buffer fills, and wait() then waits for as long as the command stays paused. It rejects after close unless it already resolved a result.

Returns

Promise<ExecResult>

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. Iteration ends once the command finishes and its remaining output has been delivered; if the connection was lost for good mid-command, it ends early with the outcome still unknown, and ExecProcess.wait fetches the result Sail recorded.

An ExecStream can be consumed once: string iteration, raw, toReadable, text, or bytes; a second consumer rejects with InvalidArgumentError. Accessing proc.stdout claims nothing. The stream is claimed when you start consuming it, and from then on nothing is lost: the command pauses when you fall behind. That does not hold for pty output, for outputMode: "tail", or after cancel() or the exec timeout has ended the pauses (see ExecProcess). It is released when the iteration finishes or you leave it (break, return, a thrown error), when text or bytes reaches the end, or when the Readable from toReadable is destroyed. While nobody is consuming, Sail keeps only the stream’s most recent bytes (1 MiB by default) unless the exec runs with outputMode: "pipe", so start consuming right after exec() returns when you need every byte. Pty output never pauses the command and keeps only its most recent bytes.

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>>

Consume and collect the 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). This consumes the stream.

Returns

AsyncIterableIterator<Buffer<ArrayBufferLike>>

text()

text(): Promise<string>

Consume and collect the stream into a single string.

Returns

Promise<string>

toReadable()

toReadable(): Readable

Consume this stream as a Node Readable of string chunks. Calling this claims the stream at once; destroying the Readable releases it at once, even while a read is waiting for output.

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, test, and transfer paths.

Writes give what they create to the image’s USER by default (root when the image sets none), the same identity commands run as, so an uploaded file is usable by the code in the Sailbox. Reads and the directory helpers act as root by default, so they work on any path.

Every operation except the reads and the directory download takes an optional user in Docker’s USER syntax (name, uid, name:group, or uid:gid; "0:0" is always root). The directory helpers other than the transfers run their command as that user, with its permissions enforced. Writes and the directory upload keep running as root but give that user what they create, like COPY --chown. Reads and the download take no user: a user only decides which paths an operation may touch and who owns what it creates. A read creates nothing in the Sailbox, and a download reads any path as root, the way the reads do. A user other than "0:0" requires a Sailbox whose guest honors requested users; on older Sailboxes these calls fail until Sailbox.upgrade is called.

Methods

downloadDir()

downloadDir(dirs): Promise<void>

Download a directory’s contents from the Sailbox into a local directory.

guestDir’s entries land inside localDir, which is created if needed. Entries the download does not name are left in place; a same-named file is replaced. The transfer reads every file in the tree, so download directories of ordinary files: system trees like /proc or /sys hold files that cannot be read as plain data, and downloading them fails. A file that is being written while the download runs is captured as it is at that moment, the way copying a live file would; download after writers finish for a consistent copy. On Windows, a directory that contains symbolic links cannot be downloaded, since Windows restricts creating them. The Sailbox’s image must provide tar and gzip, which the transfer uses to ship the directory as one compressed archive; the default images do.

Parameters

Parameter	Type
dirs	{ guestDir: string; localDir: string; }
dirs.guestDir	string
dirs.localDir	string

Returns

Promise<void>

downloadUrl()

downloadUrl(path, options?): Promise<string>

Mint a URL that serves one file over HTTPS with no API key.

Anyone who holds the URL can read path, and nothing else on the Sailbox, until it expires: expiresInSeconds after minting, one hour by default and seven days at most. Share a file by URL covers caching, rewrites, and sleeping or paused Sailboxes.

Parameters

Parameter	Type
path	string
options?	DownloadUrlOptions

Returns

Promise<string>

exists()

exists(path, options?): Promise<boolean>

Whether path exists in the guest. Follows symlinks (like test -e), so a dangling symlink reports false even though ls lists it. A user reports existence as observable by that user: a path the user lacks permission to reach also reports false.

Parameters

Parameter	Type
path	string
options?	FsOptions

Returns

Promise<boolean>

ls()

ls(path, options?): 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. A user runs the listing as that user, so a directory it may not read fails with a permission error.

Parameters

Parameter	Type
path	string
options?	FsOptions

Returns

Promise<DirEntry[]>

mkdir()

mkdir(path, options?): Promise<void>

Create a directory and any missing parents (like mkdir -p); a no-op if it already exists. A user runs the mkdir as that user, so created directories are owned by it.

Parameters

Parameter	Type
path	string
options?	FsOptions

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, options?): Promise<void>

Remove a file or directory tree (like rm -rf); a no-op if it is already absent. A user runs the removal as that user, limiting it to what that user may delete.

Parameters

Parameter	Type
path	string
options?	FsOptions

Returns

Promise<void>

uploadDir()

uploadDir(dirs): Promise<void>

Upload a local directory’s contents into a directory on the Sailbox.

localDir’s entries land inside guestDir, which is created if needed. Entries the upload does not name are left in place; a same-named file is replaced. Uploaded files belong to the image’s USER, the same identity commands run as, so the code in the Sailbox can use them. When the image sets no USER, or that user cannot be resolved in the Sailbox, they belong to root. guestDir and any missing parents the upload creates get the same owner. Files keep their permission bits, except that the setuid, setgid, and sticky bits are cleared. A user (the same syntax the other operations take) gives the entries to that user instead, like COPY --chown; it must exist in the Sailbox, and like the other operations’ user it requires a Sailbox whose guest honors requested users. The Sailbox’s image must provide tar and gzip, which the transfer uses to ship the directory as one compressed archive; the default images do.

Parameters

Parameter	Type
dirs	{ guestDir: string; localDir: string; user?: string; }
dirs.guestDir	string
dirs.localDir	string
dirs.user?	string

Returns

Promise<void>

write()

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

Write data to a guest file: writeFiles with one entry. Strings use UTF-8. Missing parent directories are created unless createParents is false. Use writeStream to stream a large source.

Parameters

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

Returns

Promise<void>

writeFiles()

writeFiles(files, options?): Promise<void>

Write several complete files in one call. files maps each absolute guest path to its contents (strings use UTF-8). Each file is its own request, up to eight at a time, and every file gets the same options. A batch is not atomic across paths: the first failure stops the batch, files that already completed stay written, writes already in flight finish, and the error names the file that failed. A path may appear only once. Use writeStream to stream a large source.

Parameters

Parameter	Type
files	Readonly<Record<string, Buffer | Uint8Array | string>>
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 request 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 its write resolves.

Returns

Writable

write()

write(data): Promise<void>

Write bytes (a string is encoded as UTF-8). The SDK 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 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.

Only the owning organization can attach a volume. Code in a Sailbox can read and write an attached volume unless the mount is read-only. Use separate volumes for workloads that must not share files.

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.

Accessors

fs

Get Signature

get fs(): VolumeFs

File operations on this volume: read, write, list, and transfer its files without mounting it in a Sailbox.

Returns

VolumeFs

Methods

delete()

delete(options?): Promise<boolean>

Delete this volume. The volume becomes unavailable at once. 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 a 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 volumes in the current org.

Parameters

Parameter	Type
options	ListVolumesOptions

Returns

Promise<Volume[]>

---

VolumeFs

File operations on a volume, reached via Volume.fs.

The volume does not have to be mounted anywhere, so it can be filled before any Sailbox uses it. A Sailbox that mounts the volume sees each change within a few seconds of the call that made it resolving.

Paths are relative to the volume’s root, with or without a leading slash: skills/review.md and /skills/review.md name the same file, which a Sailbox mounting the volume at /mnt/shared sees as /mnt/shared/skills/review.md. A path may not contain a .. segment.

The operations match SailboxFs, without its user option. Files and directories created here belong to root: a command running in a Sailbox as another user can read them, and needs root to change them.

A path that does not exist throws FileNotFoundError, and a volume that does not exist throws NotFoundError.

Methods

downloadDir()

downloadDir(dirs): Promise<void>

Download a directory’s contents from the volume into a local directory.

volumeDir’s entries land inside localDir, which is created if needed ("/" downloads the whole volume). Entries the download does not name are left in place; a same-named file is replaced. A file that changes while the download runs may be captured partway through the change or fail the download, so download after writers finish. On Windows, a directory that contains symbolic links cannot be downloaded, since Windows restricts creating them. The directory travels as one compressed archive.

Parameters

Parameter	Type
dirs	{ localDir: string; volumeDir: string; }
dirs.localDir	string
dirs.volumeDir	string

Returns

Promise<void>

exists()

exists(path): Promise<boolean>

Whether path exists on the volume. 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, sorted by name (no recursion). With no path it lists the volume’s root. A missing path throws, as does a path that is not a directory. An entry whose name is not valid UTF-8 fails the listing, since a path could not address it.

Parameters

Parameter	Type	Default value
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 file on the volume 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 file on the volume.

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. The volume’s root cannot be removed.

Parameters

Parameter	Type
path	string

Returns

Promise<void>

uploadDir()

uploadDir(dirs): Promise<void>

Upload a local directory’s contents into a directory on the volume.

localDir’s entries land inside volumeDir, which is created if needed and defaults to the volume’s root. Entries the upload does not name are left in place; a same-named file is replaced atomically. Uploaded entries keep their permission bits (the setuid, setgid, and sticky bits are cleared) and modification times, and symlinks are stored as symlinks. The directory travels as one compressed archive. An upload is not atomic across files: after a failure, the files that already landed stay.

Parameters

Parameter	Type
dirs	{ localDir: string; volumeDir?: string; }
dirs.localDir	string
dirs.volumeDir?	string

Returns

Promise<void>

write()

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

Write data to a file on the volume: writeFiles with one entry. Strings use UTF-8. Missing parent directories are created unless createParents is false. An existing file is replaced atomically, so a reader sees the old contents or the new, never a mix. Use writeStream to stream a large source.

Parameters

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

Returns

Promise<void>

writeFiles()

writeFiles(files, options?): Promise<void>

Write several complete files in one call. files maps each path to its contents (strings use UTF-8). Each file is its own request, up to eight at a time, and every file gets the same options. A batch is not atomic across paths: the first failure stops the batch, files that already completed stay written, writes already in flight finish, and the error names the file that failed. A path may appear only once. For a whole tree, uploadDir is faster: it sends one archive instead of one request per file.

Parameters

Parameter	Type
files	Readonly<Record<string, Buffer | Uint8Array | string>>
options?	VolumeWriteOptions

Returns

Promise<void>

writeStream()

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

Open a streaming upload to a file on the volume. The file appears at path, replacing any existing file atomically, only when the writer’s finish succeeds; an aborted writer leaves path as it was.

Parameters

Parameter	Type
path	string
options?	VolumeWriteOptions

Returns

Promise<FileWriter>

---

Egress policies

See Egress policy for what a policy controls, the document format, and examples. The entries below list the available TypeScript calls.

EgressPolicy

A saved egress policy: a named EgressPolicyDocument your organization can attach to any number of Sailboxes.

An egress policy limits which hosts a Sailbox can connect to and can add credentials to the HTTPS requests it sends. Saving a policy gives the document a stable id that several Sailboxes can share. Only a saved policy can reference a Secret (${secrets.NAME}).

const policy = await EgressPolicy.create("github-only", {
  allowlist: ["github.com", "api.github.com"],
  rules: {
    "api.github.com": [
      {
        request: {
          set: { headers: { authorization: "Bearer ${secrets.GITHUB_TOKEN}" } },
        },
      },
    ],
  },
});
const sb = await Sailbox.create({ egressPolicy: policy });

A policy’s document cannot be edited after it is created; create a new policy and switch each Sailbox to it. EgressPolicy.allowAll, EgressPolicy.allowOnly, EgressPolicy.noEgress, and EgressPolicy.noNetwork build the common documents without saving anything. The egress policy guide covers the document format in full.

Properties

Property	Modifier	Type	Description
createdAt	readonly	Date	When the policy was created.
document	readonly	EgressPolicyDocument	The saved document: Sail’s normalized form of the document given at creation.
id	readonly	string	The policy’s stable identifier.
name	readonly	string	The policy’s name.
updatedAt	readonly	Date	When the policy’s name last changed.

Methods

delete()

delete(): Promise<void>

Delete the policy. Fails with EgressPolicyInUseError while a Sailbox that is not terminated still runs under it; switch those Sailboxes to another policy first.

Returns

Promise<void>

rename()

rename(name): Promise<EgressPolicy>

Give the policy a new name. Only the name changes; attachments and the document stay as they are. Returns the updated policy.

Parameters

Parameter	Type
name	string

Returns

Promise<EgressPolicy>

allowAll()

static allowAll(): EgressPolicyDocument

The document that lets a Sailbox reach every host: {}. A Sailbox created without a policy runs under it, and Sailbox.clearEgressPolicy puts one back to it.

Returns

EgressPolicyDocument

allowOnly()

static allowOnly(…hosts): EgressPolicyDocument

The document that lets a Sailbox reach only the given hosts: { allowlist: hosts }. Each host is a hostname such as pypi.org, a wildcard such as *.example.com, an IPv4 address, or an IPv4 range such as 203.0.113.0/24. *.example.com matches every host below it at any depth and never example.com itself. Use EgressPolicy.noEgress for no hosts at all.

const sb = await Sailbox.create({
  egressPolicy: EgressPolicy.allowOnly("pypi.org", "*.pythonhosted.org"),
});

Parameters

Parameter	Type
…hosts	string[]

Returns

EgressPolicyDocument

create()

static create(name, document, options?): Promise<EgressPolicy>

Save document under name for your organization. The document cannot change afterwards. A ${secrets.NAME} reference in it must name a Secret that already exists. name need not be unique; its limits are in the reference.

const policy = await EgressPolicy.create("registries", {
  allowlist: ["pypi.org", "files.pythonhosted.org", "registry.npmjs.org"],
});

Creating a policy is not retried on a network error, so a failed call may or may not have saved the policy; check EgressPolicy.list before calling again. The egress policy guide covers the document format.

Parameters

Parameter	Type
name	string
document	EgressPolicyDocument
options	ClientOptions

Returns

Promise<EgressPolicy>

get()

static get(policyId, options?): Promise<EgressPolicy>

Fetch a saved policy by id, including its document.

Parameters

Parameter	Type
policyId	string
options	ClientOptions

Returns

Promise<EgressPolicy>

list()

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

List your organization’s saved policies, newest first.

Each row is an EgressPolicySummary: entry and rule counts, plus how many Sailboxes other than terminated ones run under the policy. A row carries no document; fetch one with EgressPolicy.get. Sail returns the list in pages, and this method keeps fetching until it has every policy or has reached limit.

Parameters

Parameter	Type
options	ListEgressPoliciesOptions

Returns

Promise<EgressPolicySummary[]>

noEgress()

static noEgress(): EgressPolicyDocument

The document that stops every outbound connection: { allowlist: [] }. Inbound connections still work, so ingress ports and SSH do.

Returns

EgressPolicyDocument

noNetwork()

static noNetwork(): EgressPolicyDocument

The document that cuts a Sailbox off from the network entirely: { no_network: true }. No outbound connections, no name lookups, and no ingress ports or SSH. No other field may be set beside it.

Returns

EgressPolicyDocument

---

Secret

A value an egress policy rule can insert into matching HTTPS requests.

Secrets belong to your organization. Sail never returns a stored value. Get and list calls return only the secret’s name and timestamps.

Properties

Property	Modifier	Type	Description
createdAt	readonly	Date	When the secret was first set.
name	readonly	string	The secret’s name, unique within your organization.
updatedAt	readonly	Date	When the secret’s value last changed.

Methods

delete()

delete(): Promise<void>

Delete this secret.

A secret cannot be deleted while an egress policy refers to it; throws SecretInUseError until every referencing policy is deleted. Summaries from EgressPolicy.list include the secret names they use.

Returns

Promise<void>

deleteByName()

static deleteByName(name, options?): Promise<void>

Delete the named secret. Same contract as Secret.delete.

Parameters

Parameter	Type
name	string
options	ClientOptions

Returns

Promise<void>

get()

static get(name, options?): Promise<Secret>

Fetch one secret’s name and timestamps. The value is never returned. Throws NotFoundError when no secret has that name.

Parameters

Parameter	Type
name	string
options	ClientOptions

Returns

Promise<Secret>

list()

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

List your organization’s secret names and timestamps, sorted by name.

Parameters

Parameter	Type
options	ClientOptions

Returns

Promise<Secret[]>

set()

static set(name, value, options?): Promise<Secret>

Set (create or update) the named secret’s value. An egress policy inserts it with ${secrets.NAME}.

After this call succeeds, the next matching request from any Sailbox whose egress policy uses this secret gets the new value.

Names start with a letter or number and use letters, numbers, underscores, and dashes (up to 128 characters). Values cannot be empty. They can be up to 64 KiB and cannot contain ASCII control characters such as tabs or line breaks.

Parameters

Parameter	Type
name	string
value	string
options	ClientOptions

Returns

Promise<Secret>

---

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, one-method-per-operation surface (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, options?): Promise<ImageSpec>

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

By default, Sail may reuse an existing ready build for this definition. forceBuild builds it again and waits for the fresh build to become ready: new Sailboxes use the fresh image once it is ready, Sailboxes that already exist keep the filesystem they were created with, and a forced build that fails changes nothing. For an image imported with Image.fromRegistry through a tag, a forced build also asks the registry what the tag points at now and builds that version. The tag then means that version for your whole organization, while specs built earlier keep their pinned version. A forced build of an image built with Image.fromDockerfile looks up the tags its FROM and COPY --from instructions name and moves those pins for your whole organization, while specs built earlier keep the versions their build used. If forced builds overlap, the last-requested one that succeeds decides which image new Sailboxes use and, for a tag, what the tag means.

Parameters

Parameter	Type
def	ImageDefinition
timeoutSeconds	number
options	{ forceBuild?: boolean; }
options.forceBuild?	boolean

Returns

Promise<ImageSpec>

buildSpecToReady()

buildSpecToReady(spec, timeoutSeconds, options?): Promise<ImageBuild>

Build an already-resolved spec to ready (submit + poll), bounded by timeoutSeconds. forceBuild builds the image again even if a build already exists; see Client.buildImageDefinition.

Parameters

Parameter	Type
spec	ImageSpec
timeoutSeconds	number
options	{ forceBuild?: boolean; }
options.forceBuild?	boolean

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>

createEgressPolicy()

createEgressPolicy(name, document): Promise<EgressPolicyInfo>

Save an egress policy from JSON-encoded document text. The document cannot change after creation. Most callers should use EgressPolicy.create, which accepts an object.

Parameters

Parameter	Type
name	string
document	string

Returns

Promise<EgressPolicyInfo>

createFromCheckpoint()

createFromCheckpoint(params): Promise<SailboxHandle>

Create a new Sailbox from a checkpoint.

Parameters

Parameter	Type
params	FromCheckpointRequest

Returns

Promise<SailboxHandle>

createSailbox()

createSailbox(req): Promise<SailboxHandle>

Create a Sailbox. image defaults to a plain Debian base.

Parameters

Parameter	Type
req	CreateSailboxRequest

Returns

Promise<SailboxHandle>

deleteEgressPolicy()

deleteEgressPolicy(policyId): Promise<void>

Delete a saved egress policy by id. While the policy is attached to a Sailbox, the call fails with a 409 ApiError (EgressPolicy.delete maps that to EgressPolicyInUseError).

Parameters

Parameter	Type
policyId	string

Returns

Promise<void>

deleteSecret()

deleteSecret(name): Promise<void>

Delete a secret by name. While an egress policy refers to it, the call fails with a 409 ApiError (Secret.delete maps that to SecretInUseError).

Parameters

Parameter	Type
name	string

Returns

Promise<void>

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>

downloadDir()

downloadDir(sailboxId, dirs): Promise<void>

Download a guest directory’s contents into a local directory, named in dirs.

Parameters

Parameter	Type
sailboxId	string
dirs	{ guestDir: string; localDir: string; }
dirs.guestDir	string
dirs.localDir	string

Returns

Promise<void>

downloadUrl()

downloadUrl(sailboxId, path, options?): Promise<string>

Mint a signed URL that serves one file without an API key.

Parameters

Parameter	Type
sailboxId	string
path	string
options	DownloadUrlOptions

Returns

Promise<string>

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. By default a stream you are consuming pauses the command when you fall behind, so nothing is lost until a cancel or the exec timeout ends the pauses, and a stream you are not consuming keeps only its most recent 1 MiB; outputMode and outputBufferBytes change that (see ExecProcess and ExecOptions). 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>

getEgressPolicy()

getEgressPolicy(policyId): Promise<EgressPolicyInfo>

Fetch one saved egress policy by id, including its document.

Parameters

Parameter	Type
policyId	string

Returns

Promise<EgressPolicyInfo>

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>

getSecret()

getSecret(name): Promise<SecretInfo>

Fetch one secret’s name and timestamps, never its value.

Parameters

Parameter	Type
name	string

Returns

Promise<SecretInfo>

getVolume()

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

Look up a 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>>

listApps()

listApps(): Promise<AppInfo[]>

Every app the current org owns, newest first.

Returns

Promise<AppInfo[]>

listDir()

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

List a directory’s immediate entries as structured records.

Parameters

Parameter	Type
sailboxId	string
path	string
user?	string

Returns

Promise<DirEntry[]>

listEgressPolicies()

listEgressPolicies(params): Promise<EgressPolicyPage>

List saved egress policies with paging and an optional id or name search.

Parameters

Parameter	Type
params	{ limit: number; offset: number; search?: string; }
params.limit	number
params.offset	number
params.search?	string

Returns

Promise<EgressPolicyPage>

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>

listSecrets()

listSecrets(): Promise<SecretInfo[]>

List the organization’s secret names and timestamps.

Returns

Promise<SecretInfo[]>

listVolumes()

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

List volumes in the current org.

Parameters

Parameter	Type
maxObjects?	number

Returns

Promise<VolumeInfo[]>

makeDir()

makeDir(sailboxId, path, user?): 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
user?	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, user?): Promise<boolean>

Whether path exists in the guest.

Parameters

Parameter	Type
sailboxId	string
path	string
user?	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, user?): 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
user?	string

Returns

Promise<void>

renameEgressPolicy()

renameEgressPolicy(policyId, name): Promise<EgressPolicyInfo>

Rename a saved egress policy. Its document stays unchanged. Names follow the same rules as EgressPolicy.create.

Parameters

Parameter	Type
policyId	string
name	string

Returns

Promise<EgressPolicyInfo>

resolveImage()

resolveImage(def): Promise<ImageSpec>

Resolve an image definition into a content-addressed ImageSpec: the SDK 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>

sailboxEgressPolicy()

sailboxEgressPolicy(sailboxId): Promise<SailboxEgressPolicy>

The egress policy Sail enforces on a Sailbox: the document, plus the saved policy’s id and name when one is attached.

Parameters

Parameter	Type
sailboxId	string

Returns

Promise<SailboxEgressPolicy>

setSailboxAutoSleep()

setSailboxAutoSleep(sailboxId, autoSleep): Promise<void>

Replace when Sail may sleep a Sailbox on its own. Each call replaces the whole setting: switching to { automatic: false } clears any minimum wait set earlier. Most callers use Sailbox.setAutoSleep.

Parameters

Parameter	Type
sailboxId	string
autoSleep	AutoSleep

Returns

Promise<void>

setSailboxEgressPolicy()

setSailboxEgressPolicy(sailboxId, policy): Promise<SailboxEgressPolicy>

Replace a Sailbox’s egress policy with a saved policy (an EgressPolicy, a listing summary, or an id) or a document object. Returns the new policy, which applies to connections the Sailbox opens after the call. Fails with a 409 ApiError when the new document is EgressPolicy.noNetwork and the Sailbox has exposed ports or SSH.

Parameters

Parameter	Type
sailboxId	string
policy	EgressPolicyLike

Returns

Promise<SailboxEgressPolicy>

setSecret()

setSecret(name, value): Promise<SecretInfo>

Set (create or update) an organization secret. Sail never returns the stored value. After this resolves, the next matching request from a Sailbox whose egress policy uses the secret gets the new value. Names and values follow the same rules as Secret.set.

Parameters

Parameter	Type
name	string
value	string

Returns

Promise<SecretInfo>

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). The session reconnects after a dropped connection and wakes a sleeping Sailbox on the next key pressed.

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>

uploadDir()

uploadDir(sailboxId, dirs): Promise<void>

Upload a local directory’s contents into a guest directory, named in dirs. user gives the uploaded entries to that user instead of the image’s USER.

Parameters

Parameter	Type
sailboxId	string
dirs	{ guestDir: string; localDir: string; user?: string; }
dirs.guestDir	string
dirs.localDir	string
dirs.user?	string

Returns

Promise<void>

volumeDownloadDir()

volumeDownloadDir(volumeId, dirs): Promise<void>

Download a volume directory’s contents into a local directory, named in dirs.

Parameters

Parameter	Type
volumeId	string
dirs	{ localDir: string; volumeDir: string; }
dirs.localDir	string
dirs.volumeDir	string

Returns

Promise<void>

volumeListDir()

volumeListDir(volumeId, path): Promise<DirEntry[]>

List a volume directory’s immediate entries as structured records.

Parameters

Parameter	Type
volumeId	string
path	string

Returns

Promise<DirEntry[]>

volumeMakeDir()

volumeMakeDir(volumeId, path): Promise<void>

Create a directory on a volume and any missing parents; a no-op if it already exists.

Parameters

Parameter	Type
volumeId	string
path	string

Returns

Promise<void>

volumePathExists()

volumePathExists(volumeId, path): Promise<boolean>

Whether path exists on a volume.

Parameters

Parameter	Type
volumeId	string
path	string

Returns

Promise<boolean>

volumeReadStream()

volumeReadStream(volumeId, path): Promise<FileStream>

Open a streaming read of a file on a volume.

Parameters

Parameter	Type
volumeId	string
path	string

Returns

Promise<FileStream>

volumeRemovePath()

volumeRemovePath(volumeId, path): Promise<void>

Remove a file or directory tree from a volume; a no-op if it is already absent.

Parameters

Parameter	Type
volumeId	string
path	string

Returns

Promise<void>

volumeUploadDir()

volumeUploadDir(volumeId, dirs): Promise<void>

Upload a local directory’s contents into a directory on a volume, named in dirs.

Parameters

Parameter	Type
volumeId	string
dirs	{ localDir: string; volumeDir: string; }
dirs.localDir	string
dirs.volumeDir	string

Returns

Promise<void>

volumeWriteFiles()

volumeWriteFiles(volumeId, files, options?): Promise<void>

Write several complete files to a volume in one call, up to eight at a time, stopping at the first failure.

Parameters

Parameter	Type
volumeId	string
files	Readonly<Record<string, Buffer | Uint8Array | string>>
options	VolumeWriteOptions

Returns

Promise<void>

volumeWriteStream()

volumeWriteStream(volumeId, path, options?): Promise<FileWriter>

Open a streaming upload to a file on a volume.

Parameters

Parameter	Type
volumeId	string
path	string
options	VolumeWriteOptions

Returns

Promise<FileWriter>

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>

writeFiles()

writeFiles(sailboxId, files, options?): Promise<void>

Write several complete files in one call, up to eight at a time, stopping at the first failure.

Parameters

Parameter	Type
sailboxId	string
files	Readonly<Record<string, Buffer | Uint8Array | string>>
options	WriteOptions

Returns

Promise<void>

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. This is the same resolution a client performs at construction.

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.

---

AutoSleep

AutoSleep = AutomaticSleep | NeverSleep

When Sail may put a Sailbox to sleep on its own.

Sail sleeps idle Sailboxes and wakes them when needed. Waking takes a few seconds, so the first request or command after a sleep is slower than usual.

Sail sleeps a Sailbox once it has been truly idle for a minimum time, 30 seconds by default. minSecondsBeforeSleep sets your own minimum. See Autosleep. Calling sleep() yourself is unaffected, and so are pause, resume, and scheduled wakes.

The two forms are alternatives, so minSecondsBeforeSleep cannot be combined with turning automatic sleep off.

---

AutomaticSleep

Let Sail decide when to sleep a Sailbox, optionally after a minimum wait.

Properties

Property	Modifier	Type	Description
automatic?	readonly	true	Sail decides when to sleep it.
minSecondsBeforeSleep?	readonly	number	How long the Sailbox must be idle before Sail sleeps it. Whole-second values from 1 through 3600 are accepted; 0 restores Sail’s default, and other numeric values are rejected.

---

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
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
• ListEgressPoliciesOptions
• CreateSailboxOptions
• FromCheckpointOptions
• ListSailboxesOptions
• ListSailboxesPageOptions

Properties

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

---

ComposeFile

One compose file of a project.

Properties

Property	Type	Description
content?	string	The file’s text.
name?	string	Path relative to the project directory, as docker compose -f names it.

---

ComposeProject

A Docker Compose project built into an image: the manifest of the uploaded project directory and the text of its compose files.

Properties

Property	Type	Description
composeFiles?	ComposeFile[]	The compose files in merge order.
directoryName?	string	The project directory’s name; without projectName, the project name is derived from it as Compose does.
dirs?	DockerfileContextDir[]	Every directory of the project with its mode.
environment?	Record<string, string>	${VAR} values for the compose files, winning over .env.
files?	AddLocalDirFile[]	Content manifest of the project directory, minus what its root .dockerignore excludes.
pins?	DockerfileFromResolution[]	The version each external image reference resolved to when this spec was built, filled in on the spec a completed build returns, like a Dockerfile’s pinnedFrom.
projectName?	string	The project name, like docker compose -p. Defaults as Compose does.
symlinks?	DockerfileContextSymlink[]	Symbolic links in the project, with their targets as written.

---

ComposeUpOptions

Options for Sailbox.composeUp.

Properties

Property	Type	Description
env?	Readonly<Record<string, string>>	Environment variables for Compose, such as a secret kept out of the project’s .env. A variable here wins over the same one in .env, as a shell variable does locally.
timeoutSeconds?	number	Seconds allowed for the start; omit for no limit.

---

CreateSailboxOptions

Options for Sailbox.create, with an optional explicit client. image defaults to the prebuilt Debian base.

Extends

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

Properties

Property	Type	Description	Overrides	Inherited from
app	string | App	The owning app, or its id.	-	-
autoSleep?	AutoSleep	When Sail may sleep this Sailbox on its own. Omit for the default.	-	CreateSailboxRequest.autoSleep
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.	-	CreateSailboxRequest.diskLimitGib
egressPolicy?	EgressPolicyLike	What the Sailbox may connect to and what happens to the HTTPS requests it sends. Omit to allow every host. Pass a saved EgressPolicy (or its id or listing summary), or a document object such as EgressPolicy.allowOnly’s result. EgressPolicy.noNetwork cannot be combined with ingressPorts. A document passed directly cannot reference secrets; save it as an EgressPolicy first. The policy can be changed later with Sailbox.setEgressPolicy. See EgressPolicyDocument for the document format.	-	CreateSailboxRequest.egressPolicy
image?	ImageSpec | Image	Image spec, or an Image builder (built and resolved at create). Defaults to the prebuilt Debian base, which needs no image build.	-	-
imageBuildTimeoutSeconds?	number	Timeout in seconds for building a custom Image before create (1800).	CreateSailboxRequest.imageBuildTimeoutSeconds	-
ingressPorts?	readonly (number | IngressPortInput)[]	Guest ports to expose: a bare number is HTTP shorthand.	-	-
maxLifetimeSeconds?	number	Wall-clock lifetime from creation, including capacity waits, sleep and pause. Whole seconds from 1 through 4294967295; fixed at creation. Sail terminates this Sailbox after expiration. Omit for unlimited lifetime.	-	CreateSailboxRequest.maxLifetimeSeconds
memoryLimitGib?	number	Memory limit in whole GiB within the size’s range; the size’s default when omitted.	-	CreateSailboxRequest.memoryLimitGib
name	string	The Sailbox name.	-	CreateSailboxRequest.name
size?	SailboxSize	Resource size; "m" when omitted.	-	CreateSailboxRequest.size
visibility?	"org" | "private"	Who may operate the Sailbox, fixed for its life. "org" (the default) lets any credential in your org exec, copy files, SSH, or run lifecycle operations on it; "private" restricts all of that to you. An org admin can override a private Sailbox 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, checkpoint, and restore stay creator-only. "private" requires an API key minted by your user. SSH is enabled after create with Sailbox.enableSsh.	-	-
volumes?	Readonly<Record<string, string | Volume | { readOnly?: boolean; volume: string | Volume; }>>	Shared volumes to mount, mapping an absolute guest path to a Volume, volume id, or { volume, readOnly: true }. readOnly defaults to false and is fixed for the Sailbox’s life. Writes through a read-only mount fail with EROFS, even as root. See the volume guide. 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

The request Client.createSailbox accepts.

Properties

Property	Type	Description
appId	string	Identifier of the owning app.
autoSleep?	AutoSleep	When Sail may sleep this Sailbox on its own. Omit for the default.
diskLimitGib?	number	Disk limit in whole GiB within the size’s range; the size’s default when omitted.
egressPolicy?	EgressPolicyLike	What the Sailbox may connect to and what happens to the HTTPS requests it sends. Omit to allow every host. Pass a saved EgressPolicy (or its id or listing summary), or a document object such as EgressPolicy.allowOnly’s result. EgressPolicy.noNetwork cannot be combined with ingressPorts. A document passed directly cannot reference secrets; save it as an EgressPolicy first. The policy can be changed later with Sailbox.setEgressPolicy. See EgressPolicyDocument for the document format.
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.
ingressPorts?	readonly IngressPortInput[]	Guest ports to reserve for ingress.
maxLifetimeSeconds?	number	Wall-clock lifetime from creation, including capacity waits, sleep and pause. Whole seconds from 1 through 4294967295; fixed at creation. Sail terminates this Sailbox after expiration. Omit for unlimited lifetime.
memoryLimitGib?	number	Memory limit in whole GiB within the size’s range; the size’s default when omitted.
name	string	The Sailbox name.
size?	SailboxSize	Resource size; "m" when omitted.
visibility?	"org" | "private"	Who may operate the Sailbox: "org" (the default) lets any credential in your org exec, copy files, SSH, or run lifecycle operations on it; "private" restricts all of that to the creating user and requires a user-scoped API key. Fixed for the Sailbox’s life.
volumeMounts?	readonly VolumeMountInput[]	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 or Volume.fs.ls, with type narrowed to DirEntryType.

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.	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.

---

DockerfileContextDir

One directory of a Dockerfile build context.

Properties

Property	Type	Description
mode?	number	Directory mode permission bits; omitted means the default (0755).
relativePath?	string	Slash-separated path relative to the context root.

---

DockerfileContextSymlink

One symbolic link of a Dockerfile build context.

Properties

Property	Type	Description
relativePath?	string	Slash-separated path relative to the context root.
target?	string	Raw link target, exactly as the link stores it; resolved only inside the built image.

---

DockerfileFromResolution

What one external image reference in a Dockerfile resolved to when an image was built.

Properties

Property	Type	Description
digestRef?	string	The digest-pinned form of the same reference the build used.
reference?	string	The reference as the Dockerfile’s FROM or COPY --from names it.

---

DockerfileImage

Your own Dockerfile built into an image, with its resolved build context. A RUN --mount of type cache, secret, or ssh, a bind mount reading from another image, mount options that are not literal text, and ONBUILD instructions are rejected.

Properties

Property	Type	Description
buildArgs?	Record<string, string>	Values for the Dockerfile’s ARG instructions, like --build-arg. Names may not start with the reserved BUILDKIT_ prefix, and Docker’s proxy names (HTTP_PROXY, HTTPS_PROXY, FTP_PROXY, NO_PROXY, ALL_PROXY, in any letter case) are rejected; a step that needs a proxy can set one inside its RUN command.
contextDirs?	DockerfileContextDir[]	Every directory in the context with its mode, so COPY of an empty directory works and directory modes survive like they do in a docker build.
contextFiles?	AddLocalDirFile[]	Content manifest of the build context the Dockerfile’s COPY and ADD instructions read from; empty builds without a context.
contextSymlinks?	DockerfileContextSymlink[]	Symbolic links in the context, carried as links the way a docker build context carries them.
dockerfile?	string	Full Dockerfile text.
pinnedFrom?	DockerfileFromResolution[]	The version each external image reference resolved to when this spec was built, filled in on the spec a completed build returns. A spec carrying these keeps naming the image its build produced, even after a forced build moves what the references mean for your organization; a forced build looks every reference up again instead.
target?	string	The build stage to stop at, like docker build --target; unset builds the last stage.

---

DockerfileSourceInput

A Dockerfile to build into the image, with its local build context. A RUN --mount of type cache, secret, or ssh, a bind mount reading from another image, mount options that are not literal text, and ONBUILD instructions are rejected.

Properties

Property	Type	Description
buildArgs?	Record<string, string>	Values for the Dockerfile’s ARG instructions, like --build-arg. Names may not start with the reserved BUILDKIT_ prefix, and Docker’s proxy names (HTTP_PROXY, HTTPS_PROXY, FTP_PROXY, NO_PROXY, ALL_PROXY, in any letter case) are rejected; a step that needs a proxy can set one inside its RUN command.
contextDir?	string	Local directory the Dockerfile’s COPY and ADD instructions read from; if omitted, the build runs without a context.
dockerfile	string	Path to a Dockerfile on this machine, or with isContents its full contents.
ignore?	string[]	.dockerignore-style patterns to skip in the context directory, applied after the .dockerignore rules in effect so they take precedence on conflict.
isContents?	boolean	Read dockerfile as literal Dockerfile text instead of a path.
target?	string	The build stage to stop at, like docker build --target; omitted builds the last stage.

---

DownloadUrlOptions

Options for SailboxFs.downloadUrl.

Properties

Property	Type	Description
attachment?	boolean	Serve the file as a download (Content-Disposition: attachment) instead of inline.
expiresInSeconds?	number	How long the URL stays valid, in whole seconds: at least 1 and at most 604800 (seven days). Unset is one hour.
immutable?	boolean	Mark the response cacheable for a year, so a cache that holds a copy never checks back. Use it only for a path you never overwrite.

---

EgressPolicyDocument

An egress policy document: which hosts a Sailbox may connect to (allowlist and blocked), what happens to the HTTPS requests it sends (rules), or no network at all (no_network). Every field is optional; the empty document {} allows every host.

const document: EgressPolicyDocument = {
  allowlist: ["pypi.org", "files.pythonhosted.org", "api.github.com"],
  rules: {
    "api.github.com": [
      {
        request: {
          set: { headers: { authorization: "Bearer ${secrets.GITHUB_TOKEN}" } },
        },
      },
    ],
  },
};

Sail validates the document when it is used and names any field that needs to be fixed. The egress policy guide describes every field.

Properties

Property	Type	Description
allowlist?	readonly string[]	The hosts the Sailbox may reach. Absent means every host; [] means no outbound connections at all, while inbound ports keep working.
blocked?	readonly string[]	Destinations removed from what the Sailbox may otherwise reach.
missing_alpn?	object	Rarely needed. Map an exact host under rules to "http/1.1" to apply its rules to clients that do not announce an HTTP version. See missing_alpn in the reference.
no_network?	boolean	Cut the Sailbox off from the network entirely, inbound ports included. No other field may be set beside it.
rules?	object	Rules for HTTPS requests, keyed by host, each in the order Sail tests them.

---

EgressPolicyForward

Send the request to a different HTTPS host.

Properties

Property	Type	Description
host	string	Exact hostname, without a scheme, port, or wildcard.
port?	number	HTTPS port. Defaults to 443.

---

EgressPolicyInfo

A saved policy as Client.createEgressPolicy, Client.getEgressPolicy, and Client.renameEgressPolicy return it; EgressPolicy wraps the same fields with methods.

Properties

Property	Type	Description
createdAt	Date	When the policy was created.
document	EgressPolicyDocument	The saved document: Sail’s normalized form of the document given at creation.
id	string	The policy’s stable identifier.
name	string	The policy’s name (the only mutable field).
updatedAt	Date	When the policy’s name last changed.

---

EgressPolicyLike

EgressPolicyLike = EgressPolicy | EgressPolicySummary | string | EgressPolicyDocument

What Sailbox.create and Sailbox.setEgressPolicy accept as a policy: a saved EgressPolicy, a listing summary, a policy id, or a document object such as { allowlist: ["pypi.org"] }.

---

EgressPolicyMatcher

EgressPolicyMatcher = string | { equals: string; } | { prefix: string; } | { one_of: readonly string[]; }

Match one exact string, a prefix, or one string from a list. A plain string is an exact match.

---

EgressPolicyNameValueMatcher

EgressPolicyNameValueMatcher = { name?: EgressPolicyMatcher; present?: true; value?: EgressPolicyMatcher; } | { name: EgressPolicyMatcher; present: false; value?: never; }

Match a header or query parameter. The request must carry an entry whose name and value meet the conditions given, or, with present: false, carry no entry of that name.

---

EgressPolicyPage

One page returned by Client.listEgressPolicies.

Properties

Property	Type	Description
hasMore	boolean	Whether another page is available.
items	EgressPolicySummary[]	The policies on this page.
limit	number	The requested page size.
offset	number	The requested zero-based offset.
total	number	The number of matching policies across all pages.

---

EgressPolicyRequestChange

Change the request before it is sent. At least one of set, add, or remove is required, and each names at least one field.

set.headers and set.query are templates: ${secrets.NAME} inserts a secret, and a literal dollar sign is written $$. No other field may reference a secret.

Properties

Property	Type	Description
add?	object	Headers or query parameters to append.
add.headers?	EgressPolicyValueMap	-
add.query?	EgressPolicyValueMap	-
remove?	object	Header and query parameter names to delete.
remove.headers?	readonly string[]	-
remove.query?	readonly string[]	-
set?	object	Values to replace or create. path is a replacement absolute path.
set.headers?	EgressPolicyValueMap	-
set.path?	string	-
set.query?	EgressPolicyValueMap	-

---

EgressPolicyRequestMatch

The conditions a request must meet for a rule to apply. Every condition given must hold, and at least one is required.

Properties

Property	Type	Description
headers?	readonly EgressPolicyNameValueMatcher[]	Conditions on the request headers.
method?	string | readonly string[]	One or more case-sensitive HTTP methods, such as GET.
path?	EgressPolicyMatcher	The absolute request path.
query?	readonly EgressPolicyNameValueMatcher[]	Conditions on the query parameters.

---

EgressPolicyResponse

Answer the request in place of the destination. The request is not sent on.

Properties

Property	Type	Description
body?	string	Response body. Set a content-type header when needed. Not allowed with status 204 or 304.
headers?	EgressPolicyValueMap	Headers to return.
status	number	HTTP status code to return.

---

EgressPolicyRule

EgressPolicyRule = { forward?: never; match?: EgressPolicyRequestMatch; request?: never; respond: EgressPolicyResponse; } | { forward?: EgressPolicyForward; match?: EgressPolicyRequestMatch; request?: EgressPolicyRequestChange; respond?: never; }

One rule. match narrows which requests it covers; omitting it matches every request, which is only allowed on the last rule. The first matching rule decides the outcome, so order matters.

A rule either answers the request itself (respond) or sends it on: to another HTTPS host (forward), changed first (request), both, or as it is.

---

EgressPolicySummary

A policy as returned by EgressPolicy.list, with usage counts but without the document. Fetch the full policy with EgressPolicy.get.

Properties

Property	Type	Description
allowlistCount	number | null	Number of allowlist entries; null when the document has no allowlist.
attachmentCount	number	How many Sailboxes that are not terminated run under the policy.
blockedCount	number	How many entries blocked holds.
createdAt	Date	When the policy was created.
hostCount	number	How many hosts have rules.
id	string	The policy’s stable identifier.
name	string	The policy’s name.
noNetwork	boolean	Whether the document sets no_network.
referencedSecretNames	string[]	The secret names the document refers to.
ruleCount	number	How many rules the document carries across every host.
updatedAt	Date	When the policy’s name last changed.

---

EgressPolicyValueMap

Header or query parameter names, each with one or more values.

Indexable

[name: string]: string | readonly string[]

---

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

Extends

• Omit<native.ExecStartOptions, "env" | "outputMode" | "pty" | "term" | "cols" | "rows">

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
cwd?	string	Working directory to run the command in (shell commands only). Unset starts the command in the image’s working directory, or / when the image does not set one.	Omit.cwd
env?	Readonly<Record<string, string>>	Extra environment for the command. Entries override the guest’s defaults (including LANG and the IS_SANDBOX=1 sandbox marker) 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. An exec has one live handle at a time: a second handle started with the same key takes over the stream, and the first stops receiving live output and resolves from a bounded recorded result. A first handle reconnecting after a dropped connection can race a handle that attached meanwhile, and either handle’s result may come back incomplete; avoid overlapping same-key handles. The UTF-8 value can be up to 256 KiB.	Omit.idempotencyKey
openStdin?	boolean	Leave stdin open for writeStdin.	Omit.openStdin
outputBufferBytes?	number	Size of each stream’s output buffer in bytes, 1 MiB by default. Must be between 64 KiB and 64 MiB.	Omit.outputBufferBytes
outputMode?	OutputMode	What happens when a stream’s output buffer fills; see OutputMode. "auto" by default.	-
pty?	boolean | PtyConfig	Run the command under a pseudo-terminal: true for the default terminal, or a PtyConfig to set term and the initial window. isatty() is true, control bytes on stdin become signals, stdout and stderr merge onto one stream, and resize adjusts the window. Implies openStdin.	-
timeoutSeconds?	number	Wall-clock limit in seconds before the server kills the command.	Omit.timeoutSeconds
user?	string	Run the command as this guest user: a user name or numeric uid, optionally with a group appended after a colon ("alice", "1000", "alice:staff", the Docker USER syntax). A named user must exist in the Sailbox’s /etc/passwd; a numeric uid need not. HOME (and USER/LOGNAME when a name resolves) default to the resolved account, with env entries still winning. When unset, commands run as the image’s USER if the image sets one, root otherwise; pass "0:0" to force root ("root" is a user name like any other, resolved through the Sailbox’s /etc/passwd). Sailboxes created before user support shipped must call upgrade() once first; until then such execs fail rather than run as root. The exact spelling "0:0" needs no upgrade.	Omit.user

---

ExecResult

The result of a finished exec.

stdout and stderr hold only each stream’s buffer, its most recent output (outputBufferBytes, 1 MiB by default). To get every byte, consume the live stream right after exec() returns; see ExecProcess for how consuming a stream affects the command.

Properties

Property	Type	Description
exitCode	number	The command’s exit code.
stderr	string	The most recent standard error, up to the exec’s buffer size (1 MiB by default; see stderrTruncated).
stderrTruncated	boolean	The command wrote more stderr than stderr holds, so older bytes are missing.
stdout	string	The most recent standard output, up to the exec’s buffer size (1 MiB by default; see stdoutTruncated).
stdoutTruncated	boolean	The command wrote more stdout than stdout holds, so older bytes are missing.
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.	-

---

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
maxLifetimeSeconds?	number	Wall-clock lifetime from creation, including capacity waits, sleep and pause. Whole seconds from 1 through 4294967295; fixed at creation. Sail terminates this Sailbox after expiration. Omit for unlimited lifetime.	FromCheckpointRequest.maxLifetimeSeconds
name	string	Name for the new Sailbox.	FromCheckpointRequest.name

---

FromCheckpointRequest

The create-from-checkpoint request.

Extended by

• FromCheckpointOptions

Properties

Property	Type	Description
checkpointId	string	The checkpoint to restore from.
maxLifetimeSeconds?	number	Wall-clock lifetime from creation, including capacity waits, sleep and pause. Whole seconds from 1 through 4294967295; fixed at creation. Sail terminates this Sailbox after expiration. Omit for unlimited lifetime.
name	string	Name for the new Sailbox.

---

FromComposeOptions

Options for Image.fromCompose.

Properties

Property	Type	Description
architecture?	ImageArchitecture	Target CPU architecture the image is built for (default amd64).

---

FromDockerfileOptions

Options for Image.fromDockerfile.

Properties

Property	Type	Description
architecture?	ImageArchitecture	Target CPU architecture the image is built for (default amd64).
buildArgs?	Readonly<Record<string, string>>	Values for the Dockerfile’s ARG instructions, like --build-arg. Names may not start with the reserved BUILDKIT_ prefix, and Docker’s proxy names (HTTP_PROXY, HTTPS_PROXY, FTP_PROXY, NO_PROXY, ALL_PROXY, in any letter case) are rejected; a step that needs a proxy can set one inside its RUN command.
contextDir?	string	Local directory the Dockerfile’s COPY and ADD instructions read from; if omitted, the build runs without a context.
ignore?	readonly string[]	.dockerignore-style patterns to skip in the context directory, applied after the .dockerignore rules in effect so they take precedence on conflict.
target?	string	The build stage to stop at, like docker build --target.

---

FromRegistryOptions

Options for Image.fromRegistry.

Properties

Property	Type	Description
architecture?	ImageArchitecture	Require the image to have been built for this CPU architecture. Leave it unset to use the architecture the image was built for.

---

FsOptions

Options for the directory helpers (SailboxFs.mkdir, SailboxFs.remove, SailboxFs.exists, SailboxFs.ls).

Properties

Property	Type	Description
user?	string	Run the operation as this user (Docker’s USER syntax: `name	uid[:group	gid]), with its permissions enforced by the guest kernel. Unset runs as root, so the helpers work on any path; ”0:0”is always root. Auserother than”0:0”` requires a Sailbox whose guest honors requested users; on older Sailboxes the operation fails until Sailbox.upgrade is called.

---

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
composePins?	DockerfileFromResolution[]	What each external image reference resolved to when the spec has a Compose project step; absent otherwise. Carrying these in the project’s pins keeps creating from the image this build produced, as dockerfilePins does for a Dockerfile.	Omit.composePins
dockerfilePins?	DockerfileFromResolution[]	What each external image reference resolved to when the spec’s source is a Dockerfile; absent otherwise. Carrying these in the spec’s pinnedFrom keeps creating from the image this build produced, even after a forced build moves what the references mean for your organization.	Omit.dockerfilePins
errorMessage?	string	Human-readable failure detail; present when status is failed.	Omit.errorMessage
imageId	string	The content-addressed image id.	Omit.imageId
resolvedOciRef?	string	The digest-pinned form of the spec’s registry reference when the spec’s source is an OCI image; absent otherwise. Creating from this reference instead of the submitted tag keeps naming the same registry content even if the tag has moved since.	Omit.resolvedOciRef
status	ImageBuildStatus	-	-

---

ImageBuildOptions

Options for Image.build.

Properties

Property	Type	Description
client?	Client	Use a specific client instead of the default (env) one.
forceBuild?	boolean	Build the image again even if a build already exists, and wait for the fresh build to become ready. New Sailboxes use the fresh image once it is ready, Sailboxes that already exist keep the filesystem they were created with, and a forced build that fails changes nothing. For an image imported with Image.fromRegistry through a tag, a forced build also asks the registry what the tag points at now and builds that version. The tag then means that version for your whole organization, while specs built earlier keep their pinned version. A forced build of an image built with Image.fromDockerfile or Image.fromCompose also looks up the tags in its FROM and COPY --from instructions, or in its services’ image entries, and moves those pins for your whole organization, while specs built earlier keep the versions their build used. If forced builds overlap, the last-requested one that succeeds decides which image new Sailboxes use and, for a tag, what the tag means.
timeoutSeconds?	number	Timeout in seconds bounding the whole pipeline, including hashing, uploads, the build, and any automatic retries (default 1800).

---

ImageBuildStatus

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

The status of a custom image build.

---

ImageBuildStep

ImageBuildStep = { addLocalDir?: never; addLocalFile?: never; aptInstall: PackageInstall; composeProject?: never; pipInstall?: never; runCommand?: never; } | { addLocalDir?: never; addLocalFile?: never; aptInstall?: never; composeProject?: never; pipInstall: PackageInstall; runCommand?: never; } | { addLocalDir?: never; addLocalFile?: never; aptInstall?: never; composeProject?: never; pipInstall?: never; runCommand: RunCommand; } | { addLocalDir?: never; addLocalFile: AddLocalFile; aptInstall?: never; composeProject?: never; pipInstall?: never; runCommand?: never; } | { addLocalDir: AddLocalDir; addLocalFile?: never; aptInstall?: never; composeProject?: never; pipInstall?: never; runCommand?: never; } | { addLocalDir?: never; addLocalFile?: never; aptInstall?: never; composeProject: ComposeProject; 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, registry, Dockerfile, or Compose 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 means amd64 with base, dockerfile, and compose, and with ociRef means whichever architecture the registry image was built for (amd64 when it was built for both). Setting it with ociRef requires the image to provide that architecture.
base?	string	Base image to build on: debian or devbox. The devbox base is a prebuilt development environment that includes Docker, with the daemon started automatically when the Sailbox boots and kept running across sleeps. The daemon can take a few seconds to accept commands right after boot. If it stops, it is not restarted automatically. Mutually exclusive with ociRef and dockerfile; with compose it may only be debian.
compose?	string	The directory of a Docker Compose project to build into the image: the one you would run docker compose in. The image has Docker, every service image the project needs, and a copy of the directory, minus what its root .dockerignore excludes, which composeUp starts the project from. The project’s own .env, name:, and COMPOSE_FILE apply, as they do locally. An image a service pulls, and every FROM in a service Dockerfile, follows the rules of dockerfile and is pinned the same way. A service with a build is built, and its image names the result. Mutually exclusive with ociRef and dockerfile.
dockerfile?	DockerfileSourceInput	Your own Dockerfile built into the image; mutually exclusive with base, ociRef, and compose. Every image its FROM (and COPY --from) instructions name must live on a supported public registry (docker.io, ghcr.io, public.ecr.aws, or quay.io; a short name like python:3.12 means docker.io/library/python:3.12). Each named image is pinned to the version its tag pointed at the first time your organization used it, and those pinned versions become part of the built image’s identity, so rebuilding the same spec reuses the same image even after a tag moves. A forced build looks the tags up again and builds what they point at now. The built image’s ENV, WORKDIR, and USER become the Sailbox defaults for commands you run; its ENTRYPOINT and CMD are not run, because a Sailbox manages its own processes.
env?	Record<string, string>	Environment variables baked into the image.
ociRef?	string	Your own image as the root filesystem: a reference to a Debian- or Ubuntu-based image whose first segment names a supported public registry (docker.io, ghcr.io, public.ecr.aws, or quay.io), with an optional :tag or @sha256:<64 hex> pin (no tag means the latest tag). A tag is pinned for your organization once an image has been built from it: later builds keep getting that version, even if the tag moves upstream. A forced build looks the tag up again and moves the pin for your whole organization. If forced builds of the same tag overlap, the last-requested one that succeeds decides what the tag means, no matter which build finishes first. A digest names exactly one image, so it never moves. The image’s ENV, WORKDIR, and USER become the Sailbox defaults for commands you run; its ENTRYPOINT and CMD are not run, because a Sailbox manages its own processes. Mutually exclusive with base, dockerfile, and compose.
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, registry, Dockerfile, or Compose 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 means amd64 with base and dockerfile, and with ociRef means whichever architecture the registry image was built for (amd64 when it was built for both). Setting it with ociRef requires the image to provide that architecture.	-
base?	BaseImage	Base image to build on. The devbox base is a prebuilt development environment that includes Docker, with the daemon started automatically when the Sailbox boots and kept running across sleeps. The daemon can take a few seconds to accept commands right after boot. If it stops, it is not restarted automatically. Mutually exclusive with ociRef and dockerfile.	-
buildSteps?	ImageBuildStep[]	Ordered build steps applied on top of the image source.	-
dockerfile?	DockerfileImage	Your own Dockerfile built into the image; mutually exclusive with base and ociRef. Every image its FROM (and COPY --from) instructions name must live on a supported public registry (docker.io, ghcr.io, public.ecr.aws, or quay.io; a short name like python:3.12 means docker.io/library/python:3.12). Each named image is pinned to the version its tag pointed at the first time your organization used it, and those pinned versions become part of the built image’s identity, so rebuilding the same spec reuses the same image even after a tag moves. A forced build looks the tags up again and builds what they point at now. The built image’s ENV, WORKDIR, and USER become the Sailbox defaults for commands you run; its ENTRYPOINT and CMD are not run, because a Sailbox manages its own processes.	Omit.dockerfile
env?	Record<string, string>	Environment variables baked into the image.	Omit.env
ociRef?	string	Your own image as the root filesystem: a reference to a Debian- or Ubuntu-based image whose first segment names a supported public registry (docker.io, ghcr.io, public.ecr.aws, or quay.io), with an optional :tag or @sha256:<64 hex> pin (no tag means the latest tag). A tag is pinned for your organization once an image has been built from it: later builds keep getting that version, even if the tag moves upstream. A forced build looks the tag up again and moves the pin for your whole organization. If forced builds of the same tag overlap, the last-requested one that succeeds decides what the tag means, no matter which build finishes first. A digest names exactly one image, so it never moves. The image’s ENV, WORKDIR, and USER become the Sailbox defaults for commands you run; its ENTRYPOINT and CMD are not run, because a Sailbox manages its own processes. Mutually exclusive with base and dockerfile.	Omit.ociRef

---

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.

---

ListEgressPoliciesOptions

Options for EgressPolicy.list.

Extends

• ClientOptions

Properties

Property	Type	Description	Inherited from
client?	Client	Use a specific client instead of the default (env) one.	ClientOptions.client
limit?	number	Stop after this many policies. Omit to list every policy.	-
search?	string	Return only policies whose id or name contains this text (case-insensitive).	-

---

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.	ListSailboxesPageOptions.order
search?	string	Substring filter on the Sailbox name.	Omit.search
status?	SailboxStatusFilter	Filter by lifecycle status.	ListSailboxesPageOptions.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.	ListSailboxesQuery.appId
client?	Client	Use a specific client instead of the default (env) one.	ClientOptions.client
limit?	number	Page size.	ListSailboxesQuery.limit
offset?	number	Page offset.	ListSailboxesQuery.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.	ListSailboxesQuery.search
status?	SailboxStatusFilter	Filter by lifecycle status.	ListSailboxesQuery.status

---

ListSailboxesQuery

Filters for listing Sailboxes.

Extends

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

Extended by

• ListSailboxesPageOptions

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.

---

NeverSleep

Stop Sail sleeping a Sailbox on its own. minSecondsBeforeSleep belongs to AutomaticSleep, so it cannot be combined with this.

Properties

Property	Modifier	Type	Description
automatic	readonly	false	Stop Sail sleeping this Sailbox on its own.
minSecondsBeforeSleep?	readonly	undefined	-

---

OutputMode

OutputMode = "auto" | "pipe" | "tail"

What happens when a stream’s output buffer fills. Each stream has its own buffer, 1 MiB by default (outputBufferBytes in ExecOptions). Sending cancel(), and the exec timeout, end every pause: from then on each stream keeps only its most recent bytes, so a consumer more than a buffer behind skips. A command that ignores the cancel signal keeps running that way; cancel({ force: true }) stops it. The command keeps its original timeout. If this handle attaches to a command launched earlier under the same idempotencyKey, this handle’s pause deadline starts when the attachment succeeds, so it can release the pauses one full timeout after that; cancel() and close() release them at once.

• "auto", the default: a stream you are consuming pauses the command when its buffer fills and resumes as you read, like a pipe; a stream you are not consuming never pauses the command and keeps only its most recent bytes.
• "pipe": both streams pause the command when their buffer fills, until you consume them, so nothing is lost while you are late to start. Consume both streams, or the command stays paused on the one you ignore. Once a stream is released, it goes back to keeping only its most recent bytes. Not available with pty.
• "tail": the command never pauses for you. Each stream keeps only its most recent bytes, even while you are consuming it, so a slow consumer skips output without notice; stdoutTruncated and stderrTruncated say only that the result holds less than the command wrote. A pty command always behaves this way.

---

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).

---

PtyConfig

The pseudo-terminal a pty exec runs under. Every field has a default, so {} (or pty: true) is a usable terminal.

Properties

Property	Type	Description
cols?	number	Initial width in columns (default 80).
rows?	number	Initial height in rows (default 24).
term?	string	$TERM for the pty (default xterm-256color).

---

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
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" | "user" | "idempotencyKey" | "outputBufferBytes">

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). Unset starts the command in the image’s working directory, or / when the image does not set one.	Pick.cwd
env?	Readonly<Record<string, string>>	Extra environment for the command. Entries override the guest’s defaults (including LANG and the IS_SANDBOX=1 sandbox marker) 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. An exec has one live handle at a time: a second handle started with the same key takes over the stream, and the first stops receiving live output and resolves from a bounded recorded result. A first handle reconnecting after a dropped connection can race a handle that attached meanwhile, and either handle’s result may come back incomplete; avoid overlapping same-key handles. The UTF-8 value can be up to 256 KiB.	Pick.idempotencyKey
outputBufferBytes?	number	Size of each stream’s output buffer in bytes, 1 MiB by default. Must be between 64 KiB and 64 MiB.	Pick.outputBufferBytes
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
user?	string	Run the command as this guest user: a user name or numeric uid, optionally with a group appended after a colon ("alice", "1000", "alice:staff", the Docker USER syntax). A named user must exist in the Sailbox’s /etc/passwd; a numeric uid need not. HOME (and USER/LOGNAME when a name resolves) default to the resolved account, with env entries still winning. When unset, commands run as the image’s USER if the image sets one, root otherwise; pass "0:0" to force root ("root" is a user name like any other, resolved through the Sailbox’s /etc/passwd). Sailboxes created before user support shipped must call upgrade() once first; until then such execs fail rather than run as root. The exact spelling "0:0" needs no upgrade.	Pick.user

---

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.

---

SailboxEgressPolicy

A Sailbox’s egress policy as Sail enforces it, read from Sailbox.egressPolicy.

document is always present: a Sailbox created without a policy has the empty document {}, so every host is reachable and no rules apply. policyId and name identify the saved EgressPolicy when one is attached and are absent when the Sailbox was given a document directly.

The object is frozen.

Properties

Property	Modifier	Type	Description
document	readonly	EgressPolicyDocument	The enforced document.
name?	readonly	string	The saved policy’s name.
policyId?	readonly	string	The saved policy’s id.

---

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" | "autoSleep" | "egressPolicy">

Properties

Property	Modifier	Type	Description	Inherited from
appId	public	string	Identifier of the owning app.	Omit.appId
appName	public	string	Name of the owning app.	Omit.appName
architecture	public	string	CPU architecture (for example arm64).	Omit.architecture
autoSleep?	public	AutoSleep	When Sail may sleep this Sailbox on its own.	-
checkpointGeneration	public	number	Monotonic checkpoint generation counter.	Omit.checkpointGeneration
cpuRequestedVcpu	public	number	Requested CPU, in vCPUs.	Omit.cpuRequestedVcpu
cpuUsedVcpu	public	number	Current CPU usage, in vCPUs.	Omit.cpuUsedVcpu
createdAt	public	string	When the Sailbox was created (RFC 3339).	Omit.createdAt
createdByUserId?	public	string	The user whose credential created this Sailbox (for a restore, the user who ran it). Absent for service-key creates.	Omit.createdByUserId
deprecation?	public	SailboxDeprecation	Actionable runtime deprecation notice, when an upgrade is needed.	Omit.deprecation
diskRequestedBytes	public	number	Requested disk, in bytes.	Omit.diskRequestedBytes
diskUsedBytes	public	number	Current disk usage, in bytes.	Omit.diskUsedBytes
egressPolicy?	readonly	SailboxEgressPolicy	The Sailbox’s egress policy. A Sailbox created without a policy reports the empty document {}.	-
errorMessage?	public	string	Human-readable error detail when the Sailbox is in an error state.	Omit.errorMessage
expiresAt?	public	string	Termination deadline (RFC 3339). Sail checks expiration periodically. Null means unlimited lifetime.	Omit.expiresAt
guestSchemaVersion?	public	number	The Sailbox runtime schema version the Sailbox last booted with.	Omit.guestSchemaVersion
imageId	public	string	Identifier of the image the Sailbox was created from.	Omit.imageId
lastCheckpointedAt?	public	string	When the most recent checkpoint was taken, if any (RFC 3339).	Omit.lastCheckpointedAt
memoryMib	public	number	Configured memory, in MiB.	Omit.memoryMib
memoryRequestedBytes	public	number	Requested memory, in bytes.	Omit.memoryRequestedBytes
memoryUsedBytes	public	number	Current memory usage, in bytes.	Omit.memoryUsedBytes
name	public	string	The Sailbox name.	Omit.name
sailboxId	public	string	The Sailbox id.	Omit.sailboxId
startedAt?	public	string	When the Sailbox first started running, if it ever has (RFC 3339). A resume does not rewrite it.	Omit.startedAt
stateDiskSizeGib	public	number	Configured state-disk size, in GiB.	Omit.stateDiskSizeGib
status	public	SailboxStatus	-	-
updatedAt	public	string	When the Sailbox was last updated (RFC 3339).	Omit.updatedAt
vcpuCount	public	number	Configured number of vCPUs.	Omit.vcpuCount
visibility?	public	string	"private" when access is restricted to the creator; absent/"org" is the default org-wide access.	Omit.visibility
volumeMounts	public	SailboxVolumeMount[]	Volumes attached to this Sailbox and the paths they are mounted at. Empty when the Sailbox has none.	Omit.volumeMounts

---

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.

---

SecretInfo

A secret’s name and timestamps. Sail never returns the stored value, so no value field exists. Timestamps are RFC 3339 strings.

Properties

Property	Type	Description
createdAt	string	When the secret was first set (RFC 3339).
name	string	The secret’s name, unique within your organization.
updatedAt	string	When the secret’s value last changed (RFC 3339).

---

ShellOptions

Options for Sailbox.shell.

Properties

Property	Type	Description
cwd?	string	Working directory for the session. Unset starts it in the image’s working directory, or / when the image does not set one.
env?	Readonly<Record<string, string>>	Extra environment for the session, with the precedence and reserved names of ExecOptions.env.
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.
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.
user?	string	Run the session as this user (Docker’s USER syntax: `name	uid[:group	gid]). Unset runs as the image's USERwhen the image sets one, root otherwise: the same identity [Sailbox.exec](#exec-1) uses.”0:0”is always root. Auserother than”0:0”` requires a Sailbox whose guest honors requested users; on older Sailboxes the session fails until Sailbox.upgrade is called.

---

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 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

A volume to mount at create time.

Properties

Property	Type	Description
mountPath	string	Absolute guest path to mount at.
readOnly?	boolean	Mount the volume read-only for the Sailbox’s life. Writes through this mount fail with EROFS, even as root. Defaults to false. See the volume guide.
volumeId	string	The volume id (from getVolume/listVolumes).

---

VolumeWriteOptions

Options for writing a file to a volume (VolumeFs.write, VolumeFs.writeFiles, VolumeFs.writeStream).

Properties

Property	Type	Description
createParents?	boolean	Create missing parent directories (default true).
mode?	number	Unix mode bits for the written file (default 0o644).

---

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 (default 0o644).
user?	string	Owner for the written file and any parent directories the write creates, in Docker’s USER syntax: `name	uid[:group	gid]. The write itself always runs as root, like COPY —chown, so it succeeds even where that owner could not write. Unset follows the image's USERwhen the image sets one, root otherwise: the same identity commands run as, so an uploaded file is usable by the code in the Sailbox. Pass”0:0”to force root ownership. Requires a Sailbox whose guest honors requested users; on older Sailboxes the write fails until [Sailbox.upgrade](#upgrade) is called, except with the exact spelling”0:0”`, which needs none.

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 exec 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

Extended by

• SecretInUseError
• EgressPolicyInUseError

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 exec 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 exec 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 exec 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	Transport 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

---

EgressPolicyInUseError

Deleting an egress policy that a Sailbox still runs under; terminated Sailboxes do not count. Switch those Sailboxes to another policy first.

Extends

• ApiError

Constructors

Constructor

new EgressPolicyInUseError(message, details?): EgressPolicyInUseError

Parameters

Parameter	Type
message	string
details	SailErrorDetails

Returns

EgressPolicyInUseError

Inherited from

ApiError.constructor

Properties

Property	Modifier	Type	Description	Inherited from
body?	readonly	unknown	Parsed response body from the failed request, when available.	ApiError.body
code	readonly	string	Stable, language-neutral error code (e.g. "NotFound").	ApiError.code
retryable	readonly	boolean	Advisory: true when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient exec 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.retryable
status?	readonly	number	HTTP status code returned by the API, when the failure carries one.	ApiError.status

---

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 exec 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 exec 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 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 exec 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 exec 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 exec 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 exec 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 exec 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 exec 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	Transport 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 exec 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	Transport 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 exec 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	Transport 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 exec 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	Transport 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

---

SecretInUseError

Deleting a secret that egress policies still refer to. Delete those policies first, then delete the secret.

Extends

• ApiError

Constructors

Constructor

new SecretInUseError(message, details?): SecretInUseError

Parameters

Parameter	Type
message	string
details	SailErrorDetails

Returns

SecretInUseError

Inherited from

ApiError.constructor

Properties

Property	Modifier	Type	Description	Inherited from
body?	readonly	unknown	Parsed response body from the failed request, when available.	ApiError.body
code	readonly	string	Stable, language-neutral error code (e.g. "NotFound").	ApiError.code
retryable	readonly	boolean	Advisory: true when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient exec 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.retryable
status?	readonly	number	HTTP status code returned by the API, when the failure carries one.	ApiError.status

---

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 exec 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 exec 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