> ## Documentation Index > Fetch the complete documentation index at: https://docs.sailresearch.com/llms.txt > Use this file to discover all available pages before exploring further. # TypeScript SDK reference > Complete API reference for the Sail TypeScript SDK. ## Classes ### ApiError A transient, retryable server-side API failure. #### Extends * [`SailError`](#sailerror) #### Constructors ##### Constructor > **new ApiError**(`message`): [`ApiError`](#apierror) ###### Parameters | Parameter | Type | | --------- | -------- | | `message` | `string` | ###### Returns [`ApiError`](#apierror) ###### Overrides [`SailError`](#sailerror).[`constructor`](#constructor-13) #### Properties | Property | Modifier | Type | Description | Inherited from | | ---------------------- | ---------- | -------- | -------------------------------------------------------- | -------------------------------------------- | | `code` | `readonly` | `string` | Stable, language-neutral error code (e.g. `"NotFound"`). | [`SailError`](#sailerror).[`code`](#code-13) | *** ### App An app: the billing/ownership scope a sailbox belongs to. Look one up (or mint it) with [App.find](#find), then pass it (or its [App.id](#id)) to [Sailbox.create](#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`](#app)> Find an app by name, optionally minting it if missing. ###### Parameters | Parameter | Type | | --------- | -------------------------------------------- | | `name` | `string` | | `options` | [`ClientOptions`](#clientoptions) & `object` | ###### Returns `Promise`\<[`App`](#app)> ##### list() > `static` **list**(`options?`): `Promise`\<[`App`](#app)\[]> Every app the current org owns, newest first. ###### Parameters | Parameter | Type | | --------- | --------------------------------- | | `options` | [`ClientOptions`](#clientoptions) | ###### Returns `Promise`\<[`App`](#app)\[]> *** ### BrokenPipeError A stream (e.g. exec stdin) was closed and can no longer be written. #### Extends * [`SailError`](#sailerror) #### Constructors ##### Constructor > **new BrokenPipeError**(`message`): [`BrokenPipeError`](#brokenpipeerror) ###### Parameters | Parameter | Type | | --------- | -------- | | `message` | `string` | ###### Returns [`BrokenPipeError`](#brokenpipeerror) ###### Overrides [`SailError`](#sailerror).[`constructor`](#constructor-13) #### Properties | Property | Modifier | Type | Description | Inherited from | | ------------------------ | ---------- | -------- | -------------------------------------------------------- | -------------------------------------------- | | `code` | `readonly` | `string` | Stable, language-neutral error code (e.g. `"NotFound"`). | [`SailError`](#sailerror).[`code`](#code-13) | *** ### 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](#sailbox), [App](#app), [Volume](#volume)) is built on top of it. Construct with [Client.fromEnv](#fromenv) or [Client.fromConfig](#fromconfig). #### Methods ##### buildImageDefinition() > **buildImageDefinition**(`def`, `timeoutSeconds`): `Promise`\<[`ImageSpec`](#imagespec)> Resolve an image definition and build it to ready, returning the content-addressed [ImageSpec](#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`](#imagedefinition) | | `timeoutSeconds` | `number` | ###### Returns `Promise`\<[`ImageSpec`](#imagespec)> ##### buildSpecToReady() > **buildSpecToReady**(`spec`, `timeoutSeconds`): `Promise`\<[`ImageBuild`](#imagebuild-1)> Build an already-resolved spec to ready (submit + poll), bounded by `timeoutSeconds`. ###### Parameters | Parameter | Type | | ---------------- | ------------------------- | | `spec` | [`ImageSpec`](#imagespec) | | `timeoutSeconds` | `number` | ###### Returns `Promise`\<[`ImageBuild`](#imagebuild-1)> ##### checkpointSailbox() > **checkpointSailbox**(`sailboxId`, `options?`): `Promise`\<[`SailboxCheckpoint`](#sailboxcheckpoint-1)> 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`](#checkpointoptions) | ###### Returns `Promise`\<[`SailboxCheckpoint`](#sailboxcheckpoint-1)> ##### createFromCheckpoint() > **createFromCheckpoint**(`params`): `Promise`\<[`SailboxHandle`](#sailboxhandle)> Create a new sailbox from a checkpoint. ###### Parameters | Parameter | Type | | --------- | ------------------------------------------------- | | `params` | [`FromCheckpointRequest`](#fromcheckpointrequest) | ###### Returns `Promise`\<[`SailboxHandle`](#sailboxhandle)> ##### createSailbox() > **createSailbox**(`req`, `timeoutSeconds?`): `Promise`\<[`SailboxHandle`](#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`](#createsailboxrequest) | `undefined` | | `timeoutSeconds` | `number` | `600` | ###### Returns `Promise`\<[`SailboxHandle`](#sailboxhandle)> ##### deleteVolume() > **deleteVolume**(`volumeId`, `allowMissing?`): `Promise`\<[`VolumeInfo`](#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`](#volumeinfo) | `null`> ##### enableSsh() > **enableSsh**(`sailboxId`, `options?`): `Promise`\<[`SshEndpoint`](#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](#timeouterror) if it is not within `timeoutSeconds`; with `wait: false`, skips the probe and resolves `null`. ###### Parameters | Parameter | Type | | ----------- | --------------------------------------- | | `sailboxId` | `string` | | `options` | [`EnableSshOptions`](#enablesshoptions) | ###### Returns `Promise`\<[`SshEndpoint`](#sshendpoint) | `null`> ##### exec() > **exec**(`sailboxId`, `command`, `options?`): `Promise`\<[`ExecProcess`](#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](#execoptions)). ###### Parameters | Parameter | Type | | ----------- | ----------------------------- | | `sailboxId` | `string` | | `command` | `string` \| `string`\[] | | `options` | [`ExecOptions`](#execoptions) | ###### Returns `Promise`\<[`ExecProcess`](#execprocess)> ##### exposeListener() > **exposeListener**(`sailboxId`, `guestPort`, `protocol?`, `allowlist?`): `Promise`\<[`Listener`](#listener-1)> 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`](#ingressprotocol) | `"http"` | | `allowlist` | `string`\[] | `[]` | ###### Returns `Promise`\<[`Listener`](#listener-1)> ##### findApp() > **findApp**(`name`, `mintIfMissing?`): `Promise`\<[`AppInfo`](#appinfo)> Find an app by name, optionally minting it. ###### Parameters | Parameter | Type | Default value | | --------------- | --------- | ------------- | | `name` | `string` | `undefined` | | `mintIfMissing` | `boolean` | `false` | ###### Returns `Promise`\<[`AppInfo`](#appinfo)> ##### getListener() > **getListener**(`sailboxId`, `guestPort`): `Promise`\<[`Listener`](#listener-1)> Fetch one listener by guest port without waking the box. ###### Parameters | Parameter | Type | | ----------- | -------- | | `sailboxId` | `string` | | `guestPort` | `number` | ###### Returns `Promise`\<[`Listener`](#listener-1)> ##### getSailbox() > **getSailbox**(`sailboxId`): `Promise`\<[`SailboxInfo`](#sailboxinfo)> Fetch one sailbox by id. ###### Parameters | Parameter | Type | | ----------- | -------- | | `sailboxId` | `string` | ###### Returns `Promise`\<[`SailboxInfo`](#sailboxinfo)> ##### getVolume() > **getVolume**(`name`, `mintIfMissing?`): `Promise`\<[`VolumeInfo`](#volumeinfo)> Look up (optionally minting) an NFS volume by name. ###### Parameters | Parameter | Type | Default value | | --------------- | --------- | ------------- | | `name` | `string` | `undefined` | | `mintIfMissing` | `boolean` | `false` | ###### Returns `Promise`\<[`VolumeInfo`](#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`](#imagespec) | ###### Returns `boolean` ##### listApps() > **listApps**(): `Promise`\<[`AppInfo`](#appinfo)\[]> Every app the current org owns, newest first. ###### Returns `Promise`\<[`AppInfo`](#appinfo)\[]> ##### listListeners() > **listListeners**(`sailboxId`): `Promise`\<[`Listener`](#listener-1)\[]> List a sailbox's listeners without waking it. ###### Parameters | Parameter | Type | | ----------- | -------- | | `sailboxId` | `string` | ###### Returns `Promise`\<[`Listener`](#listener-1)\[]> ##### listSailboxes() > **listSailboxes**(`params?`): `Promise`\<[`SailboxInfoPage`](#sailboxinfopage)> List one page of sailboxes in the current org. ###### Parameters | Parameter | Type | | --------- | ------------------------------------------- | | `params` | [`ListSailboxesQuery`](#listsailboxesquery) | ###### Returns `Promise`\<[`SailboxInfoPage`](#sailboxinfopage)> ##### listVolumes() > **listVolumes**(`maxObjects?`): `Promise`\<[`VolumeInfo`](#volumeinfo)\[]> List NFS volumes in the current org. ###### Parameters | Parameter | Type | | ------------- | -------- | | `maxObjects?` | `number` | ###### Returns `Promise`\<[`VolumeInfo`](#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`](#filestream)> Open a streaming read of a guest file. ###### Parameters | Parameter | Type | | ----------- | -------- | | `sailboxId` | `string` | | `path` | `string` | ###### Returns `Promise`\<[`FileStream`](#filestream)> ##### resolveImage() > **resolveImage**(`def`): `Promise`\<[`ImageSpec`](#imagespec)> Resolve an image definition into a content-addressed [ImageSpec](#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`](#imagedefinition) | ###### Returns `Promise`\<[`ImageSpec`](#imagespec)> ##### resumeSailbox() > **resumeSailbox**(`sailboxId`): `Promise`\<[`SailboxHandle`](#sailboxhandle)> Resume a paused or sleeping sailbox. ###### Parameters | Parameter | Type | | ----------- | -------- | | `sailboxId` | `string` | ###### Returns `Promise`\<[`SailboxHandle`](#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`](#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`](#upgraderesult)> Upgrade a sailbox's in-guest agent (now if running, else at next wake). ###### Parameters | Parameter | Type | | ----------- | -------- | | `sailboxId` | `string` | ###### Returns `Promise`\<[`UpgradeResult`](#upgraderesult)> ##### waitForListener() > **waitForListener**(`sailboxId`, `guestPort`, `timeoutSeconds`, `pollIntervalSeconds`): `Promise`\<[`Listener`](#listener-1)> Block until the listener on `guestPort` is reachable end to end and return it, throwing [TimeoutError](#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`](#listener-1)> ##### writeStream() > **writeStream**(`sailboxId`, `path`, `options?`): `Promise`\<[`FileWriter`](#filewriter)> Open a streaming upload to a guest file. ###### Parameters | Parameter | Type | | ----------- | ------------------------------- | | `sailboxId` | `string` | | `path` | `string` | | `options` | [`WriteOptions`](#writeoptions) | ###### Returns `Promise`\<[`FileWriter`](#filewriter)> ##### fromConfig() > `static` **fromConfig**(`config`): [`Client`](#client) Build a client from an explicit [ClientConfig](#clientconfig). ###### Parameters | Parameter | Type | | --------- | ------------------------------- | | `config` | [`ClientConfig`](#clientconfig) | ###### Returns [`Client`](#client) ##### fromEnv() > `static` **fromEnv**(): [`Client`](#client) Build a client from the environment (`SAIL_API_KEY`, ...). ###### Returns [`Client`](#client) *** ### ExecProcess A live command running in a sailbox. Stream [stdout](#stdout)/[stderr](#stderr), write to [writeStdin](#writestdin), and [wait](#wait) for the result. Not killed on GC; call [close](#close) to detach, or [cancel](#cancel) to stop the command. #### Example ```ts theme={null} 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`](#execstream) | Stderr as an async iterable of decoded chunks. | | `stdout` | `readonly` | [`ExecStream`](#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`](#execstream) Alias for [stdout](#stdout): under a pty the two output streams merge onto stdout, and `output` names that merged terminal stream. ###### Returns [`ExecStream`](#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`](#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](#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`](#execresult)> Await the authoritative result (exit code, buffered output, flags). ###### Returns `Promise`\<[`ExecResult`](#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 ```ts theme={null} 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`](#sailerror) #### Constructors ##### Constructor > **new FileNotFoundError**(`message`): [`FileNotFoundError`](#filenotfounderror) ###### Parameters | Parameter | Type | | --------- | -------- | | `message` | `string` | ###### Returns [`FileNotFoundError`](#filenotfounderror) ###### Overrides [`SailError`](#sailerror).[`constructor`](#constructor-13) #### Properties | Property | Modifier | Type | Description | Inherited from | | ------------------------ | ---------- | -------- | -------------------------------------------------------- | -------------------------------------------- | | `code` | `readonly` | `string` | Stable, language-neutral error code (e.g. `"NotFound"`). | [`SailError`](#sailerror).[`code`](#code-13) | *** ### FileStream An async-iterable download of a guest file. Chunks are `Buffer`s; 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](#close-1). #### 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](#write), then confirm with [finish](#finish); only `finish` commits the write. A writer that goes away without finishing ([abort](#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](#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](#create), or via [toSpec](#tospec)), so chaining stays synchronous. #### Example ```ts theme={null} 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`](#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`](#addlocaldiroptions) | ###### Returns [`Image`](#image) ##### addLocalFile() > **addLocalFile**(`localPath`, `remotePath`, `options?`): [`Image`](#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`](#addlocalfileoptions) | ###### Returns [`Image`](#image) ##### aptInstall() > **aptInstall**(...`packages`): [`Image`](#image) Install system packages with apt. ###### Parameters | Parameter | Type | | ------------- | ----------- | | ...`packages` | `string`\[] | ###### Returns [`Image`](#image) ##### build() > **build**(`options?`): `Promise`\<[`ImageSpec`](#imagespec)> Upload any local files and build the image, waiting until it is ready. Returns the resolved [ImageSpec](#imagespec). [Sailbox.create](#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`](#client); `timeoutSeconds?`: `number`; } | | `options.client?` | [`Client`](#client) | | `options.timeoutSeconds?` | `number` | ###### Returns `Promise`\<[`ImageSpec`](#imagespec)> ##### env() > **env**(`env`): [`Image`](#image) Bake environment variables into the image (keys are trimmed). ###### Parameters | Parameter | Type | | --------- | ----------------------------- | | `env` | `Record`\<`string`, `string`> | ###### Returns [`Image`](#image) ##### pipInstall() > **pipInstall**(...`packages`): [`Image`](#image) Install Python packages with pip. ###### Parameters | Parameter | Type | | ------------- | ----------- | | ...`packages` | `string`\[] | ###### Returns [`Image`](#image) ##### runCommand() > **runCommand**(`command`): [`Image`](#image) Run a shell command during the build. ###### Parameters | Parameter | Type | | --------- | -------- | | `command` | `string` | ###### Returns [`Image`](#image) ##### toSpec() > **toSpec**(`client?`): `Promise`\<[`ImageSpec`](#imagespec)> Resolve to an [ImageSpec](#imagespec): walks local files/dirs (honoring gitignore), hashes them, and uploads their content via `client` (defaults to the env client). [Sailbox.create](#create) calls this for you; use it directly only if you need the raw spec. ###### Parameters | Parameter | Type | | --------- | ------------------- | | `client?` | [`Client`](#client) | ###### Returns `Promise`\<[`ImageSpec`](#imagespec)> ##### debian() > `static` **debian**(`architecture?`): [`Image`](#image) A Debian base image (defaults to arm64). ###### Parameters | Parameter | Type | Default value | | -------------- | ----------------------------------------- | ------------- | | `architecture` | [`ImageArchitecture`](#imagearchitecture) | `"arm64"` | ###### Returns [`Image`](#image) ##### devbox() > `static` **devbox**(`architecture?`): [`Image`](#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](#debian) to customize. ###### Parameters | Parameter | Type | Default value | | -------------- | ----------------------------------------- | ------------- | | `architecture` | [`ImageArchitecture`](#imagearchitecture) | `"arm64"` | ###### Returns [`Image`](#image) *** ### ImageBuildError A custom image could not be built or its local content could not be uploaded. #### Extends * [`SailError`](#sailerror) #### Constructors ##### Constructor > **new ImageBuildError**(`message`): [`ImageBuildError`](#imagebuilderror) ###### Parameters | Parameter | Type | | --------- | -------- | | `message` | `string` | ###### Returns [`ImageBuildError`](#imagebuilderror) ###### Overrides [`SailError`](#sailerror).[`constructor`](#constructor-13) #### Properties | Property | Modifier | Type | Description | Inherited from | | ------------------------ | ---------- | -------- | -------------------------------------------------------- | -------------------------------------------- | | `code` | `readonly` | `string` | Stable, language-neutral error code (e.g. `"NotFound"`). | [`SailError`](#sailerror).[`code`](#code-13) | *** ### InternalError An unexpected internal SDK/core failure. #### Extends * [`SailError`](#sailerror) #### Constructors ##### Constructor > **new InternalError**(`message`): [`InternalError`](#internalerror) ###### Parameters | Parameter | Type | | --------- | -------- | | `message` | `string` | ###### Returns [`InternalError`](#internalerror) ###### Overrides [`SailError`](#sailerror).[`constructor`](#constructor-13) #### Properties | Property | Modifier | Type | Description | Inherited from | | ------------------------ | ---------- | -------- | -------------------------------------------------------- | -------------------------------------------- | | `code` | `readonly` | `string` | Stable, language-neutral error code (e.g. `"NotFound"`). | [`SailError`](#sailerror).[`code`](#code-13) | *** ### InvalidArgumentError Invalid arguments or configuration (bad request, missing/invalid API key). #### Extends * [`SailError`](#sailerror) #### Constructors ##### Constructor > **new InvalidArgumentError**(`message`): [`InvalidArgumentError`](#invalidargumenterror) ###### Parameters | Parameter | Type | | --------- | -------- | | `message` | `string` | ###### Returns [`InvalidArgumentError`](#invalidargumenterror) ###### Overrides [`SailError`](#sailerror).[`constructor`](#constructor-13) #### Properties | Property | Modifier | Type | Description | Inherited from | | ------------------------ | ---------- | -------- | -------------------------------------------------------- | -------------------------------------------- | | `code` | `readonly` | `string` | Stable, language-neutral error code (e.g. `"NotFound"`). | [`SailError`](#sailerror).[`code`](#code-13) | *** ### NotFoundError The sailbox, volume, or other resource does not exist (or is another org's). #### Extends * [`SailError`](#sailerror) #### Constructors ##### Constructor > **new NotFoundError**(`message`): [`NotFoundError`](#notfounderror) ###### Parameters | Parameter | Type | | --------- | -------- | | `message` | `string` | ###### Returns [`NotFoundError`](#notfounderror) ###### Overrides [`SailError`](#sailerror).[`constructor`](#constructor-13) #### Properties | Property | Modifier | Type | Description | Inherited from | | ------------------------ | ---------- | -------- | -------------------------------------------------------- | -------------------------------------------- | | `code` | `readonly` | `string` | Stable, language-neutral error code (e.g. `"NotFound"`). | [`SailError`](#sailerror).[`code`](#code-13) | *** ### PermissionDeniedError The credential is not permitted to perform the operation. #### Extends * [`SailError`](#sailerror) #### Constructors ##### Constructor > **new PermissionDeniedError**(`message`): [`PermissionDeniedError`](#permissiondeniederror) ###### Parameters | Parameter | Type | | --------- | -------- | | `message` | `string` | ###### Returns [`PermissionDeniedError`](#permissiondeniederror) ###### Overrides [`SailError`](#sailerror).[`constructor`](#constructor-13) #### Properties | Property | Modifier | Type | Description | Inherited from | | ------------------------ | ---------- | -------- | -------------------------------------------------------- | -------------------------------------------- | | `code` | `readonly` | `string` | Stable, language-neutral error code (e.g. `"NotFound"`). | [`SailError`](#sailerror).[`code`](#code-13) | *** ### Sailbox A sandbox (sailbox): the primary object agent harnesses work with. Create one with [Sailbox.create](#create), run commands with [exec](#exec-1), move files with [writeStream](#writestream-1)/[readStream](#readstream-1), expose ports with [expose](#expose), and manage its lifecycle. The statics use a default env-configured client unless you pass one. #### Example ```ts theme={null} 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`](#client) The underlying [Client](#client). ###### Returns [`Client`](#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`](#sailboxstatus-1) The lifecycle status as of the call that produced this handle (updated by lifecycle calls on this instance). Use [Sailbox.get](#get) for a fresh snapshot. ###### Returns [`SailboxStatus`](#sailboxstatus-1) ##### 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`](#sailboxcheckpoint-1)> Take a checkpoint of this sailbox. The returned handle carries `expiresAt`, when it becomes eligible for garbage collection. ###### Parameters | Parameter | Type | | --------- | ----------------------------------------- | | `options` | [`CheckpointOptions`](#checkpointoptions) | ###### Returns `Promise`\<[`SailboxCheckpoint`](#sailboxcheckpoint-1)> ##### enableSsh() > **enableSsh**(`options?`): `Promise`\<[`SshEndpoint`](#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](#timeouterror) if it is not within `timeoutSeconds`; with `wait: false`, skips the probe and resolves `null`. ###### Parameters | Parameter | Type | | --------- | --------------------------------------- | | `options` | [`EnableSshOptions`](#enablesshoptions) | ###### Returns `Promise`\<[`SshEndpoint`](#sshendpoint) | `null`> ##### exec() > **exec**(`command`, `options?`): `Promise`\<[`ExecProcess`](#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](#execoptions)). ###### Parameters | Parameter | Type | | ---------- | ----------------------------- | | `command` | `string` \| `string`\[] | | `options?` | [`ExecOptions`](#execoptions) | ###### Returns `Promise`\<[`ExecProcess`](#execprocess)> ##### expose() > **expose**(`guestPort`, `protocol?`, `allowlist?`): `Promise`\<[`Listener`](#listener-1)> 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](#waitforlistener-1) confirms the route is live. ###### Parameters | Parameter | Type | Default value | | ----------- | ------------------------------------- | ------------- | | `guestPort` | `number` | `undefined` | | `protocol` | [`IngressProtocol`](#ingressprotocol) | `"http"` | | `allowlist` | `string`\[] | `[]` | ###### Returns `Promise`\<[`Listener`](#listener-1)> ##### 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`](#listener-1)> Fetch one listener by guest port without waking the box. ###### Parameters | Parameter | Type | | ----------- | -------- | | `guestPort` | `number` | ###### Returns `Promise`\<[`Listener`](#listener-1)> ##### listeners() > **listeners**(): `Promise`\<[`Listener`](#listener-1)\[]> List this sailbox's listeners without waking it. ###### Returns `Promise`\<[`Listener`](#listener-1)\[]> ##### 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](#readstream-1)). ###### Parameters | Parameter | Type | | --------- | -------- | | `path` | `string` | ###### Returns `Promise`\<`Buffer`\<`ArrayBufferLike`>> ##### readStream() > **readStream**(`path`): `Promise`\<[`FileStream`](#filestream)> Open a streaming read of a guest file. ###### Parameters | Parameter | Type | | --------- | -------- | | `path` | `string` | ###### Returns `Promise`\<[`FileStream`](#filestream)> ##### resume() > **resume**(): `Promise`\<`void`> Resume this sailbox (updates [status](#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`](#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](#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`](#upgraderesult)> Upgrade this sailbox's in-guest agent. ###### Returns `Promise`\<[`UpgradeResult`](#upgraderesult)> ##### waitForListener() > **waitForListener**(`guestPort`, `options?`): `Promise`\<[`Listener`](#listener-1)> Block until the listener on `guestPort` is reachable end to end and return it, or throw [TimeoutError](#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`](#waitforlisteneroptions) | ###### Returns `Promise`\<[`Listener`](#listener-1)> ##### 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](#writestream-1); pass `createParents: false` to opt out). ###### Parameters | Parameter | Type | | ---------- | ---------------------------------------------------------------------------- | | `path` | `string` | | `data` | `string` \| `Buffer`\<`ArrayBufferLike`> \| `Uint8Array`\<`ArrayBufferLike`> | | `options?` | [`WriteOptions`](#writeoptions) | ###### Returns `Promise`\<`void`> ##### writeStream() > **writeStream**(`path`, `options?`): `Promise`\<[`FileWriter`](#filewriter)> Open a streaming upload to a guest file. ###### Parameters | Parameter | Type | | ---------- | ------------------------------- | | `path` | `string` | | `options?` | [`WriteOptions`](#writeoptions) | ###### Returns `Promise`\<[`FileWriter`](#filewriter)> ##### create() > `static` **create**(`options`): `Promise`\<[`Sailbox`](#sailbox)> Create a new sailbox. ###### Parameters | Parameter | Type | | --------- | ----------------------------------------------- | | `options` | [`CreateSailboxOptions`](#createsailboxoptions) | ###### Returns `Promise`\<[`Sailbox`](#sailbox)> ##### fromCheckpoint() > `static` **fromCheckpoint**(`options`): `Promise`\<[`Sailbox`](#sailbox)> Create a new sailbox from a checkpoint. ###### Parameters | Parameter | Type | | --------- | ------------------------------------------------- | | `options` | [`FromCheckpointOptions`](#fromcheckpointoptions) | ###### Returns `Promise`\<[`Sailbox`](#sailbox)> ##### get() > `static` **get**(`sailboxId`, `options?`): `Promise`\<[`Sailbox`](#sailbox)> Fetch an existing sailbox by id. ###### Parameters | Parameter | Type | | ----------- | --------------------------------- | | `sailboxId` | `string` | | `options` | [`ClientOptions`](#clientoptions) | ###### Returns `Promise`\<[`Sailbox`](#sailbox)> ##### list() > `static` **list**(`params?`, `options?`): `Promise`\<[`Sailbox`](#sailbox)\[]> List one page of sailboxes as [Sailbox](#sailbox) instances. ###### Parameters | Parameter | Type | | --------- | ------------------------------------------- | | `params` | [`ListSailboxesQuery`](#listsailboxesquery) | | `options` | [`ClientOptions`](#clientoptions) | ###### Returns `Promise`\<[`Sailbox`](#sailbox)\[]> ##### listPage() > `static` **listPage**(`params?`, `options?`): `Promise`\<[`SailboxPage`](#sailboxpage)> Like [list](#list-1) but also returns the pagination envelope (`total`/`hasMore`) for paging through large result sets. ###### Parameters | Parameter | Type | | --------- | ------------------------------------------- | | `params` | [`ListSailboxesQuery`](#listsailboxesquery) | | `options` | [`ClientOptions`](#clientoptions) | ###### Returns `Promise`\<[`SailboxPage`](#sailboxpage)> *** ### SailboxCreationError A sailbox could not be created (provisioning failed). #### Extends * [`SailError`](#sailerror) #### Constructors ##### Constructor > **new SailboxCreationError**(`message`): [`SailboxCreationError`](#sailboxcreationerror) ###### Parameters | Parameter | Type | | --------- | -------- | | `message` | `string` | ###### Returns [`SailboxCreationError`](#sailboxcreationerror) ###### Overrides [`SailError`](#sailerror).[`constructor`](#constructor-13) #### Properties | Property | Modifier | Type | Description | Inherited from | | ------------------------ | ---------- | -------- | -------------------------------------------------------- | -------------------------------------------- | | `code` | `readonly` | `string` | Stable, language-neutral error code (e.g. `"NotFound"`). | [`SailError`](#sailerror).[`code`](#code-13) | *** ### SailboxExecRequestNotFoundError The exec request could not be found (for example after the sailbox moved machines). #### Extends * [`SailboxExecutionError`](#sailboxexecutionerror) #### Constructors ##### Constructor > **new SailboxExecRequestNotFoundError**(`message`): [`SailboxExecRequestNotFoundError`](#sailboxexecrequestnotfounderror) ###### Parameters | Parameter | Type | | --------- | -------- | | `message` | `string` | ###### Returns [`SailboxExecRequestNotFoundError`](#sailboxexecrequestnotfounderror) ###### Overrides [`SailboxExecutionError`](#sailboxexecutionerror).[`constructor`](#constructor-10) #### Properties | Property | Modifier | Type | Description | Inherited from | | ------------------------ | ---------- | -------- | -------------------------------------------------------- | -------------------------------------------------------------------- | | `code` | `readonly` | `string` | Stable, language-neutral error code (e.g. `"NotFound"`). | [`SailboxExecutionError`](#sailboxexecutionerror).[`code`](#code-10) | *** ### SailboxExecutionError Base class for failures during an exec. #### Extends * [`SailError`](#sailerror) #### Extended by * [`SailboxTerminatedError`](#sailboxterminatederror) * [`SailboxExecRequestNotFoundError`](#sailboxexecrequestnotfounderror) * [`SailboxWorkerLostError`](#sailboxworkerlosterror) #### Constructors ##### Constructor > **new SailboxExecutionError**(`message`, `code?`): [`SailboxExecutionError`](#sailboxexecutionerror) ###### Parameters | Parameter | Type | Default value | | --------- | -------- | ------------------------- | | `message` | `string` | `undefined` | | `code` | `string` | `"SailboxExecutionError"` | ###### Returns [`SailboxExecutionError`](#sailboxexecutionerror) ###### Overrides [`SailError`](#sailerror).[`constructor`](#constructor-13) #### Properties | Property | Modifier | Type | Description | Inherited from | | ------------------------- | ---------- | -------- | -------------------------------------------------------- | -------------------------------------------- | | `code` | `readonly` | `string` | Stable, language-neutral error code (e.g. `"NotFound"`). | [`SailError`](#sailerror).[`code`](#code-13) | *** ### SailboxTerminatedError The sailbox was terminated while an exec was in flight. #### Extends * [`SailboxExecutionError`](#sailboxexecutionerror) #### Constructors ##### Constructor > **new SailboxTerminatedError**(`message`): [`SailboxTerminatedError`](#sailboxterminatederror) ###### Parameters | Parameter | Type | | --------- | -------- | | `message` | `string` | ###### Returns [`SailboxTerminatedError`](#sailboxterminatederror) ###### Overrides [`SailboxExecutionError`](#sailboxexecutionerror).[`constructor`](#constructor-10) #### Properties | Property | Modifier | Type | Description | Inherited from | | ------------------------- | ---------- | -------- | -------------------------------------------------------- | -------------------------------------------------------------------- | | `code` | `readonly` | `string` | Stable, language-neutral error code (e.g. `"NotFound"`). | [`SailboxExecutionError`](#sailboxexecutionerror).[`code`](#code-10) | *** ### SailboxWorkerLostError The machine hosting the sailbox was lost while an exec was in flight. #### Extends * [`SailboxExecutionError`](#sailboxexecutionerror) #### Constructors ##### Constructor > **new SailboxWorkerLostError**(`message`): [`SailboxWorkerLostError`](#sailboxworkerlosterror) ###### Parameters | Parameter | Type | | --------- | -------- | | `message` | `string` | ###### Returns [`SailboxWorkerLostError`](#sailboxworkerlosterror) ###### Overrides [`SailboxExecutionError`](#sailboxexecutionerror).[`constructor`](#constructor-10) #### Properties | Property | Modifier | Type | Description | Inherited from | | ------------------------- | ---------- | -------- | -------------------------------------------------------- | -------------------------------------------------------------------- | | `code` | `readonly` | `string` | Stable, language-neutral error code (e.g. `"NotFound"`). | [`SailboxExecutionError`](#sailboxexecutionerror).[`code`](#code-10) | *** ### SailError Base class for every error surfaced by the SDK. #### Extends * `Error` #### Extended by * [`InvalidArgumentError`](#invalidargumenterror) * [`InternalError`](#internalerror) * [`NotFoundError`](#notfounderror) * [`PermissionDeniedError`](#permissiondeniederror) * [`FileNotFoundError`](#filenotfounderror) * [`BrokenPipeError`](#brokenpipeerror) * [`TimeoutError`](#timeouterror) * [`TransportError`](#transporterror) * [`ApiError`](#apierror) * [`SailboxCreationError`](#sailboxcreationerror) * [`ImageBuildError`](#imagebuilderror) * [`SailboxExecutionError`](#sailboxexecutionerror) #### Constructors ##### Constructor > **new SailError**(`message`, `code?`): [`SailError`](#sailerror) ###### Parameters | Parameter | Type | Default value | | --------- | -------- | ------------- | | `message` | `string` | `undefined` | | `code` | `string` | `"SailError"` | ###### Returns [`SailError`](#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`](#sailerror) #### Constructors ##### Constructor > **new TimeoutError**(`message`): [`TimeoutError`](#timeouterror) ###### Parameters | Parameter | Type | | --------- | -------- | | `message` | `string` | ###### Returns [`TimeoutError`](#timeouterror) ###### Overrides [`SailError`](#sailerror).[`constructor`](#constructor-13) #### Properties | Property | Modifier | Type | Description | Inherited from | | ------------------------- | ---------- | -------- | -------------------------------------------------------- | -------------------------------------------- | | `code` | `readonly` | `string` | Stable, language-neutral error code (e.g. `"NotFound"`). | [`SailError`](#sailerror).[`code`](#code-13) | *** ### TransportError A network/connection transport failure. #### Extends * [`SailError`](#sailerror) #### Constructors ##### Constructor > **new TransportError**(`message`): [`TransportError`](#transporterror) ###### Parameters | Parameter | Type | | --------- | -------- | | `message` | `string` | ###### Returns [`TransportError`](#transporterror) ###### Overrides [`SailError`](#sailerror).[`constructor`](#constructor-13) #### Properties | Property | Modifier | Type | Description | Inherited from | | ------------------------- | ---------- | -------- | -------------------------------------------------------- | -------------------------------------------- | | `code` | `readonly` | `string` | Stable, language-neutral error code (e.g. `"NotFound"`). | [`SailError`](#sailerror).[`code`](#code-13) | *** ### Volume A managed NFS volume that can be mounted into sailboxes. Look one up (or mint it) with [Volume.find](#find-1), then pass it (or its [Volume.id](#id-1)) 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](#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`](#volume)> Look up an NFS volume by name, optionally minting it if missing. ###### Parameters | Parameter | Type | | --------- | -------------------------------------------- | | `name` | `string` | | `options` | [`ClientOptions`](#clientoptions) & `object` | ###### Returns `Promise`\<[`Volume`](#volume)> ##### fromMount() > `static` **fromMount**(`path`): [`Volume`](#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`](#volume) ##### list() > `static` **list**(`options?`): `Promise`\<[`Volume`](#volume)\[]> List NFS volumes in the current org. ###### Parameters | Parameter | Type | | --------- | -------------------------------------------- | | `options` | [`ClientOptions`](#clientoptions) & `object` | ###### Returns `Promise`\<[`Volume`](#volume)\[]> ## Interfaces ### AddLocalDir A tree of local files copied into the image. #### Properties | Property | Type | Description | | ----------------------------------- | ---------------------------------------- | ------------------------------------------ | | `files?` | [`AddLocalDirFile`](#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](#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](#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](#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](#client) to use. #### Extended by * [`CreateSailboxOptions`](#createsailboxoptions) * [`FromCheckpointOptions`](#fromcheckpointoptions) #### Properties | Property | Type | Description | | ----------------------------- | ------------------- | ------------------------------------------------------- | | `client?` | [`Client`](#client) | Use a specific client instead of the default (env) one. | *** ### CreateSailboxOptions Options for [Sailbox.create](#create): the create request plus a per-attempt timeout and an optional explicit client. `image` defaults to a Debian base. #### Extends * `Omit`\<[`CreateSailboxRequest`](#createsailboxrequest), `"image"` | `"appId"` | `"volumeMounts"` | `"ingressPorts"`>.[`ClientOptions`](#clientoptions) #### Properties | Property | Type | Description | Overrides | Inherited from | | --------------------------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ----------------------------------------------------------------- | | `app` | `string` \| [`App`](#app) | The owning app, or its id. | - | - | | `autosleepTimeoutMinutes?` | `number` | Idle minutes (1-1440) after which Sail may sleep the box. | - | `Omit.autosleepTimeoutMinutes` | | `client?` | [`Client`](#client) | Use a specific client instead of the default (env) one. | - | [`ClientOptions`](#clientoptions).[`client`](#client-2) | | `diskGib?` | `number` | Disk size in whole GiB within the size's range; the size's default when omitted. | - | `Omit.diskGib` | | `image?` | [`ImageSpec`](#imagespec) \| [`Image`](#image) | Image spec, or an [Image](#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`](#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`](#sailboxsize) | Resource size; `"m"` when omitted. | - | [`CreateSailboxRequest`](#createsailboxrequest).[`size`](#size-1) | | `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](#enablessh-1) 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`](#volume)> | Shared volumes to mount, mapping an absolute guest path to a [Volume](#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`](#imagespec) | Image to boot; defaults to a plain Debian base when omitted. | - | | `ingressPorts?` | [`IngressPortInput`](#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`](#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`](#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](#fromcheckpoint). #### Extends * [`FromCheckpointRequest`](#fromcheckpointrequest).[`ClientOptions`](#clientoptions) #### Properties | Property | Type | Description | Inherited from | | --------------------------------------------- | ------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | `checkpointId` | `string` | The checkpoint to restore from. | [`FromCheckpointRequest`](#fromcheckpointrequest).[`checkpointId`](#checkpointid-1) | | `client?` | [`Client`](#client) | Use a specific client instead of the default (env) one. | [`ClientOptions`](#clientoptions).[`client`](#client-2) | | `name?` | `string` | Name for the new sailbox; defaults to the source box's name. | [`FromCheckpointRequest`](#fromcheckpointrequest).[`name`](#name-8) | | `timeoutSeconds?` | `number` | Restore timeout in whole seconds (positive); omitted uses the server default. | [`FromCheckpointRequest`](#fromcheckpointrequest).[`timeoutSeconds`](#timeoutseconds-4) | *** ### FromCheckpointRequest The create-from-checkpoint request. #### Extended by * [`FromCheckpointOptions`](#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`](#imagebuildstatus-1) | - | - | *** ### 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`](#imagedefinitionstep)\[] | Ordered build steps. | *** ### ImageDefinitionStep One image-definition step. Exactly one of the fields must be set. #### Properties | Property | Type | Description | | ----------------------------------------- | ----------------------------------- | ------------------------------------------- | | `addLocalDir?` | [`LocalDirInput`](#localdirinput) | Bake a local directory tree into the image. | | `addLocalFile?` | [`LocalFileInput`](#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`](#imagearchitecture) | Target CPU architecture; unset lets the backend choose. | - | | `base?` | [`BaseImage`](#baseimage) | Base image to build on. | - | | `buildSteps?` | [`ImageBuildStep`](#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`](#ingressprotocol) | `http` or `tcp`. | - | *** ### Listener An exposed guest port and how to reach it. #### Properties | Property | Type | Description | | ------------------------------------ | ----------------------------------------------- | ------------------------------------------------------------------ | | `endpoint?` | [`ListenerEndpoint`](#listenerendpoint-1) | How to reach the port; `undefined` until the listener is routable. | | `guestPort` | `number` | The in-guest port traffic is forwarded to. | | `protocol` | [`Protocol`](#protocol-2) | Wire protocol exposed. | | `routeStatus` | [`ListenerRouteStatus`](#listenerroutestatus-1) | 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`](#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`](#ingressscheme-1) | - | - | | `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`](#sailboxstatus-1) | - | - | *** ### 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`](#sailboxstatus-1) | - | - | *** ### 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`](#sailboxstatus-1) | - | - | | `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`](#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](#sailbox) instances plus the pagination envelope. #### Extends * `Omit`\<[`SailboxInfoPage`](#sailboxinfopage), `"items"`> #### Properties | Property | Type | Description | Inherited from | | ------------------------------ | ------------------------ | ------------------------------------------ | -------------- | | `hasMore` | `boolean` | Whether more results exist past this page. | `Omit.hasMore` | | `items` | [`Sailbox`](#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](#shell-1). #### 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`](#sailboxstatus-1) | - | - | *** ### 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](#waitforlistener-1). #### 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`](#packageinstall); } | \{ `pipInstall`: [`PackageInstall`](#packageinstall); } | \{ `runCommand`: [`RunCommand`](#runcommand-2); } | \{ `addLocalFile`: [`AddLocalFile`](#addlocalfile-1); } | \{ `addLocalDir`: [`AddLocalDir`](#addlocaldir-1); } 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`](#httpendpoint) | [`TcpEndpoint`](#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`](#client) The process-wide client used by the object-model statics ([Sailbox](#sailbox), [App](#app), [Volume](#volume)) when no explicit `client` is passed. Created lazily from the environment on first use. #### Returns [`Client`](#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`](#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`](#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`](#client) \| `undefined` | #### Returns `void`