TypeScript SDK reference

Classes

ApiError

A transient, retryable server-side API failure.

Extends

SailError

Constructors

Constructor

new ApiError(message): ApiError

Parameters

Parameter	Type
`message`	`string`

Returns

ApiError

Overrides

SailError.constructor

Properties

Property	Modifier	Type	Description	Inherited from
`code`	`readonly`	`string`	Stable, language-neutral error code (e.g. `"NotFound"`).	`SailError`.`code`

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`	`ClientOptions` & `object`

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

BrokenPipeError

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

Extends

SailError

Constructors

Constructor

new BrokenPipeError(message): BrokenPipeError

Parameters

Parameter	Type
`message`	`string`

Returns

BrokenPipeError

Overrides

SailError.constructor

Properties

Property	Modifier	Type	Description	Inherited from
`code`	`readonly`	`string`	Stable, language-neutral error code (e.g. `"NotFound"`).	`SailError`.`code`

Client

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

Methods

buildImageDefinition()

buildImageDefinition(def, timeoutSeconds): Promise<ImageSpec>

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

Parameters

Parameter	Type
`def`	`ImageDefinition`
`timeoutSeconds`	`number`

Returns

Promise<ImageSpec>

buildSpecToReady()

buildSpecToReady(spec, timeoutSeconds): Promise<ImageBuild>

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

Parameters

Parameter	Type
`spec`	`ImageSpec`
`timeoutSeconds`	`number`

Returns

Promise<ImageBuild>

checkpointSailbox()

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

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

Parameters

Parameter	Type
`sailboxId`	`string`
`options`	`CheckpointOptions`

Returns

Promise<SailboxCheckpoint>

createFromCheckpoint()

createFromCheckpoint(params): Promise<SailboxHandle>

Create a new sailbox from a checkpoint.

Parameters

Parameter	Type
`params`	`FromCheckpointRequest`

Returns

Promise<SailboxHandle>

createSailbox()

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

Create a sailbox. timeoutSeconds bounds each create attempt (default 600s); pass 0 for no client-side timeout. Timed-out attempts are retried, reattaching to the same box, so when the overall budget is exhausted the box 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. Resolves null when allowMissing and it’s gone.

Parameters

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

Returns

Promise<VolumeInfo | null>

enableSsh()

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

Enable SSH on a sailbox: trust the org SSH CA, start sshd, and expose guest port 22 as TCP once the CA-only daemon owns it. A non-empty allowlist restricts port 22 to those source CIDRs, 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).

Parameters

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

Returns

Promise<ExecProcess>

exposeListener()

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

Expose a guest port at runtime (route status starts “unspecified”; the response confirms configuration, not reachability).

Parameters

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

Returns

Promise<Listener>

findApp()

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

Find an app by name, optionally minting it.

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

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 (optionally minting) an NFS volume by name.

Parameters

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

Returns

Promise<VolumeInfo>

ingressAuthHeaders()

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

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

Parameters

Parameter	Type
`sailboxId`	`string`

Returns

Promise<Record<string, string>>

isBuiltinBaseSpec()

isBuiltinBaseSpec(spec): boolean

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

Parameters

Parameter	Type
`spec`	`ImageSpec`

Returns

boolean

listApps()

listApps(): Promise<AppInfo[]>

Every app the current org owns, newest first.

Returns

Promise<AppInfo[]>

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

orgSshCaPublicKey()

orgSshCaPublicKey(): Promise<string>

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

Returns

Promise<string>

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>

resolveImage()

resolveImage(def): Promise<ImageSpec>

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

Parameters

Parameter	Type
`def`	`ImageDefinition`

Returns

Promise<ImageSpec>

resumeSailbox()

resumeSailbox(sailboxId): Promise<SailboxHandle>

Resume a paused or sleeping sailbox.

Parameters

Parameter	Type
`sailboxId`	`string`

Returns

Promise<SailboxHandle>

shell()

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

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

Parameters

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

Returns

Promise<number>

sleepSailbox()

sleepSailbox(sailboxId): Promise<void>

Sleep a sailbox to disk (wakes on traffic).

Parameters

Parameter	Type
`sailboxId`	`string`

Returns

Promise<void>

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 in-guest agent (now if running, else at next wake).

Parameters

Parameter	Type
`sailboxId`	`string`

Returns

Promise<UpgradeResult>

waitForListener()

waitForListener(sailboxId, guestPort, timeoutSeconds, pollIntervalSeconds): 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`
`pollIntervalSeconds`	`number`

Returns

Promise<Listener>

writeStream()

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

Open a streaming upload to a guest file.

Parameters

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

Returns

Promise<FileWriter>

fromConfig()

static fromConfig(config): Client

Build a client from an explicit ClientConfig.

Parameters

Parameter	Type
`config`	`ClientConfig`

Returns

Client

fromEnv()

static fromEnv(): Client

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

Returns

Client

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 as an async iterable of decoded chunks.
`stdout`	`readonly`	`ExecStream`	Stdout as an async iterable of decoded chunks.

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

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

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). Chunks are decoded UTF-8 strings; iteration ends at end of 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]

text()

text(): Promise<string>

Collect the whole stream into a single string.

Returns

Promise<string>

toReadable()

toReadable(): Readable

Adapt to a Node Readable (e.g. to .pipe() it somewhere).

Returns

Readable

FileNotFoundError

A remote file path does not exist.

Extends

SailError

Constructors

Constructor

new FileNotFoundError(message): FileNotFoundError

Parameters

Parameter	Type
`message`	`string`

Returns

FileNotFoundError

Overrides

SailError.constructor

Properties

Property	Modifier	Type	Description	Inherited from
`code`	`readonly`	`string`	Stable, language-neutral error code (e.g. `"NotFound"`).	`SailError`.`code`

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

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

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>

write()

write(data): Promise<void>

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

Parameters

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

Returns

Promise<void>

Image

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

Example

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

Methods

addLocalDir()

addLocalDir(localPath, remotePath, options?): Image

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

Parameters

Parameter	Type
`localPath`	`string`
`remotePath`	`string`
`options`	`AddLocalDirOptions`

Returns

Image

addLocalFile()

addLocalFile(localPath, remotePath, options?): Image

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

Parameters

Parameter	Type
`localPath`	`string`
`remotePath`	`string`
`options`	`AddLocalFileOptions`

Returns

Image

aptInstall()

aptInstall(…packages): Image

Install system packages with apt.

Parameters

Parameter	Type
…`packages`	`string`[]

Returns

Image

build()

build(options?): Promise<ImageSpec>

Upload any local files and build the image, waiting until it is ready. Returns the resolved ImageSpec. Sailbox.create calls this for a custom image before creating the sailbox (the backend serves the content-addressed built image); a bare base image skips the build.

Parameters

Parameter	Type
`options`	{ `client?`: `Client`; `timeoutSeconds?`: `number`; }
`options.client?`	`Client`
`options.timeoutSeconds?`	`number`

Returns

Promise<ImageSpec>

env()

env(env): Image

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

Parameters

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

Returns

Image

pipInstall()

pipInstall(…packages): Image

Install Python packages with pip.

Parameters

Parameter	Type
…`packages`	`string`[]

Returns

Image

runCommand()

runCommand(command): Image

Run a shell command during the build.

Parameters

Parameter	Type
`command`	`string`

Returns

Image

toSpec()

toSpec(client?): Promise<ImageSpec>

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

Parameters

Parameter	Type
`client?`	`Client`

Returns

Promise<ImageSpec>

debian()

static debian(architecture?): Image

A Debian base image (defaults to arm64).

Parameters

Parameter	Type	Default value
`architecture`	`ImageArchitecture`	`"arm64"`

Returns

Image

devbox()

static devbox(architecture?): Image

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

Parameters

Parameter	Type	Default value
`architecture`	`ImageArchitecture`	`"arm64"`

Returns

Image

ImageBuildError

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

Extends

SailError

Constructors

Constructor

new ImageBuildError(message): ImageBuildError

Parameters

Parameter	Type
`message`	`string`

Returns

ImageBuildError

Overrides

SailError.constructor

Properties

Property	Modifier	Type	Description	Inherited from
`code`	`readonly`	`string`	Stable, language-neutral error code (e.g. `"NotFound"`).	`SailError`.`code`

InternalError

An unexpected internal SDK/core failure.

Extends

SailError

Constructors

Constructor

new InternalError(message): InternalError

Parameters

Parameter	Type
`message`	`string`

Returns

InternalError

Overrides

SailError.constructor

Properties

Property	Modifier	Type	Description	Inherited from
`code`	`readonly`	`string`	Stable, language-neutral error code (e.g. `"NotFound"`).	`SailError`.`code`

InvalidArgumentError

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

Extends

SailError

Constructors

Constructor

new InvalidArgumentError(message): InvalidArgumentError

Parameters

Parameter	Type
`message`	`string`

Returns

InvalidArgumentError

Overrides

SailError.constructor

Properties

Property	Modifier	Type	Description	Inherited from
`code`	`readonly`	`string`	Stable, language-neutral error code (e.g. `"NotFound"`).	`SailError`.`code`

NotFoundError

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

Extends

SailError

Constructors

Constructor

new NotFoundError(message): NotFoundError

Parameters

Parameter	Type
`message`	`string`

Returns

NotFoundError

Overrides

SailError.constructor

Properties

Property	Modifier	Type	Description	Inherited from
`code`	`readonly`	`string`	Stable, language-neutral error code (e.g. `"NotFound"`).	`SailError`.`code`

PermissionDeniedError

The credential is not permitted to perform the operation.

Extends

SailError

Constructors

Constructor

new PermissionDeniedError(message): PermissionDeniedError

Parameters

Parameter	Type
`message`	`string`

Returns

PermissionDeniedError

Overrides

SailError.constructor

Properties

Property	Modifier	Type	Description	Inherited from
`code`	`readonly`	`string`	Stable, language-neutral error code (e.g. `"NotFound"`).	`SailError`.`code`

Sailbox

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

Example

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

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

Accessors

appId

Get Signature

get appId(): string | undefined

Identifier of the owning app.

Returns

string | undefined

appName

Get Signature

get appName(): string | undefined

Name of the owning app.

Returns

string | undefined

architecture

Get Signature

get architecture(): string | undefined

CPU architecture (for example arm64).

Returns

string | undefined

checkpointGeneration

Get Signature

get checkpointGeneration(): number | undefined

Checkpoint generation counter as of the snapshot.

Returns

number | undefined

client

Get Signature

get client(): Client

The underlying Client.

Returns

Client

cpuRequestedVcpu

Get Signature

get cpuRequestedVcpu(): number | undefined

Requested CPU, in vCPUs.

Returns

number | undefined

cpuUsedVcpu

Get Signature

get cpuUsedVcpu(): number | undefined

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

Returns

number | undefined

createdAt

Get Signature

get createdAt(): Date | undefined

When the sailbox was created.

Returns

Date | undefined

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

guestSchemaVersion

Get Signature

get guestSchemaVersion(): number | undefined

In-guest agent 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 current boot started (RFC 3339).

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

Methods

checkpoint()

checkpoint(options?): Promise<SailboxCheckpoint>

Take a checkpoint of this sailbox. The returned handle carries expiresAt, when it becomes eligible for garbage collection.

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

Parameters

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

Returns

Promise<ExecProcess>

expose()

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

Expose a guest port at runtime. The returned listener carries the resolved endpoint but an "unspecified" route status: the response confirms configuration, not reachability; waitForListener confirms the route is live.

Parameters

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

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

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>

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>

resume()

resume(): Promise<void>

Resume this sailbox (updates status).

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

Parameters

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

Returns

Promise<number>

sleep()

sleep(): Promise<void>

Sleep this sailbox to disk (wakes on traffic).

Returns

Promise<void>

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 in-guest agent.

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>

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>

create()

static create(options): Promise<Sailbox>

Create a new sailbox.

Parameters

Parameter	Type
`options`	`CreateSailboxOptions`

Returns

Promise<Sailbox>

fromCheckpoint()

static fromCheckpoint(options): Promise<Sailbox>

Create a new sailbox from a checkpoint.

Parameters

Parameter	Type
`options`	`FromCheckpointOptions`

Returns

Promise<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?, options?): Promise<Sailbox[]>

List one page of sailboxes as Sailbox instances.

Parameters

Parameter	Type
`params`	`ListSailboxesQuery`
`options`	`ClientOptions`

Returns

Promise<Sailbox[]>

listPage()

static listPage(params?, options?): Promise<SailboxPage>

Like list but also returns the pagination envelope (total/hasMore) for paging through large result sets.

Parameters

Parameter	Type
`params`	`ListSailboxesQuery`
`options`	`ClientOptions`

Returns

Promise<SailboxPage>

SailboxCreationError

A sailbox could not be created (provisioning failed).

Extends

SailError

Constructors

Constructor

new SailboxCreationError(message): SailboxCreationError

Parameters

Parameter	Type
`message`	`string`

Returns

SailboxCreationError

Overrides

SailError.constructor

Properties

Property	Modifier	Type	Description	Inherited from
`code`	`readonly`	`string`	Stable, language-neutral error code (e.g. `"NotFound"`).	`SailError`.`code`

SailboxExecRequestNotFoundError

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

Extends

SailboxExecutionError

Constructors

Constructor

new SailboxExecRequestNotFoundError(message): SailboxExecRequestNotFoundError

Parameters

Parameter	Type
`message`	`string`

Returns

SailboxExecRequestNotFoundError

Overrides

SailboxExecutionError.constructor

Properties

Property	Modifier	Type	Description	Inherited from
`code`	`readonly`	`string`	Stable, language-neutral error code (e.g. `"NotFound"`).	`SailboxExecutionError`.`code`

SailboxExecutionError

Base class for failures during an exec.

Extends

SailError

Constructors

Constructor

new SailboxExecutionError(message, code?): SailboxExecutionError

Parameters

Parameter	Type	Default value
`message`	`string`	`undefined`
`code`	`string`	`"SailboxExecutionError"`

Returns

SailboxExecutionError

Overrides

SailError.constructor

Properties

Property	Modifier	Type	Description	Inherited from
`code`	`readonly`	`string`	Stable, language-neutral error code (e.g. `"NotFound"`).	`SailError`.`code`

SailboxTerminatedError

The sailbox was terminated while an exec was in flight.

Extends

SailboxExecutionError

Constructors

Constructor

new SailboxTerminatedError(message): SailboxTerminatedError

Parameters

Parameter	Type
`message`	`string`

Returns

SailboxTerminatedError

Overrides

SailboxExecutionError.constructor

Properties

Property	Modifier	Type	Description	Inherited from
`code`	`readonly`	`string`	Stable, language-neutral error code (e.g. `"NotFound"`).	`SailboxExecutionError`.`code`

SailboxWorkerLostError

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

Extends

SailboxExecutionError

Constructors

Constructor

new SailboxWorkerLostError(message): SailboxWorkerLostError

Parameters

Parameter	Type
`message`	`string`

Returns

SailboxWorkerLostError

Overrides

SailboxExecutionError.constructor

Properties

Property	Modifier	Type	Description	Inherited from
`code`	`readonly`	`string`	Stable, language-neutral error code (e.g. `"NotFound"`).	`SailboxExecutionError`.`code`

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?): SailError

Parameters

Parameter	Type	Default value
`message`	`string`	`undefined`
`code`	`string`	`"SailError"`

Returns

SailError

Overrides

Error.constructor

Properties

Property	Modifier	Type	Description
`code`	`readonly`	`string`	Stable, language-neutral error code (e.g. `"NotFound"`).

TimeoutError

A request exceeded its timeout.

Extends

SailError

Constructors

Constructor

new TimeoutError(message): TimeoutError

Parameters

Parameter	Type
`message`	`string`

Returns

TimeoutError

Overrides

SailError.constructor

Properties

Property	Modifier	Type	Description	Inherited from
`code`	`readonly`	`string`	Stable, language-neutral error code (e.g. `"NotFound"`).	`SailError`.`code`

TransportError

A network/connection transport failure.

Extends

SailError

Constructors

Constructor

new TransportError(message): TransportError

Parameters

Parameter	Type
`message`	`string`

Returns

TransportError

Overrides

SailError.constructor

Properties

Property	Modifier	Type	Description	Inherited from
`code`	`readonly`	`string`	Stable, language-neutral error code (e.g. `"NotFound"`).	`SailError`.`code`

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.

Properties

Property	Modifier	Type	Default value	Description
`backend`	`readonly`	`string`	`undefined`	Storage backend serving the volume.
`createdAt`	`readonly`	`Date` \| `null`	`undefined`	Creation time, if reported.
`id`	`readonly`	`string`	`undefined`	Stable volume id.
`mountPath`	`readonly`	`string` \| `null`	`null`	Guest mount path, when loaded via Volume.fromMount.
`name`	`readonly`	`string`	`undefined`	Volume name.
`status`	`readonly`	`string`	`undefined`	Lifecycle status.
`updatedAt`	`readonly`	`Date` \| `null`	`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`	{ `allowMissing?`: `boolean`; }
`options.allowMissing?`	`boolean`

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`	`ClientOptions` & `object`

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`	`ClientOptions` & `object`

Returns

Promise<Volume[]>

Interfaces

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

CancelOptions

Options for cancelling an exec.

Properties

Property	Type	Description
`force?`	`boolean`	Send SIGKILL instead of SIGINT.
`retryTimeoutSeconds?`	`number`	Budget in seconds for retrying the cancel against a waking/migrating box.

CheckpointOptions

Options for Sailbox.checkpoint.

Properties

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

ClientConfig

Explicit client configuration (an alternative to environment resolution).

Extends

Omit<native.ClientConfig, "mode">

Properties

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

ClientOptions

Options for statics that select which Client to use.

Extended by

CreateSailboxOptions
FromCheckpointOptions

Properties

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

CreateSailboxOptions

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

Extends

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

Properties

Property	Type	Description	Overrides	Inherited from
`app`	`string` \| `App`	The owning app, or its id.	-	-
`autosleepTimeoutMinutes?`	`number`	Idle minutes (1-1440) after which Sail may sleep the box.	-	`Omit.autosleepTimeoutMinutes`
`client?`	`Client`	Use a specific client instead of the default (env) one.	-	`ClientOptions`.`client`
`diskGib?`	`number`	Disk size in whole GiB within the size’s range; the size’s default when omitted.	-	`Omit.diskGib`
`image?`	`ImageSpec` \| `Image`	Image spec, or an Image builder (built and resolved at create). Defaults to a plain Debian base.	-	-
`imageBuildTimeoutSeconds?`	`number`	Timeout in seconds for building a custom `Image` before create (1800).	-	-
`ingressPorts?`	(`number` \| `IngressPortInput`)[]	Guest ports to expose: a bare number is HTTP shorthand.	-	-
`memoryGib?`	`number`	Memory limit in whole GiB within the size’s range; the size’s default when omitted.	-	`Omit.memoryGib`
`name`	`string`	The sailbox name.	-	`Omit.name`
`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. Timed-out attempts are retried, reattaching to the same box, so when the overall budget is exhausted the box may still be coming up server-side: find or terminate it by `name`.	-	-
`volumes?`	`Record`<`string`, `string` \| `Volume`>	Shared volumes to mount, mapping an absolute guest path to a Volume or volume id.	-	-

CreateSailboxRequest

Extends

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

Properties

Property	Type	Description	Inherited from
`appId`	`string`	Identifier of the owning app.	`Omit.appId`
`autosleepTimeoutMinutes?`	`number`	Idle minutes (1-1440) after which Sail may sleep the box.	`Omit.autosleepTimeoutMinutes`
`diskGib?`	`number`	Disk size in whole GiB within the size’s range; the size’s default when omitted.	`Omit.diskGib`
`image?`	`ImageSpec`	Image to boot; defaults to a plain Debian base when omitted.	-
`ingressPorts?`	`IngressPortInput`[]	Guest ports to reserve for ingress.	-
`memoryGib?`	`number`	Memory limit in whole GiB within the size’s range; the size’s default when omitted.	`Omit.memoryGib`
`name`	`string`	The sailbox name.	`Omit.name`
`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?`	`VolumeMountInput`[]	NFS volumes to mount.	`Omit.volumeMounts`

EnableSshOptions

Options for enabling SSH on a sailbox.

Properties

Property	Type	Description
`allowlist?`	`string`[]	Source CIDRs 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.

Properties

Property	Type	Description
`background?`	`boolean`	Detach the command so it keeps running and the call returns immediately; output is discarded (shell commands only, incompatible with `openStdin`/`pty`).
`cols?`	`number`	Initial pty width in columns.
`cwd?`	`string`	Working directory to run the command in (shell commands only).
`idempotencyKey?`	`string`	Stable key so a reconnect reattaches to the same command.
`openStdin?`	`boolean`	Leave stdin open for `writeStdin`.
`pty?`	`boolean`	Allocate a pseudo-terminal.
`retryTimeoutSeconds?`	`number`	Budget in seconds for retrying transient RPC failures.
`rows?`	`number`	Initial pty height in rows.
`term?`	`string`	TERM value for the pty.
`timeoutSeconds?`	`number`	Wall-clock limit in seconds before the server kills the command.

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.

FromCheckpointOptions

Options for Sailbox.fromCheckpoint.

Extends

FromCheckpointRequest.ClientOptions

Properties

Property	Type	Description	Inherited from
`checkpointId`	`string`	The checkpoint to restore from.	`FromCheckpointRequest`.`checkpointId`
`client?`	`Client`	Use a specific client instead of the default (env) one.	`ClientOptions`.`client`
`name?`	`string`	Name for the new sailbox; defaults to the source box’s name.	`FromCheckpointRequest`.`name`
`timeoutSeconds?`	`number`	Restore timeout in whole seconds (positive); omitted uses the server default.	`FromCheckpointRequest`.`timeoutSeconds`

FromCheckpointRequest

The create-from-checkpoint request.

Extended by

FromCheckpointOptions

Properties

Property	Type	Description
`checkpointId`	`string`	The checkpoint to restore from.
`name?`	`string`	Name for the new sailbox; defaults to the source box’s name.
`timeoutSeconds?`	`number`	Restore timeout in whole seconds (positive); omitted uses the server default.

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.

ImageBuild

The state of a custom image build.

Extends

Omit<native.ImageBuild, "status">

Properties

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

ImageDefinition

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

Properties

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

ImageDefinitionStep

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

Properties

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

ImageSpec

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

Extends

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

Properties

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

IngressPortInput

A guest port to reserve for ingress at create time.

Extends

Omit<native.IngressPortInput, "protocol">

Properties

Property	Type	Description	Inherited from
`allowlist?`	`string`[]	Source addresses allowed to reach the port; empty allows all.	`Omit.allowlist`
`guestPort`	`number`	The in-guest port to expose (1-65535).	`Omit.guestPort`
`protocol`	`IngressProtocol`	`http` or `tcp`.	-

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.

ListSailboxesQuery

Filters for listing sailboxes.

Extends

Omit<native.ListSailboxesQuery, "status">

Properties

Property	Type	Description	Inherited from
`appId?`	`string`	Filter to one app by its id.	`Omit.appId`
`limit?`	`number`	Page size.	`Omit.limit`
`maxGuestSchemaVersion?`	`number`	Only sailboxes at or below this guest schema version.	`Omit.maxGuestSchemaVersion`
`offset?`	`number`	Page offset.	`Omit.offset`
`search?`	`string`	Substring filter on the sailbox name.	`Omit.search`
`status?`	`SailboxStatusFilter`	Filter by lifecycle status.	-

LocalDirInput

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

Properties

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

LocalFileInput

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

Properties

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

PackageInstall

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

Properties

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

ResolvedConfig

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

Extends

Omit<native.ResolvedConfig, "ingressScheme">

Properties

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

RunCommand

A shell command to run during the build.

Properties

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

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 handle becomes eligible for garbage collection, if bounded.	-
`sailboxId`	`string`	The sailbox the checkpoint was taken from.	`Omit.sailboxId`
`status`	`SailboxStatus`	-	-

SailboxHandle

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

Extends

Omit<native.SailboxHandle, "status">

Properties

Property	Type	Description	Inherited from
`name`	`string`	The sailbox name.	`Omit.name`
`sailboxId`	`string`	The sailbox id.	`Omit.sailboxId`
`status`	`SailboxStatus`	-	-

SailboxInfo

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

Extends

Omit<native.SailboxInfo, "status">

Properties

Property	Type	Description	Inherited from
`appId`	`string`	Identifier of the owning app.	`Omit.appId`
`appName`	`string`	Name of the owning app.	`Omit.appName`
`architecture`	`string`	CPU architecture (for example `arm64`).	`Omit.architecture`
`checkpointGeneration`	`number`	Monotonic checkpoint generation counter.	`Omit.checkpointGeneration`
`cpuRequestedVcpu`	`number`	Requested CPU, in vCPUs.	`Omit.cpuRequestedVcpu`
`cpuUsedVcpu`	`number`	Current CPU usage, in vCPUs.	`Omit.cpuUsedVcpu`
`createdAt`	`string`	When the sailbox was created (RFC 3339).	`Omit.createdAt`
`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 box is in an error state.	`Omit.errorMessage`
`guestSchemaVersion?`	`number`	Guest schema version; absent for boxes created before it was recorded (treat as the oldest possible version).	`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 box last started, if it ever has (RFC 3339).	`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`

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`

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`

ShellOptions

Options for Sailbox.shell.

Properties

Property	Type	Description
`cwd?`	`string`	Working directory for the session.
`shell?`	`string`	Login shell to run when no command is given (default: the guest’s `$SHELL`, else `/bin/bash`). Ignored when a command is given.
`term?`	`string`	`$TERM` for the remote pty (default: the local `$TERM`).
`timeoutSeconds?`	`number`	Wall-clock limit for the session in seconds; omit for no limit.

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 an in-guest agent upgrade.

Extends

Omit<native.UpgradeResult, "status">

Properties

Property	Type	Description	Inherited from
`applied`	`boolean`	True when applied immediately (running box); false when deferred to the next wake.	`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
`pollIntervalSeconds?`	`number`	Re-check cadence in seconds (default 1).
`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.

Type Aliases

BaseImage

BaseImage = "debian" | "devbox"

ImageArchitecture

ImageArchitecture = "amd64" | "arm64"

ImageBuildStatus

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

The status of a custom image build.

ImageBuildStep

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

One build step: exactly one operation.

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.

ListenerEndpoint

ListenerEndpoint = HttpEndpoint | TcpEndpoint

How to reach an exposed listener; discriminate on kind.

ListenerRouteStatus

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

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

Protocol

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

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

SailboxSize

SailboxSize = "s" | "m"

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.

Functions

defaultClient()

defaultClient(): Client

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

Returns

Client

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>

resolveConfig()

resolveConfig(): ResolvedConfig

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

Returns

ResolvedConfig

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

Python SDK reference Rust SDK reference

⌘I

​Classes

​ApiError

​Extends

​Constructors

Constructor

Parameters

Returns

Overrides

​Properties

​App

​Properties

​Methods

find()

Parameters

Returns

list()

Parameters

Returns

​BrokenPipeError

​Extends

​Constructors

Constructor

Parameters

Returns

Overrides

​Properties

​Client

​Methods

buildImageDefinition()

Parameters

Returns

buildSpecToReady()

Parameters

Returns

checkpointSailbox()

Parameters

Returns

createFromCheckpoint()

Parameters

Returns

createSailbox()

Parameters

Returns

deleteVolume()

Parameters

Returns

enableSsh()

Parameters

Returns

exec()

Parameters

Returns

exposeListener()

Parameters

Returns

findApp()

Parameters

Returns

getListener()

Parameters

Returns

getSailbox()

Parameters

Returns

getVolume()

Parameters

Returns

ingressAuthHeaders()

Parameters

Returns

isBuiltinBaseSpec()

Parameters

Returns

listApps()

Returns

listListeners()

Parameters

Returns

listSailboxes()

Parameters

Classes

ApiError

Extends

Constructors

Properties

App

Properties

Methods

BrokenPipeError

Extends

Constructors

Properties

Client

Methods

ExecProcess

Example

Properties

Accessors

Methods