TypeScript SDK

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

errorMessage

Get Signature

get errorMessage(): string | undefined

Failure detail when the status is failed.

Returns

string | undefined

fs

Get Signature

get fs(): SailboxFs

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

Returns

SailboxFs

guestSchemaVersion

Get Signature

get guestSchemaVersion(): number | undefined

The Sailbox runtime schema version the Sailbox last booted with.

Returns

number | undefined

imageId

Get Signature

get imageId(): string | undefined

Identifier of the image the Sailbox was created from.

Returns

string | undefined

lastCheckpointedAt

Get Signature

get lastCheckpointedAt(): Date | undefined

When the most recent checkpoint was taken.

Returns

Date | undefined

memoryMib

Get Signature

get memoryMib(): number | undefined

Configured memory, in MiB.

Returns

number | undefined

memoryRequestedBytes

Get Signature

get memoryRequestedBytes(): number | undefined

Requested memory, in bytes.

Returns

number | undefined

memoryUsedBytes

Get Signature

get memoryUsedBytes(): number | undefined

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

Returns

number | undefined

name

Get Signature

get name(): string

The Sailbox name.

Returns

string

sailboxId

Get Signature

get sailboxId(): string

The Sailbox’s stable identifier.

Returns

string

startedAt

Get Signature

get startedAt(): Date | undefined

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

Returns

Date | undefined

stateDiskSizeGib

Get Signature

get stateDiskSizeGib(): number | undefined

Configured state-disk size, in GiB.

Returns

number | undefined

status

Get Signature

get status(): SailboxStatus

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

Returns

SailboxStatus

updatedAt

Get Signature

get updatedAt(): Date | undefined

When the Sailbox last changed.

Returns

Date | undefined

vcpuCount

Get Signature

get vcpuCount(): number | undefined

Configured number of vCPUs.

Returns

number | undefined

visibility

Get Signature

get visibility(): string | undefined

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

Returns

string | undefined

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. The returned handle carries expiresAt, after which starting a Sailbox from it fails.

Parameters

Parameter	Type
`options`	`CheckpointOptions`

Returns

Promise<SailboxCheckpoint>

enableSsh()

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

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

Parameters

Parameter	Type
`options`	`EnableSshOptions`

Returns

Promise<SshEndpoint | null>

exec()

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

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

Parameters

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

Returns

Promise<ExecProcess>

expose()

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

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

Parameters

Parameter	Type
`guestPort`	`number`
`options`	`ExposeOptions`

Returns

Promise<Listener>

ingressAuthHeaders()

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

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

Returns

Promise<Record<string, string>>

listener()

listener(guestPort): Promise<Listener>

Fetch one listener by guest port without waking the Sailbox.

Parameters

Parameter	Type
`guestPort`	`number`

Returns

Promise<Listener>

listeners()

listeners(): Promise<Listener[]>

List this Sailbox’s listeners without waking it.

Returns

Promise<Listener[]>

pause()

pause(): Promise<void>

Pause this Sailbox in memory.

Returns

Promise<void>

resume()

resume(): Promise<void>

Resume this Sailbox (updates status).

Returns

Promise<void>

run()

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

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

Parameters

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

Returns

Promise<ExecResult>

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>

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

Parameters

Parameter	Type
`options`	`FromCheckpointOptions`

Returns

Promise<Sailbox>

fromId()

static fromId(sailboxId, options?): Sailbox

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

Parameters

Parameter	Type
`sailboxId`	`string`
`options`	`ClientOptions`

Returns

Sailbox

get()

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

Fetch an existing Sailbox by id.

Parameters

Parameter	Type
`sailboxId`	`string`
`options`	`ClientOptions`

Returns

Promise<Sailbox>

list()

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

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

Parameters

Parameter	Type
`params`	`ListSailboxesOptions`

Returns

Promise<Sailbox[]>

listPage()

static listPage(params?): Promise<SailboxPage>

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

Parameters

Parameter	Type
`params`	`ListSailboxesPageOptions`

Returns

Promise<SailboxPage>

App

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

Properties

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

Methods

find()

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

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

Parameters

Parameter	Type
`name`	`string`
`options`	`FindAppOptions`

Returns

Promise<App>

list()

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

Every app the current org owns, newest first.

Parameters

Parameter	Type
`options`	`ClientOptions`

Returns

Promise<App[]>

Image

A Sailbox image: a base, registry, or Dockerfile 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

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

aptInstall()

aptInstall(…packages): Image

Install system packages with apt.

Parameters

Parameter	Type
…`packages`	`string`[]

Returns

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, the returned spec is likewise pinned to the versions the build resolved for its FROM and COPY --from images; 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

pipInstall()

pipInstall(…packages): Image

Install Python packages with pip.

Parameters

Parameter	Type
…`packages`	`string`[]

Returns

runCommand()

runCommand(command): Image

Run a shell command during the build.

Parameters

Parameter	Type
`command`	`string`

Returns

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

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

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

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), fully qualified, e.g. docker.io/library/python:3.13. 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

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.

Example

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

Properties

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

Accessors

execRequestId

Get Signature

get execRequestId(): string

The durable exec request id.

Returns

string

idempotencyKey

Get Signature

get idempotencyKey(): string

The idempotency key used to launch the command.

Returns

string

output

Get Signature

get output(): ExecStream

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

Returns

ExecStream

Methods

[asyncDispose]()

[asyncDispose](): Promise<void>

await using support: detaches on scope exit.

Returns

Promise<void>

[dispose]()

[dispose](): void

using support: detaches on scope exit.

Returns

void

cancel()

cancel(options?): Promise<void>

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

Parameters

Parameter	Type
`options`	`CancelOptions`

Returns

Promise<void>

close()

close(): void

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

Returns

void

closeStdin()

closeStdin(): Promise<void>

Close the command’s stdin (send EOF).

Returns

Promise<void>

poll()

poll(): number | null

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

Returns

number | null

resize()

resize(cols, rows): Promise<void>

Resize the pty (no-op without one).

Parameters

Parameter	Type
`cols`	`number`
`rows`	`number`

Returns

Promise<void>

resync()

resync(): Promise<void>

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

Returns

Promise<void>

wait()

wait(): Promise<ExecResult>

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

Returns

Promise<ExecResult>

waitStreamEnded()

waitStreamEnded(timeoutSeconds): Promise<boolean>

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

Parameters

Parameter	Type
`timeoutSeconds`	`number`

Returns

Promise<boolean>

writeStdin()

writeStdin(data): Promise<void>

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

Parameters

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

Returns

Promise<void>

ExecStream

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

Example

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

Implements

AsyncIterable<string>

Methods

[asyncIterator]()

[asyncIterator](): AsyncIterator<string>

Returns

AsyncIterator<string>

Implementation of

AsyncIterable.[asyncIterator]

bytes()

bytes(): Promise<Buffer<ArrayBufferLike>>

Collect the whole raw byte stream into a single Buffer.

Returns

Promise<Buffer<ArrayBufferLike>>

raw()

raw(): AsyncIterableIterator<Buffer<ArrayBufferLike>>

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

Returns

AsyncIterableIterator<Buffer<ArrayBufferLike>>

text()

text(): Promise<string>

Collect the whole stream into a single string.

Returns

Promise<string>

toReadable()

toReadable(): Readable

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

Returns

Readable

SailboxFs

Filesystem operations on a Sailbox’s guest, reached via Sailbox.fs. File I/O streams bytes to/from the guest; the directory helpers create, remove, 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>

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

Parameters

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

Returns

Promise<void>

writeStream()

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

Open a streaming upload to a guest file.

Parameters

Parameter	Type
`path`	`string`
`options?`	`WriteOptions`

Returns

Promise<FileWriter>

FileWriter

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

Methods

[asyncDispose]()

[asyncDispose](): Promise<void>

await using support; same semantics as the synchronous form.

Returns

Promise<void>

[dispose]()

[dispose](): void

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

Returns

void

abort()

abort(): void

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

Returns

void

finish()

finish(): Promise<void>

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

Returns

Promise<void>

toWritable()

toWritable(): Writable

Adapt to a Node Writable: end() runs finish (only that commits the write), destroying the stream aborts it, and backpressure follows the underlying transfer since each chunk’s callback fires when 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 NFS volume that can be mounted into Sailboxes. Look one up (or mint it) with Volume.find, then pass it (or its Volume.id) in a Sailbox’s volumes mapping.Volumes are currently in Alpha. To pilot them, reach out in the Sail Slack: https://join.slack.com/t/sailresearchcrew/shared_invite/zt-41pdcym9j-UU0Ey~A~r6n2H0DQVQsQHQ.

Properties

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

Methods

delete()

delete(options?): Promise<boolean>

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

Parameters

Parameter	Type
`options`	`DeleteVolumeOptions`

Returns

Promise<boolean>

find()

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

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

Parameters

Parameter	Type
`name`	`string`
`options`	`FindVolumeOptions`

Returns

Promise<Volume>

fromMount()

static fromMount(path): Volume

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

Parameters

Parameter	Type
`path`	`string`

Returns

Volume

list()

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

List NFS volumes in the current org.

Parameters

Parameter	Type
`options`	`ListVolumesOptions`

Returns

Promise<Volume[]>

ingressAuthHeaders()

ingressAuthHeaders(): Record<string, string>

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

Returns

Record<string, string>

Client

A configured Sail client: the low-level, 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>

createFromCheckpoint()

createFromCheckpoint(params): Promise<SailboxHandle>

Create a new Sailbox from a checkpoint.

Parameters

Parameter	Type
`params`	`FromCheckpointRequest`

Returns

Promise<SailboxHandle>

createSailbox()

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

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

Parameters

Parameter	Type	Default value
`req`	`CreateSailboxRequest`	`undefined`
`timeoutSeconds`	`number`	`600`

Returns

Promise<SailboxHandle>

deleteVolume()

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

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

Parameters

Parameter	Type	Default value
`volumeId`	`string`	`undefined`
`allowMissing`	`boolean`	`false`

Returns

Promise<VolumeInfo | null>

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>

enableSsh()

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

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

Parameters

Parameter	Type
`sailboxId`	`string`
`options`	`EnableSshOptions`

Returns

Promise<SshEndpoint | null>

exec()

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

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

Parameters

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

Returns

Promise<ExecProcess>

exposeListener()

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

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

Parameters

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

Returns

Promise<Listener>

findApp()

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

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

Parameters

Parameter	Type	Default value
`name`	`string`	`undefined`
`mintIfMissing`	`boolean`	`false`

Returns

Promise<AppInfo>

getListener()

getListener(sailboxId, guestPort): Promise<Listener>

Fetch one listener by guest port without waking the Sailbox.

Parameters

Parameter	Type
`sailboxId`	`string`
`guestPort`	`number`

Returns

Promise<Listener>

getSailbox()

getSailbox(sailboxId): Promise<SailboxInfo>

Fetch one Sailbox by id.

Parameters

Parameter	Type
`sailboxId`	`string`

Returns

Promise<SailboxInfo>

getVolume()

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

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

Parameters

Parameter	Type	Default value
`name`	`string`	`undefined`
`mintIfMissing`	`boolean`	`false`

Returns

Promise<VolumeInfo>

ingressAuthHeaders()

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

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

Parameters

Parameter	Type
`sailboxId`	`string`

Returns

Promise<Record<string, string>>

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

listListeners()

listListeners(sailboxId): Promise<Listener[]>

List a Sailbox’s listeners without waking it.

Parameters

Parameter	Type
`sailboxId`	`string`

Returns

Promise<Listener[]>

listSailboxes()

listSailboxes(params?): Promise<SailboxInfoPage>

List one page of Sailboxes in the current org.

Parameters

Parameter	Type
`params`	`ListSailboxesQuery`

Returns

Promise<SailboxInfoPage>

listVolumes()

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

List NFS volumes in the current org.

Parameters

Parameter	Type
`maxObjects?`	`number`

Returns

Promise<VolumeInfo[]>

makeDir()

makeDir(sailboxId, path, 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>

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>

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>

shell()

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

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

Parameters

Parameter	Type
`sailboxId`	`string`
`command?`	`string`
`options?`	`ShellOptions`

Returns

Promise<number>

sleepSailbox()

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

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

Parameters

Parameter	Type
`sailboxId`	`string`
`wakeAt?`	`string`

Returns

Promise<string | null>

terminateSailbox()

terminateSailbox(sailboxId): Promise<void>

Terminate a Sailbox (idempotent).

Parameters

Parameter	Type
`sailboxId`	`string`

Returns

Promise<void>

unexposeListener()

unexposeListener(sailboxId, guestPort): Promise<void>

Remove a runtime ingress port.

Parameters

Parameter	Type
`sailboxId`	`string`
`guestPort`	`number`

Returns

Promise<void>

upgradeSailbox()

upgradeSailbox(sailboxId): Promise<UpgradeResult>

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

Parameters

Parameter	Type
`sailboxId`	`string`

Returns

Promise<UpgradeResult>

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>

waitForListener()

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

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

Parameters

Parameter	Type
`sailboxId`	`string`
`guestPort`	`number`
`timeoutSeconds`	`number`

Returns

Promise<Listener>

writeStream()

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

Open a streaming upload to a guest file.

Parameters

Parameter	Type
`sailboxId`	`string`
`path`	`string`
`options`	`WriteOptions`

Returns

Promise<FileWriter>

fromConfig()

static fromConfig(config): Client

Build a client from an explicit ClientConfig.

Parameters

Parameter	Type
`config`	`ClientConfig`

Returns

fromEnv()

static fromEnv(): Client

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

Returns

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

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 Sailboxes that are doing nothing, freeing their memory and waking them the moment anything needs them again. Waking takes a couple of seconds: free for a batch job, unwelcome if someone is waiting at a terminal.Both settings can only make Sail sleep the Sailbox less often. Neither causes a sleep, and Sail still sleeps a Sailbox only when it sits fully idle: no busy process, no imminent timer, nothing a sleep would interrupt. 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`	Make Sail wait at least this long before sleeping it. A value below Sail’s own wait has no effect; values above one hour 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.

Properties

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

CreateSailboxOptions

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

Extends

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

Properties

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

CreateSailboxRequest

Extends

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

Properties

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

DeleteVolumeOptions

Options for Volume.delete.

Properties

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

DirEntry

One entry in a directory listing from Sailbox.fs.ls, 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 as reported by the guest.	`Omit.size`
`type`	`DirEntryType`	-	-

DirEntryType

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

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

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.

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.

EnableSshOptions

Options for enabling SSH on a Sailbox.

Properties

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

ExecOptions

Options for starting an exec.

Extends

Omit<native.ExecStartOptions, "env">

Properties

Property	Type	Description	Inherited from
`background?`	`boolean`	Detach the command so it keeps running and the call returns immediately; output is discarded (shell commands only, incompatible with `openStdin`/`pty`).	`Omit.background`
`cols?`	`number`	Initial pty width in columns.	`Omit.cols`
`cwd?`	`string`	Working directory to run the command in (shell commands only). 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.	`Omit.idempotencyKey`
`openStdin?`	`boolean`	Leave stdin open for `writeStdin`.	`Omit.openStdin`
`pty?`	`boolean`	Allocate a pseudo-terminal.	`Omit.pty`
`rows?`	`number`	Initial pty height in rows.	`Omit.rows`
`term?`	`string`	TERM value for the pty.	`Omit.term`
`timeoutSeconds?`	`number`	Wall-clock limit in seconds before the server kills the command.	`Omit.timeoutSeconds`
`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 authoritative result of a finished exec.The buffered stdout/stderr are a capped, drop-oldest tail (the server keeps a bounded ring). To capture the complete output of a large-output command, stream it live and consult the *Truncated/*Complete flags.

Properties

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

ExposeOptions

Options for Sailbox.expose.

Properties

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

FindAppOptions

Options for App.find.

Extends

ClientOptions

Properties

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

FindVolumeOptions

Options for Volume.find.

Extends

ClientOptions

Properties

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

FromCheckpointOptions

Options for Sailbox.fromCheckpoint.

Extends

FromCheckpointRequest.ClientOptions

Properties

Property	Type	Description	Inherited from
`checkpointId`	`string`	The checkpoint to restore from.	`FromCheckpointRequest`.`checkpointId`
`client?`	`Client`	Use a specific client instead of the default (env) one.	`ClientOptions`.`client`
`name?`	`string`	Name for the new Sailbox. Defaults to a name derived from the Sailbox the checkpoint came from.	`FromCheckpointRequest`.`name`
`timeoutSeconds?`	`number`	Whole seconds, positive when given. Bounds the call, since restoring a checkpoint can block for many minutes while the new Sailbox queues for capacity. A call that times out fails, and the restore may still finish in the background; the new Sailbox then shows up when you list Sailboxes. Unset waits without a bound.	`FromCheckpointRequest`.`timeoutSeconds`

FromCheckpointRequest

The create-from-checkpoint request.

Extended by

FromCheckpointOptions

Properties

Property	Type	Description
`checkpointId`	`string`	The checkpoint to restore from.
`name?`	`string`	Name for the new Sailbox. Defaults to a name derived from the Sailbox the checkpoint came from.
`timeoutSeconds?`	`number`	Whole seconds, positive when given. Bounds the call, since restoring a checkpoint can block for many minutes while the new Sailbox queues for capacity. A call that times out fails, and the restore may still finish in the background; the new Sailbox then shows up when you list Sailboxes. Unset waits without a bound.

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.

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. A`user`other 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
`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 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.
`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; pipInstall?: never; runCommand?: never; } | { addLocalDir?: never; addLocalFile?: never; aptInstall?: never; pipInstall: PackageInstall; runCommand?: never; } | { addLocalDir?: never; addLocalFile?: never; aptInstall?: never; pipInstall?: never; runCommand: RunCommand; } | { addLocalDir?: never; addLocalFile: AddLocalFile; aptInstall?: never; pipInstall?: never; runCommand?: never; } | { addLocalDir: AddLocalDir; addLocalFile?: never; aptInstall?: never; pipInstall?: never; runCommand?: never; }

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

ImageDefinition

A custom image definition: a base, registry, or Dockerfile 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` 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?`	`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`.
`dockerfile?`	`DockerfileSourceInput`	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.
`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` and `dockerfile`.
`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 or registry 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.

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

PackageInstall

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

Properties

Property	Type	Description
`packages?`	`string`[]	Package names.

Protocol

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

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

ResolvedConfig

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

Extends

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

Properties

Property	Type	Description	Inherited from
`apiKey?`	`string`	The resolved API key; absent when none is configured.	`Omit.apiKey`
`apiUrl`	`string`	Sail API URL.	`Omit.apiUrl`
`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">

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.	`Pick.idempotencyKey`
`signal?`	`AbortSignal`	Aborting rejects with the signal’s reason and force-cancels the remote command (SIGKILL, like ExecProcess.cancel with `force`), briefly retrying transient failures. Best effort: the kill is sent once the submission settles (an abort mid-submission cancels the command as soon as its launch is confirmed), and a kill that still fails leaves the command running.	-
`timeoutSeconds?`	`number`	Wall-clock limit in seconds before the server kills the command.	`Pick.timeoutSeconds`
`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.

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

Properties

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

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.
`noForward?`	`boolean`	While attached, the Sailbox’s browser opens and localhost servers reach your machine, files dragged onto the terminal upload and paste as guest paths, and Ctrl+V forwards your clipboard. On devbox images the clipboard is two-way (pastes land on the Sailbox’s clipboard, and what you copy inside the Sailbox comes back); other images upload a pasted image as a file and paste its path. Set `true` to turn all of it off, for example for an untrusted or automated session.
`noForwardBrowser?`	`boolean`	Set `true` to keep everything forwarded except browser opens. Ignored when `noForward` is set.
`shell?`	`string`	Login shell to run when no command is given (default: the guest’s `$SHELL`, else `/bin/bash`). Ignored when a command is given.
`term?`	`string`	`$TERM` for the remote pty (default: the local `$TERM`).
`timeoutSeconds?`	`number`	Wall-clock limit for the session in seconds; omit for no limit.
`user?`	`string`	Run the session as this user (Docker’s `USER` syntax: `name	uid[:group	gid]`). Unset runs as the image's` USER`when the image sets one, root otherwise: the same identity [Sailbox.exec](#exec-1) uses.`”0:0”`is always root. A`user`other 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 NFS volume. Timestamps are RFC 3339 strings.

Properties

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

VolumeMountInput

An NFS volume to mount at create time.

Properties

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

WaitForListenerOptions

Options for Sailbox.waitForListener.

Properties

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

WriteOptions

Options for uploading a file.

Properties

Property	Type	Description
`createParents?`	`boolean`	Create missing parent directories.
`mode?`	`number`	Unix mode bits for the written file.
`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` USER`when 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 RPC failure). `false` when the failure is deterministic (bad argument, missing resource, permission). The SDK’s built-in retry already covers the transient window for most calls; this classifies what leaks past it.

ApiError

A non-2xx API response.

Extends

SailError

Constructors

Constructor

new ApiError(message, details?): ApiError

Parameters

Parameter	Type
`message`	`string`
`details`	`SailErrorDetails`

Returns

ApiError

Overrides

Properties

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

BrokenPipeError

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

Extends

SailError

Constructors

Constructor

new BrokenPipeError(message, details?): BrokenPipeError

Parameters

Parameter	Type
`message`	`string`
`details`	`SailErrorDetails`

Returns

BrokenPipeError

Overrides

Properties

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

CommandFailedError

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

Extends

SailboxExecutionError

Constructors

Constructor

new CommandFailedError(message, result): CommandFailedError

Parameters

Parameter	Type
`message`	`string`
`result`	`ExecResult`

Returns

CommandFailedError

Overrides

Properties

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

FileNotFoundError

A remote file path does not exist.

Extends

SailError

Constructors

Constructor

new FileNotFoundError(message, details?): FileNotFoundError

Parameters

Parameter	Type
`message`	`string`
`details`	`SailErrorDetails`

Returns

FileNotFoundError

Overrides

Properties

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

ImageBuildError

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

Extends

SailError

Constructors

Constructor

new ImageBuildError(message, details?): ImageBuildError

Parameters

Parameter	Type
`message`	`string`
`details`	`SailErrorDetails`

Returns

ImageBuildError

Overrides

Properties

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

InternalError

An unexpected internal SDK failure.

Extends

SailError

Constructors

Constructor

new InternalError(message, details?): InternalError

Parameters

Parameter	Type
`message`	`string`
`details`	`SailErrorDetails`

Returns

InternalError

Overrides

Properties

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

InvalidArgumentError

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

Extends

SailError

Constructors

Constructor

new InvalidArgumentError(message, details?): InvalidArgumentError

Parameters

Parameter	Type
`message`	`string`
`details`	`SailErrorDetails`

Returns

InvalidArgumentError

Overrides

Properties

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

NotFoundError

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

Extends

SailError

Constructors

Constructor

new NotFoundError(message, details?): NotFoundError

Parameters

Parameter	Type
`message`	`string`
`details`	`SailErrorDetails`

Returns

NotFoundError

Overrides

Properties

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

PermissionDeniedError

The credential is not permitted to perform the operation.

Extends

SailError

Constructors

Constructor

new PermissionDeniedError(message, details?): PermissionDeniedError

Parameters

Parameter	Type
`message`	`string`
`details`	`SailErrorDetails`

Returns

PermissionDeniedError

Overrides

Properties

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

SailboxCreationError

A Sailbox could not be created (provisioning failed).

Extends

SailError

Constructors

Constructor

new SailboxCreationError(message, details?): SailboxCreationError

Parameters

Parameter	Type
`message`	`string`
`details`	`SailErrorDetails`

Returns

SailboxCreationError

Overrides

SailboxExecRequestNotFoundError

Properties

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

SailboxExecRequestNotFoundError

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

Extends

SailboxExecutionError

Constructors

Constructor

new SailboxExecRequestNotFoundError(message, details?): SailboxExecRequestNotFoundError

Parameters

Parameter	Type
`message`	`string`
`details`	`SailErrorDetails`

Returns

Overrides

Properties

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

SailboxExecutionError

Base class for failures during an exec.

Extends

SailError

Extended by

CommandFailedError
SailboxTerminatedError
SailboxExecRequestNotFoundError
SailboxHostLostError

Constructors

Constructor

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

Parameters

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

Returns

SailboxExecutionError

Overrides

Properties

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

SailboxHostLostError

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

Extends

SailboxExecutionError

Constructors

Constructor

new SailboxHostLostError(message, details?): SailboxHostLostError

Parameters

Parameter	Type
`message`	`string`
`details`	`SailErrorDetails`

Returns

SailboxHostLostError

Overrides

Properties

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

SailboxTerminatedError

The Sailbox was terminated while an exec was in flight.

Extends

SailboxExecutionError

Constructors

Constructor

new SailboxTerminatedError(message, details?): SailboxTerminatedError

Parameters

Parameter	Type
`message`	`string`
`details`	`SailErrorDetails`

Returns

SailboxTerminatedError

Overrides

Properties

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

TimeoutError

A request exceeded its timeout.

Extends

SailError

Constructors

Constructor

new TimeoutError(message, details?): TimeoutError

Parameters

Parameter	Type
`message`	`string`
`details`	`SailErrorDetails`

Returns

TimeoutError

Overrides

Properties

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

TransportError

A network/connection transport failure.

Extends

SailError

Constructors

Constructor

new TransportError(message, details?): TransportError

Parameters

Parameter	Type
`message`	`string`
`details`	`SailErrorDetails`

Returns

TransportError

Overrides