> ## 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 > TypeScript SDK installation and full reference The Sail TypeScript SDK (`@sailresearch/sdk` on npm) runs on Node 22+ and Bun. Sail also provides [Python](/reference/python-sdk) and [Rust](/reference/rust-sdk) SDKs. ## Install ```bash npm theme={null} npm install @sailresearch/sdk ``` ```bash pnpm theme={null} pnpm add @sailresearch/sdk ``` ```bash bun theme={null} bun add @sailresearch/sdk ``` The SDK supports Linux x64/arm64 (glibc and musl), macOS x64/arm64, and Windows x64. The Sail API warns when your SDK version is nearing the end of its support window. The SDK prints that warning to stderr once per process. A version past the end of its support window is rejected with an upgrade error before any operation runs. Upgrade with `npm install @sailresearch/sdk@latest`. ## Configure Set `SAIL_API_KEY` in the environment; the SDK also reads the credential `sail auth login` stores under `~/.sail`. The statics on `Sailbox`, `App`, and `Volume` use this configuration by default, or construct a `Client` explicitly with `Client.fromConfig({ apiKey })`. See [Configuration](/reference/sdk-configuration). ## Quickstart ```ts theme={null} import { App, Sailbox } from "@sailresearch/sdk"; // Look up (or create) the app your sandboxes belong to. const app = await App.find("example-app", { mintIfMissing: true }); // Boot a sandbox. const sb = await Sailbox.create({ app, name: "worker-1" }); // Run a command and stream its output. const proc = await sb.exec("echo hello && ls /"); for await (const chunk of proc.stdout) process.stdout.write(chunk); const result = await proc.wait(); console.log("exit code:", result.exitCode); // Move files. await sb.fs.write("/tmp/note.txt", "hi\n"); const contents = await sb.fs.read("/tmp/note.txt"); // Expose a port and wait until it is reachable. await sb.expose(8080, { protocol: "http" }); const listener = await sb.waitForListener(8080); if (listener.endpoint?.kind === "http") { console.log("reachable at:", listener.endpoint.url); } // Clean up (see also pause / sleep / resume / checkpoint). await sb.terminate(); ``` ## Errors Every failure the SDK recognizes extends `SailError`, so one `catch (e) { if (e instanceof SailError) }` handles them; a truly unexpected error is rethrown unchanged. Subclasses like `NotFoundError` and `SailboxExecutionError` match specific failures, every error carries an advisory `retryable` flag, and `isSailError()` is the realm-safe check. See [Errors](/sailbox-sdk-errors). ## Reference The docs below are auto-generated.
## Sailbox A sandbox (Sailbox): the primary object agent harnesses work with. Create one with [Sailbox.create](#create-1), run commands with [exec](#exec-1), move files with [fs](#fs), 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` #### autoSleep ##### Get Signature > **get** **autoSleep**(): [`AutoSleep`](#autosleep-4) | `undefined` When Sail may sleep this Sailbox on its own: from the latest [Sailbox.get](#get-1) snapshot, or your own last [Sailbox.setAutoSleep](#setautosleep) through this object. `undefined` before either; a Sailbox created by [Sailbox.fromCheckpoint](#fromcheckpoint) inherits its source's preference, so call [Sailbox.get](#get-1) to learn an inherited value. ##### Returns [`AutoSleep`](#autosleep-4) | `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` #### createdByUserId ##### Get Signature > **get** **createdByUserId**(): `string` | `undefined` The user whose credential created this Sailbox (for a restore, the user who ran it). `undefined` for service-key creates. ##### Returns `string` | `undefined` #### deprecation ##### Get Signature > **get** **deprecation**(): `SailboxDeprecation` | `undefined` Actionable runtime deprecation notice, when an upgrade is needed. ##### Returns `SailboxDeprecation` | `undefined` #### diskRequestedBytes ##### Get Signature > **get** **diskRequestedBytes**(): `number` | `undefined` Requested disk, in bytes. ##### Returns `number` | `undefined` #### diskUsedBytes ##### Get Signature > **get** **diskUsedBytes**(): `number` | `undefined` Current disk usage, in bytes, as of the snapshot. ##### Returns `number` | `undefined` #### errorMessage ##### Get Signature > **get** **errorMessage**(): `string` | `undefined` Failure detail when the status is `failed`. ##### Returns `string` | `undefined` #### fs ##### Get Signature > **get** **fs**(): [`SailboxFs`](#sailboxfs-1) Filesystem operations on this Sailbox's guest: read and write files (buffered or streaming), and directory helpers. ##### Returns [`SailboxFs`](#sailboxfs-1) #### guestSchemaVersion ##### Get Signature > **get** **guestSchemaVersion**(): `number` | `undefined` The Sailbox runtime schema version the Sailbox last booted with. ##### Returns `number` | `undefined` #### imageId ##### Get Signature > **get** **imageId**(): `string` | `undefined` Identifier of the image the Sailbox was created from. ##### Returns `string` | `undefined` #### lastCheckpointedAt ##### Get Signature > **get** **lastCheckpointedAt**(): `Date` | `undefined` When the most recent checkpoint was taken. ##### Returns `Date` | `undefined` #### memoryMib ##### Get Signature > **get** **memoryMib**(): `number` | `undefined` Configured memory, in MiB. ##### Returns `number` | `undefined` #### memoryRequestedBytes ##### Get Signature > **get** **memoryRequestedBytes**(): `number` | `undefined` Requested memory, in bytes. ##### Returns `number` | `undefined` #### memoryUsedBytes ##### Get Signature > **get** **memoryUsedBytes**(): `number` | `undefined` Current memory usage, in bytes, as of the snapshot. ##### Returns `number` | `undefined` #### name ##### Get Signature > **get** **name**(): `string` The Sailbox name. ##### Returns `string` #### networkPolicy ##### Get Signature > **get** **networkPolicy**(): [`NetworkPolicyInfo`](#networkpolicyinfo) | `undefined` The Sailbox's network policy, frozen at creation, from the latest [Sailbox.get](#get-1) or [Sailbox.list](#list-2) snapshot. `undefined` means public (unrestricted outbound access) or that no snapshot has been taken yet; a present value carries the restrictive mode so you can verify what is enforced, including on a Sailbox created from a checkpoint. ##### Returns [`NetworkPolicyInfo`](#networkpolicyinfo) | `undefined` #### sailboxId ##### Get Signature > **get** **sailboxId**(): `string` The Sailbox's stable identifier. ##### Returns `string` #### startedAt ##### Get Signature > **get** **startedAt**(): `Date` | `undefined` When the Sailbox first started running. A resume does not rewrite it. ##### Returns `Date` | `undefined` #### stateDiskSizeGib ##### Get Signature > **get** **stateDiskSizeGib**(): `number` | `undefined` Configured state-disk size, in GiB. ##### Returns `number` | `undefined` #### status ##### Get Signature > **get** **status**(): [`SailboxStatus`](#sailboxstatus-1) The lifecycle status as of the call that produced this handle (updated by lifecycle calls on this instance). Use [Sailbox.get](#get-1) 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` #### visibility ##### Get Signature > **get** **visibility**(): `string` | `undefined` `"private"` when access is restricted to the creator; `undefined`/`"org"` is the default org-wide access. ##### Returns `string` | `undefined` #### volumeMounts ##### Get Signature > **get** **volumeMounts**(): `SailboxVolumeMount`\[] | `undefined` Volumes attached to this Sailbox and the paths they are mounted at. ##### Returns `SailboxVolumeMount`\[] | `undefined` ### Methods #### checkpoint() > **checkpoint**(`options?`): `Promise`\<[`SailboxCheckpoint`](#sailboxcheckpoint-1)> Take a checkpoint of this Sailbox and prepare its clean start state. The returned handle carries `expiresAt`, after which starting a Sailbox from it fails. Sailboxes with volume mounts are not supported. Upgrade a Sailbox that uses an older guest payload before creating a checkpoint handle. ##### Parameters | Parameter | Type | | --------- | ----------------------------------------- | | `options` | [`CheckpointOptions`](#checkpointoptions) | ##### Returns `Promise`\<[`SailboxCheckpoint`](#sailboxcheckpoint-1)> #### clearHttpPolicy() > **clearHttpPolicy**(): `Promise`\<`void`> Clear this Sailbox's attached HTTP policy. The change applies to HTTPS connections this Sailbox opens after the call; connections already open keep the previous policy until they close. This also resolves when no policy is attached. ##### Returns `Promise`\<`void`> #### 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); a private Sailbox accepts only its creator's certificates. Safe to re-run. With `wait` (the default), polls until the endpoint is reachable and returns it, throwing [TimeoutError](#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. By default a stream you are consuming pauses the command when you fall behind, so nothing is lost until a cancel or the exec timeout ends the pauses, and a stream you are not consuming keeps only its most recent 1 MiB; start consuming right after this call returns to get every byte. `outputMode` and `outputBufferBytes` in `options` change that (see [ExecProcess](#execprocess)). `options` can also set a working directory or detach the command (see [ExecOptions](#execoptions)). Stopping the command is the caller's job via [ExecProcess.cancel](#cancel). ##### Parameters | Parameter | Type | | ---------- | -------------------------------- | | `command` | `string` \| readonly `string`\[] | | `options?` | [`ExecOptions`](#execoptions) | ##### Returns `Promise`\<[`ExecProcess`](#execprocess)> #### expose() > **expose**(`guestPort`, `options?`): `Promise`\<[`Listener`](#listener-1)> Expose a guest port at runtime. Re-exposing a port under the same protocol sets its `allowlist` to what you pass, so pass the whole list every time; passing none clears the restriction and reopens the port. The returned listener carries the resolved endpoint but an `"unknown"` route status: the response confirms configuration, not reachability; [waitForListener](#waitforlistener-1) confirms the route is live. ##### Parameters | Parameter | Type | | ----------- | --------------------------------- | | `guestPort` | `number` | | `options` | [`ExposeOptions`](#exposeoptions) | ##### Returns `Promise`\<[`Listener`](#listener-1)> #### httpPolicy() > **httpPolicy**(): `Promise`\<[`HttpPolicy`](#httppolicy) | `null`> The HTTP policy attached to this Sailbox, or `null` when no policy is attached. ##### Returns `Promise`\<[`HttpPolicy`](#httppolicy) | `null`> #### 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 Sailbox. ##### 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`> #### resume() > **resume**(): `Promise`\<`void`> Resume this Sailbox (updates [status](#status-2)). ##### Returns `Promise`\<`void`> #### run() > **run**(`command`, `options?`): `Promise`\<[`ExecResult`](#execresult)> Run a command to completion and return its buffered result: a one-shot convenience over [exec](#exec-1) followed by [ExecProcess.wait](#wait). A `string` command runs via `/bin/sh -lc`; a `string[]` is exec'd directly. Set `env` in `options` to add environment variables; `cwd` sets the working directory (string commands only, like [exec](#exec-1)); `signal` force-cancels the command on abort (see [RunOptions](#runoptions)). The result's stdout and stderr hold only the most recent `outputBufferBytes` of each stream (1 MiB by default, up to 64 MiB), with `stdoutTruncated` and `stderrTruncated` set when older output was dropped; the command never pauses for unread output. While the first call is still running, a second call with the same `idempotencyKey` takes over its output stream, and the earlier call's result may come back truncated. To get every byte, use [exec](#exec-1) and consume the stream (see [ExecProcess](#execprocess)). `openStdin`, `pty`, `background`, and `outputMode: "pipe"` are excluded from [RunOptions](#runoptions) and rejected at runtime: run() waits for the command to finish and buffers its output, so an interactive command would hang, a backgrounded one would return the launcher's result, not the command's, and a pipe would pause forever with nobody consuming it; use [exec](#exec-1) for those. ##### Parameters | Parameter | Type | | ---------- | -------------------------------- | | `command` | `string` \| readonly `string`\[] | | `options?` | [`RunOptions`](#runoptions) | ##### Returns `Promise`\<[`ExecResult`](#execresult)> #### setAutoSleep() > **setAutoSleep**(`autoSleep`): `Promise`\<`void`> Replace when Sail may sleep this Sailbox on its own. Each call replaces the whole setting: switching to `{ automatic: false }` clears any minimum wait set earlier, and switching back does not restore it. Calling [Sailbox.sleep](#sleep) yourself is unaffected, and so are `pause`, `resume`, and scheduled wakes. ##### Parameters | Parameter | Type | | ----------- | --------------------------- | | `autoSleep` | [`AutoSleep`](#autosleep-4) | ##### Returns `Promise`\<`void`> #### setHttpPolicy() > **setHttpPolicy**(`policy`): `Promise`\<`void`> Attach an HTTP policy to this Sailbox, replacing any policy already attached (a Sailbox has at most one). Accepts an [HttpPolicy](#httppolicy), a listing summary, or a policy id string. The policy applies to HTTPS connections this Sailbox opens after the call; connections already open keep the previous policy until they close. ##### Parameters | Parameter | Type | | --------- | ----------------------------------- | | `policy` | [`HttpPolicyLike`](#httppolicylike) | ##### Returns `Promise`\<`void`> #### shell() > **shell**(`command?`, `options?`): `Promise`\<`number`> Open an interactive pty session on this Sailbox, bridged to the local terminal. With no `command`, runs a login shell; pass a command to run that under a pty instead (e.g. a REPL or an editor). Blocks until the remote process exits and resolves with its exit code. Requires an interactive terminal (stdin and stdout TTYs) on a Unix machine. The session runs as the image's `USER` when the image sets one, root otherwise; see [ShellOptions.user](#user-3). While the session is open, browser opens, localhost servers, paste, drag-and-drop, and clipboard are forwarded to your machine (the clipboard is two-way on devbox images); see [ShellOptions.noForward](#noforward). ##### Parameters | Parameter | Type | | ---------- | ------------------------------- | | `command?` | `string` | | `options?` | [`ShellOptions`](#shelloptions) | ##### Returns `Promise`\<`number`> #### sleep() > **sleep**(`wakeAt?`): `Promise`\<`Date` | `undefined`> Sleep this Sailbox to disk (wakes on traffic), optionally scheduling a wall-clock wake first. `wakeAt`, when given, records the wake before the sleep starts and the returned value is the effective wake time: the sooner of this request and any wake already scheduled. If the Sailbox is sleeping when that moment arrives, Sail restores it. The wake can fire a little after the time you set, so treat it as approximate. Sleeping an already-sleeping Sailbox succeeds and just updates the scheduled wake. ##### Parameters | Parameter | Type | | --------- | ------ | | `wakeAt?` | `Date` | ##### Returns `Promise`\<`Date` | `undefined`> #### terminate() > **terminate**(): `Promise`\<`void`> Terminate (delete) this Sailbox (updates [status](#status-2)). ##### 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 runtime. ##### 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)> #### create() > `static` **create**(`options`): `Promise`\<[`Sailbox`](#sailbox)> Create a new Sailbox. A custom image definition passed as `image` is built first. Sail may sleep a fully idle Sailbox; it wakes transparently on traffic or the next operation. ##### Parameters | Parameter | Type | | --------- | ----------------------------------------------- | | `options` | [`CreateSailboxOptions`](#createsailboxoptions) | ##### Returns `Promise`\<[`Sailbox`](#sailbox)> #### fromCheckpoint() > `static` **fromCheckpoint**(`options`): `Promise`\<[`Sailbox`](#sailbox)> Create a new running Sailbox from a durable checkpoint handle. The new Sailbox uses the checkpoint's writable disk and cleaned memory state, so background processes continue and the new Sailbox runs independently of the source. Commands started with [Sailbox.exec](#exec-1) stop, though their writes up to the checkpoint remain. Host-specific identity and network routes are removed before the checkpoint handle becomes ready. A Sailbox with volume mounts cannot create a reusable checkpoint. If Sail cannot resume the saved memory, it starts the child cold with its writable disk intact and without the saved processes. The new Sailbox keeps the original's network policy; read it back with [Sailbox.get](#get-1). ##### Parameters | Parameter | Type | | --------- | ------------------------------------------------- | | `options` | [`FromCheckpointOptions`](#fromcheckpointoptions) | ##### Returns `Promise`\<[`Sailbox`](#sailbox)> #### fromId() > `static` **fromId**(`sailboxId`, `options?`): [`Sailbox`](#sailbox) Bind a handle to an existing Sailbox id without a network call. The returned handle carries no snapshot fields (its [name](#name-2) and [status](#status-2) are empty), just the operable surface. The id is not verified to exist: operations on an unknown or inaccessible id reject with [NotFoundError](#notfounderror). Use [get](#get-1) to validate the id and fetch a fresh snapshot instead. ##### Parameters | Parameter | Type | | ----------- | --------------------------------- | | `sailboxId` | `string` | | `options` | [`ClientOptions`](#clientoptions) | ##### Returns [`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?`): `Promise`\<[`Sailbox`](#sailbox)\[]> List the Sailboxes that match the filters, fetching pages internally until every match (or `limit` of them) is collected; use [listPage](#listpage) to page through results manually instead. `limit` caps the total returned, bounding the fetch for large orgs. A `client` can ride along in the query object. ##### Parameters | Parameter | Type | | --------- | ----------------------------------------------- | | `params` | [`ListSailboxesOptions`](#listsailboxesoptions) | ##### Returns `Promise`\<[`Sailbox`](#sailbox)\[]> #### listPage() > `static` **listPage**(`params?`): `Promise`\<[`SailboxPage`](#sailboxpage)> List one page of Sailboxes alongside the pagination envelope (`total`/`hasMore`). Takes the same filters as [list](#list-2), plus `limit` and `offset` to select the page. ##### Parameters | Parameter | Type | | --------- | ------------------------------------------------------- | | `params` | [`ListSailboxesPageOptions`](#listsailboxespageoptions) | ##### Returns `Promise`\<[`SailboxPage`](#sailboxpage)> *** ## 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-1). ### 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` | [`FindAppOptions`](#findappoptions) | ##### 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)\[]> *** ## Image A Sailbox image: a base, registry, or Dockerfile image plus ordered build steps. Immutable and fluent: each method returns a new `Image`. Local files/dirs are recorded here and hashed and uploaded when the image is resolved to a spec (at [Sailbox.create](#create-1), or via [toSpec](#tospec)), so chaining stays synchronous. ### Example ```ts theme={null} const image = Image.debian() .aptInstall("git") .pipInstall("numpy") .addLocalDir("./app", "/app", { ignore: ["*.pyc", "__pycache__/"] }) .runCommand("pip install -e /app"); const box = await Sailbox.create({ app, name: "w", image }); ``` ### Methods #### addLocalDir() > **addLocalDir**(`localPath`, `remotePath`, `options?`): [`Image`](#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-1) calls this for a custom image before creating the Sailbox (the backend serves the content-addressed built image); a bare base image skips the build. Local files are re-hashed on every call, so edits always reach the build, and rebuilding an unchanged, already-built image returns quickly. Creating Sailboxes from the returned spec needs no further build. For an image imported with [Image.fromRegistry](#fromregistry) through a tag, the spec is also pinned to the exact version the build resolved the tag to, even if the tag later moves upstream. [ImageBuildOptions.forceBuild](#forcebuild) looks the tag up again and moves the tag's meaning for your whole organization. For an image built with [Image.fromDockerfile](#fromdockerfile), the returned spec is likewise pinned to the versions the build resolved for its `FROM` and `COPY --from` images; [ImageBuildOptions.forceBuild](#forcebuild) moves those pins for your whole organization, while specs built earlier keep their pinned versions. ##### Parameters | Parameter | Type | | --------- | ----------------------------------------- | | `options` | [`ImageBuildOptions`](#imagebuildoptions) | ##### Returns `Promise`\<[`ImageSpec`](#imagespec)> #### env() > **env**(`env`): [`Image`](#image) Bake environment variables into the image (keys are trimmed). ##### Parameters | Parameter | Type | | --------- | ------------------------------------------ | | `env` | `Readonly`\<`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-1) 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 amd64). ##### Parameters | Parameter | Type | Default value | | -------------- | ----------------------------------------- | ------------- | | `architecture` | [`ImageArchitecture`](#imagearchitecture) | `"amd64"` | ##### Returns [`Image`](#image) #### devbox() > `static` **devbox**(`architecture?`): [`Image`](#image) The devbox base image (defaults to amd64): a prebuilt Debian base with a baked development layer. Docker is included, and its daemon starts automatically when the Sailbox boots and keeps running across sleeps. The daemon can take a few seconds to accept commands right after boot. If it stops, it is not restarted automatically. Prebuilt-only, so it does not support build steps or env; start from [Image.debian](#debian) to customize. ##### Parameters | Parameter | Type | Default value | | -------------- | ----------------------------------------- | ------------- | | `architecture` | [`ImageArchitecture`](#imagearchitecture) | `"amd64"` | ##### Returns [`Image`](#image) #### fromDockerfile() > `static` **fromDockerfile**(`dockerfile`, `options?`): [`Image`](#image) Build your own Dockerfile into a Sailbox image, with everything Sail needs layered on top. Pass the path to a Dockerfile on this machine, or its literal text wrapped as `{ contents }`. The result behaves like any other image: build steps, env, and pip/apt installs work the same as on [Image.debian](#debian). Pass `contextDir` to give the Dockerfile's `COPY` and `ADD` instructions a build context; if omitted, the build runs without one. A `.dockerignore` in that directory is honored, and `ignore` patterns are applied after it, so they take precedence on conflict. A file named after the Dockerfile, like `Dockerfile.dockerignore`, sitting next to it is used instead of the context's `.dockerignore`, as it is with Docker. The files the ignore rules keep are hashed and uploaded when the image is built, so edits up to that point reach the build. File modes, empty directories, and symbolic links are carried into the build. Every image a `FROM` (or `COPY --from`) instruction names must live on a supported public registry (`docker.io`, `ghcr.io`, `public.ecr.aws`, or `quay.io`); a short name like `python:3.12` means `docker.io/library/python:3.12`. Each named image is pinned to the version its tag pointed at the first time your organization used it, and those pinned versions become part of the built image's identity, so rebuilding the same spec reuses the same image even after a tag moves. Pass `forceBuild` to [Image.build](#build) to look the tags up again and build what they point at now. The Dockerfile must produce a Debian- or Ubuntu-based filesystem. A `# syntax=` line can declare `docker/dockerfile:1` or a release from 1.4 through 1.22.0. A file that declares anything else is rejected. The declared release does not change how the file is built. Multi-stage Dockerfiles work. A `RUN --mount` of type `cache`, `secret`, or `ssh` is rejected; `tmpfs` mounts work, and `bind` mounts work when they read from the build context or another build stage. Mount options must be literal text, and `ONBUILD` is not supported, in the Dockerfile or in an image a `FROM` names. The built image's environment variables, working directory, and `USER` become the defaults for commands you run with [Sailbox.exec](#exec-1) or [Sailbox.run](#run); per-call `env`, `cwd`, and `user` override them (pass `user: "0:0"` to run as root on an image that sets `USER`). The image's `ENTRYPOINT` and `CMD` are not run: a Sailbox manages its own processes, and your commands say what to execute. Build steps you chain onto the image (such as `aptInstall`) and SSH sessions still run as root. ##### Parameters | Parameter | Type | | ------------ | ------------------------------------------------- | | `dockerfile` | `string` \| \{ `contents`: `string`; } | | `options` | [`FromDockerfileOptions`](#fromdockerfileoptions) | ##### Returns [`Image`](#image) ##### Example ```ts theme={null} const image = Image.fromDockerfile("./envs/task1/Dockerfile", { contextDir: "./envs/task1", }); ``` #### fromRegistry() > `static` **fromRegistry**(`ref`, `options?`): [`Image`](#image) Your own image as the Sailbox root filesystem, with everything Sail needs layered on top. The result behaves like any other image: build steps, env, and pip/apt installs work the same as on [Image.debian](#debian). Reference an image on a supported public registry (`docker.io`, `ghcr.io`, `public.ecr.aws`, or `quay.io`), written as you would for `docker pull`: `python:3.13` means `docker.io/library/python:3.13` and `acme/tool` means `docker.io/acme/tool`; name the registry for the others, as in `ghcr.io/acme/tool`. You can pass a tag, a `@sha256:...` digest, or just the name, which means the `latest` tag. The image must be Debian- or Ubuntu-based. Your Sailbox runs on the CPU architecture the image was built for. An image published for both amd64 and arm64 runs on amd64. Pass `architecture` to require one instead, and building fails if the image was not built for it. A tag is pinned for your organization once an image has been built from it: later builds keep using that image even after the tag moves upstream. Call `build({ forceBuild: true })` to look the tag up again and build the version it points at now for your whole organization; see [ImageBuildOptions.forceBuild](#forcebuild) for how the switch propagates. A digest names exactly one image, so it never moves. The image's environment variables, working directory, and `USER` become the defaults for commands you run with [Sailbox.exec](#exec-1) or [Sailbox.run](#run); per-call `env`, `cwd`, and `user` override them (pass `user: "0:0"` to run as root on an image that sets `USER`). The image's `ENTRYPOINT` and `CMD` are not run: a Sailbox manages its own processes, and your commands say what to execute. Build steps you chain onto the image (such as `aptInstall`) and SSH sessions still run as root. ##### Parameters | Parameter | Type | | --------- | --------------------------------------------- | | `ref` | `string` | | `options` | [`FromRegistryOptions`](#fromregistryoptions) | ##### Returns [`Image`](#image) ##### Example ```ts theme={null} const image = Image.fromRegistry( "docker.io/library/python:3.13" ).aptInstall("git"); ``` *** ## 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. Each stream has a buffer, 1 MiB by default (`outputBufferBytes`), and the `outputMode` says what happens when it fills. With the default `"auto"`: if you are not consuming a stream, the command never pauses and the stream keeps only its most recent bytes; if you are consuming a stream and fall behind, the command pauses when the buffer fills and resumes as you read, like a pipe. Consuming a stream is how you get every byte, and it slows the command when you cannot keep up. `"pipe"` holds both streams from the start, so a consumer that starts late still gets every byte; `"tail"` never pauses the command for you. See `OutputMode`. With `"auto"`, start consuming right after `exec()` returns to get every byte. You can consume stdout without holding stderr, or the reverse; the stream you are not holding keeps its most recent bytes and never pauses the command when it fills. If you hold both, consume them at the same time (`Promise.all`). The exit code is available from [poll](#poll) once the streams end and from [wait](#wait). Accessing `proc.stdout` or `proc.stderr` claims nothing. A stream is claimed when you start iterating it (`for await`, [ExecStream.raw](#raw), [ExecStream.text](#text), [ExecStream.bytes](#bytes)) or call [ExecStream.toReadable](#toreadable), and released when the iteration finishes or you leave it (`break`, `return`, a thrown error), when `.text()` or `.bytes()` reaches the end, or when the `Readable` is destroyed. Each stream can be claimed once; a second attempt rejects with `InvalidArgumentError`. [wait](#wait) returns each stream's buffer, its most recent output, with `stdoutTruncated` / `stderrTruncated` set when older output was dropped. [close](#close), or your process exiting, releases both streams; the command keeps running, and `wait()` rejects after `close()` unless it already resolved a result. Sail may reattach after an interruption, but reattachment does not guarantee exact output replay. A pty command never pauses; [resync](#resync) requests a fresh screen. ### Example ```ts theme={null} const proc = await box.exec(["bash", "-lc", "echo hi"]); for await (const chunk of proc.stdout) process.stdout.write(chunk); const result = await proc.wait(); console.log(result.exitCode, result.stderr); ``` ### Accessors #### execRequestId ##### Get Signature > **get** **execRequestId**(): `string` The durable exec request id: the launch's idempotency key as Sail recorded it (yours, or the one Sail generated when you did not supply one; read it here to learn the generated value). Reading it marks a generated identity as shareable: a second handle started with it takes over the stream, so from then on this handle no longer reclaims the stream after any interruption, a clean end or a dropped connection alike, and resolves from the recorded result instead. Reading back a key you supplied changes nothing. ##### Returns `string` #### output ##### Get Signature > **get** **output**(): [`ExecStream`](#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) #### stderr ##### Get Signature > **get** **stderr**(): [`ExecStream`](#execstream) The sole stderr stream: string iteration by default, `.raw()` for bytes. Claimed and released the same way as [stdout](#stdout). ##### Returns [`ExecStream`](#execstream) #### stdout ##### Get Signature > **get** **stdout**(): [`ExecStream`](#execstream) The sole stdout stream: string iteration by default, `.raw()` for bytes. Accessing this property claims nothing; the stream is claimed when you start consuming it and released when the iteration finishes or you leave it (see [ExecStream](#execstream)). ##### 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`). Transient failures are retried briefly, covering the window right after the command starts when the guest cannot accept signals for it yet. ##### Parameters | Parameter | Type | | --------- | --------------------------------- | | `options` | [`CancelOptions`](#canceloptions) | ##### Returns `Promise`\<`void`> #### close() > **close**(): `void` Abandon the handle without killing the command. It releases both streams. The command keeps running and never pauses, and Sail keeps only the most recent output of each stream. Call [cancel](#cancel) instead if the command should stop. [wait](#wait) rejects after `close()` unless it already resolved a result. ##### Returns `void` #### closeStdin() > **closeStdin**(): `Promise`\<`void`> Close the command's stdin (send EOF). ##### Returns `Promise`\<`void`> #### poll() > **poll**(): `number` | `null` The exit code once the output stream has ended, else `null`. Never blocks and never drops output. If the connection was lost for good mid-command, the stream ends early with the outcome still unknown: `poll()` stays `null` and [wait](#wait) fetches the result Sail recorded. A host-lost exec (the machine running the Sailbox was lost mid-command) has no real exit code: [wait](#wait) always throws `SailboxHostLostError` for one, and `poll()` throws it when that loss is what ended the stream. ##### Returns `number` | `null` #### resize() > **resize**(`cols`, `rows`): `Promise`\<`void`> Resize the pty (no-op without one). ##### Parameters | Parameter | Type | | --------- | -------- | | `cols` | `number` | | `rows` | `number` | ##### Returns `Promise`\<`void`> #### resync() > **resync**(): `Promise`\<`void`> Ask a pty exec to repaint its current screen (no-op without a pty). A command runs at full speed and never waits for a slow reader, so if you fall far behind the oldest output is dropped. Call this after that happens to receive the current screen instead of a broken, partial one. Advisory and best-effort. ##### Returns `Promise`\<`void`> #### wait() > **wait**(): `Promise`\<[`ExecResult`](#execresult)> Wait for the command to finish and return its result. `stdout` and `stderr` on the result hold each stream's buffer, its most recent output (1 MiB by default), with `stdoutTruncated` / `stderrTruncated` set when older output was dropped; to get every byte, consume the stream (see [ExecProcess](#execprocess)). `wait()` itself never pauses the command and may run alongside an active consumer. With `outputMode: "pipe"`, a stream nobody consumes pauses the command when its buffer fills, and `wait()` then waits for as long as the command stays paused. It rejects after [close](#close) unless it already resolved a result. ##### Returns `Promise`\<[`ExecResult`](#execresult)> #### writeStdin() > **writeStdin**(`data`): `Promise`\<`void`> Write to the command's stdin (requires `openStdin`). ##### Parameters | Parameter | Type | | --------- | ---------------------------------------------------------------------------- | | `data` | `string` \| `Buffer`\<`ArrayBufferLike`> \| `Uint8Array`\<`ArrayBufferLike`> | ##### Returns `Promise`\<`void`> *** ## ExecStream An async-iterable view of one exec stream (stdout or stderr). Default iteration yields `string` chunks, incrementally decoded as UTF-8 (a multibyte character split across chunks is carried until complete); use [raw](#raw) for the unmodified byte stream. Iteration ends once the command finishes and its remaining output has been delivered; if the connection was lost for good mid-command, it ends early with the outcome still unknown, and [ExecProcess.wait](#wait) fetches the result Sail recorded. An `ExecStream` can be consumed once: string iteration, [raw](#raw), [toReadable](#toreadable), [text](#text), or [bytes](#bytes); a second consumer rejects with `InvalidArgumentError`. Accessing `proc.stdout` claims nothing. The stream is claimed when you start consuming it, and from then on nothing is lost: the command pauses when you fall behind. That does not hold for pty output, for `outputMode: "tail"`, or after `cancel()` or the exec timeout has ended the pauses (see [ExecProcess](#execprocess)). It is released when the iteration finishes or you leave it (`break`, `return`, a thrown error), when [text](#text) or [bytes](#bytes) reaches the end, or when the `Readable` from [toReadable](#toreadable) is destroyed. While nobody is consuming, Sail keeps only the stream's most recent bytes (1 MiB by default) unless the exec runs with `outputMode: "pipe"`, so start consuming right after `exec()` returns when you need every byte. Pty output never pauses the command and keeps only its most recent bytes. ### Example ```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]` #### bytes() > **bytes**(): `Promise`\<`Buffer`\<`ArrayBufferLike`>> Consume and collect the raw byte stream into a single `Buffer`. ##### Returns `Promise`\<`Buffer`\<`ArrayBufferLike`>> #### raw() > **raw**(): `AsyncIterableIterator`\<`Buffer`\<`ArrayBufferLike`>> Iterate the raw byte stream, exactly as the command wrote it (escape sequences and binary payloads included). This consumes the stream. ##### Returns `AsyncIterableIterator`\<`Buffer`\<`ArrayBufferLike`>> #### text() > **text**(): `Promise`\<`string`> Consume and collect the stream into a single string. ##### Returns `Promise`\<`string`> #### toReadable() > **toReadable**(): `Readable` Consume this stream as a Node `Readable` of string chunks. Calling this claims the stream at once; destroying the `Readable` releases it at once, even while a read is waiting for output. ##### Returns `Readable` *** ## SailboxFs Filesystem operations on a Sailbox's guest, reached via [Sailbox.fs](#fs). File I/O streams bytes to/from the guest; the directory helpers create, remove, test, and transfer paths. Writes give what they create to the image's `USER` by default (root when the image sets none), the same identity commands run as, so an uploaded file is usable by the code in the Sailbox. Reads and the directory helpers act as root by default, so they work on any path. Every operation except the reads and the directory download takes an optional `user` in Docker's `USER` syntax (`name`, `uid`, `name:group`, or `uid:gid`; `"0:0"` is always root). The directory helpers other than the transfers run their command as that user, with its permissions enforced. Writes and the directory upload keep running as root but give that user what they create, like `COPY --chown`. Reads and the download take no `user`: a `user` only decides which paths an operation may touch and who owns what it creates. A read creates nothing in the Sailbox, and a download reads any path as root, the way the reads do. A `user` other than `"0:0"` requires a Sailbox whose guest honors requested users; on older Sailboxes these calls fail until [Sailbox.upgrade](#upgrade) is called. ### Methods #### downloadDir() > **downloadDir**(`dirs`): `Promise`\<`void`> Download a directory's contents from the Sailbox into a local directory. `guestDir`'s entries land inside `localDir`, which is created if needed. Entries the download does not name are left in place; a same-named file is replaced. The transfer reads every file in the tree, so download directories of ordinary files: system trees like `/proc` or `/sys` hold files that cannot be read as plain data, and downloading them fails. A file that is being written while the download runs is captured as it is at that moment, the way copying a live file would; download after writers finish for a consistent copy. On Windows, a directory that contains symbolic links cannot be downloaded, since Windows restricts creating them. The Sailbox's image must provide `tar` and `gzip`, which the transfer uses to ship the directory as one compressed archive; the default images do. ##### Parameters | Parameter | Type | | --------------- | ------------------------------------------------ | | `dirs` | \{ `guestDir`: `string`; `localDir`: `string`; } | | `dirs.guestDir` | `string` | | `dirs.localDir` | `string` | ##### Returns `Promise`\<`void`> #### exists() > **exists**(`path`, `options?`): `Promise`\<`boolean`> Whether `path` exists in the guest. Follows symlinks (like `test -e`), so a dangling symlink reports `false` even though [ls](#ls) lists it. A `user` reports existence as observable by that user: a path the user lacks permission to reach also reports `false`. ##### Parameters | Parameter | Type | | ---------- | ------------------------- | | `path` | `string` | | `options?` | [`FsOptions`](#fsoptions) | ##### Returns `Promise`\<`boolean`> #### ls() > **ls**(`path`, `options?`): `Promise`\<[`DirEntry`](#direntry)\[]> List a directory's immediate entries as [DirEntry](#direntry) records (no recursion). A missing path throws, as does a path that is not a directory and a listing too large for the exec output cap. An entry whose name is not valid UTF-8 fails the listing, since the path API cannot address it. A `user` runs the listing as that user, so a directory it may not read fails with a permission error. ##### Parameters | Parameter | Type | | ---------- | ------------------------- | | `path` | `string` | | `options?` | [`FsOptions`](#fsoptions) | ##### Returns `Promise`\<[`DirEntry`](#direntry)\[]> #### mkdir() > **mkdir**(`path`, `options?`): `Promise`\<`void`> Create a directory and any missing parents (like `mkdir -p`); a no-op if it already exists. A `user` runs the mkdir as that user, so created directories are owned by it. ##### Parameters | Parameter | Type | | ---------- | ------------------------- | | `path` | `string` | | `options?` | [`FsOptions`](#fsoptions) | ##### 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)> #### remove() > **remove**(`path`, `options?`): `Promise`\<`void`> Remove a file or directory tree (like `rm -rf`); a no-op if it is already absent. A `user` runs the removal as that user, limiting it to what that user may delete. ##### Parameters | Parameter | Type | | ---------- | ------------------------- | | `path` | `string` | | `options?` | [`FsOptions`](#fsoptions) | ##### Returns `Promise`\<`void`> #### uploadDir() > **uploadDir**(`dirs`): `Promise`\<`void`> Upload a local directory's contents into a directory on the Sailbox. `localDir`'s entries land inside `guestDir`, which is created if needed. Entries the upload does not name are left in place; a same-named file is replaced. Uploaded files belong to the image's `USER`, the same identity commands run as, so the code in the Sailbox can use them. When the image sets no `USER`, or that user cannot be resolved in the Sailbox, they belong to root. `guestDir` and any missing parents the upload creates get the same owner. Files keep their permission bits, except that the setuid, setgid, and sticky bits are cleared. A `user` (the same syntax the other operations take) gives the entries to that user instead, like `COPY --chown`; it must exist in the Sailbox, and like the other operations' `user` it requires a Sailbox whose guest honors requested users. The Sailbox's image must provide `tar` and `gzip`, which the transfer uses to ship the directory as one compressed archive; the default images do. ##### Parameters | Parameter | Type | | --------------- | ------------------------------------------------------------------- | | `dirs` | \{ `guestDir`: `string`; `localDir`: `string`; `user?`: `string`; } | | `dirs.guestDir` | `string` | | `dirs.localDir` | `string` | | `dirs.user?` | `string` | ##### Returns `Promise`\<`void`> #### write() > **write**(`path`, `data`, `options?`): `Promise`\<`void`> Write `data` to a guest file: [writeFiles](#writefiles-1) with one entry. Strings use UTF-8. Missing parent directories are created unless `createParents` is false. Use [writeStream](#writestream-1) to stream a large source. ##### Parameters | Parameter | Type | | ---------- | ---------------------------------------------------------------------------- | | `path` | `string` | | `data` | `string` \| `Buffer`\<`ArrayBufferLike`> \| `Uint8Array`\<`ArrayBufferLike`> | | `options?` | [`WriteOptions`](#writeoptions) | ##### Returns `Promise`\<`void`> #### writeFiles() > **writeFiles**(`files`, `options?`): `Promise`\<`void`> Write several complete files in one call. `files` maps each absolute guest path to its contents (strings use UTF-8). Each file is its own request, up to eight at a time, and every file gets the same options. A batch is not atomic across paths: the first failure stops the batch, files that already completed stay written, writes already in flight finish, and the error names the file that failed. A path may appear only once. Use [writeStream](#writestream-1) to stream a large source. ##### Parameters | Parameter | Type | | ---------- | ---------------------------------------------------------------------- | | `files` | `Readonly`\<`Record`\<`string`, `Buffer` \| `Uint8Array` \| `string`>> | | `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)> *** ## 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 #### \[asyncDispose]\() > **\[asyncDispose]**(): `Promise`\<`void`> `await using` support; same semantics as the synchronous form. ##### Returns `Promise`\<`void`> #### \[dispose]\() > **\[dispose]**(): `void` `using` support: aborts the write if it was never finished, so leaving scope on an error path cancels instead of committing a partial file. `abort` is synchronous, so the plain form suffices. ##### Returns `void` #### abort() > **abort**(): `void` Abort the write: cancel the request so the server does not commit it. Idempotent. A later [finish](#finish) reports the abort instead of succeeding; the guest file state after an abort is unspecified. ##### Returns `void` #### finish() > **finish**(): `Promise`\<`void`> Confirm the write, creating an empty file if nothing was written. ##### Returns `Promise`\<`void`> #### toWritable() > **toWritable**(): `Writable` Adapt to a Node `Writable`: `end()` runs [finish](#finish) (only that commits the write), destroying the stream aborts it, and backpressure follows the underlying transfer since each chunk's callback fires when its [write](#write) resolves. ##### Returns `Writable` #### write() > **write**(`data`): `Promise`\<`void`> Write bytes (a `string` is encoded as UTF-8). The SDK splits them into transport-sized chunks. ##### Parameters | Parameter | Type | | --------- | ---------------------------------------------------------------------------- | | `data` | `string` \| `Buffer`\<`ArrayBufferLike`> \| `Uint8Array`\<`ArrayBufferLike`> | ##### Returns `Promise`\<`void`> *** ## FileStream An async-iterable download of a guest file. Chunks are `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` *** ## 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-2)) in a Sailbox's `volumes` mapping. Volumes are currently in Alpha. To pilot them, reach out in the Sail Slack: [https://join.slack.com/t/sailresearchcrew/shared\_invite/zt-41pdcym9j-UU0Ey\~A\~r6n2H0DQVQsQHQ](https://join.slack.com/t/sailresearchcrew/shared_invite/zt-41pdcym9j-UU0Ey~A~r6n2H0DQVQsQHQ). ### Properties | Property | Modifier | Type | Default value | Description | | ---------------------------------- | ---------- | ----------------------- | ------------- | ----------------------------------------------------------------- | | `backend` | `readonly` | `string` | `undefined` | Storage backend serving the volume. | | `createdAt` | `readonly` | `Date` \| `undefined` | `undefined` | Creation time, if reported. | | `id` | `readonly` | `string` | `undefined` | Stable volume id. | | `mountPath` | `readonly` | `string` \| `undefined` | `undefined` | Guest mount path, when loaded via [Volume.fromMount](#frommount). | | `name` | `readonly` | `string` | `undefined` | Volume name. | | `status` | `readonly` | `string` | `undefined` | Lifecycle status. | | `updatedAt` | `readonly` | `Date` \| `undefined` | `undefined` | Last-update time, if reported. | ### Methods #### delete() > **delete**(`options?`): `Promise`\<`boolean`> Delete this volume. Resolves `true` if it was deleted, `false` if it was already gone (only possible with `allowMissing`). ##### Parameters | Parameter | Type | | --------- | --------------------------------------------- | | `options` | [`DeleteVolumeOptions`](#deletevolumeoptions) | ##### 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` | [`FindVolumeOptions`](#findvolumeoptions) | ##### 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` | [`ListVolumesOptions`](#listvolumesoptions) | ##### Returns `Promise`\<[`Volume`](#volume)\[]> *** ## HTTP policies See [Credential injection](/sailboxes-credentials) for setup, examples, and cleanup. The entries below list the available TypeScript calls. ### Secret A value an HTTP policy can insert into matching HTTPS requests. Secrets belong to your organization. Sail never returns a stored value. Get and list calls return only the secret's name and timestamps. #### Properties | Property | Modifier | Type | Description | | ---------------------------------- | ---------- | -------- | --------------------------------------------------- | | `createdAt` | `readonly` | `Date` | When the secret was first set. | | `name` | `readonly` | `string` | The secret's name, unique within your organization. | | `updatedAt` | `readonly` | `Date` | When the secret's value last changed. | #### Methods ##### delete() > **delete**(): `Promise`\<`void`> Delete this secret. A secret cannot be deleted while an HTTP policy refers to it; throws [SecretInUseError](#secretinuseerror) until every referencing policy is deleted. Summaries from [HttpPolicy.list](#list-1) include the secret names they use. ###### Returns `Promise`\<`void`> ##### deleteByName() > `static` **deleteByName**(`name`, `options?`): `Promise`\<`void`> Delete the named secret. Same contract as [Secret.delete](#delete-1). ###### Parameters | Parameter | Type | | --------- | --------------------------------- | | `name` | `string` | | `options` | [`ClientOptions`](#clientoptions) | ###### Returns `Promise`\<`void`> ##### get() > `static` **get**(`name`, `options?`): `Promise`\<[`Secret`](#secret)> Fetch one secret's name and timestamps. The value is never returned. Throws [NotFoundError](#notfounderror) when no secret has that name. ###### Parameters | Parameter | Type | | --------- | --------------------------------- | | `name` | `string` | | `options` | [`ClientOptions`](#clientoptions) | ###### Returns `Promise`\<[`Secret`](#secret)> ##### list() > `static` **list**(`options?`): `Promise`\<[`Secret`](#secret)\[]> List your organization's secret names and timestamps, sorted by name. ###### Parameters | Parameter | Type | | --------- | --------------------------------- | | `options` | [`ClientOptions`](#clientoptions) | ###### Returns `Promise`\<[`Secret`](#secret)\[]> ##### set() > `static` **set**(`name`, `value`, `options?`): `Promise`\<[`Secret`](#secret)> Set (create or update) the named secret's value. An HTTP policy inserts it with `${secrets.NAME}`. After this call succeeds, the next matching request from any Sailbox whose attached HTTP policy uses this secret gets the new value. Names start with a letter or number and use letters, numbers, underscores, and dashes (up to 128 characters). Values cannot be empty. They can be up to 64 KiB and cannot contain ASCII control characters such as tabs or line breaks. ###### Parameters | Parameter | Type | | --------- | --------------------------------- | | `name` | `string` | | `value` | `string` | | `options` | [`ClientOptions`](#clientoptions) | ###### Returns `Promise`\<[`Secret`](#secret)> *** ### HttpPolicy Rules that shape the HTTPS requests your Sailboxes send. A policy is a named document owned by your organization. Obtain one from [HttpPolicy.create](#create) or [HttpPolicy.get](#get); do not construct it directly. The document cannot change after creation, but [HttpPolicy.rename](#rename) can change its name. #### Properties | Property | Modifier | Type | Description | | ---------------------------------- | ---------- | --------------------------------------------- | ------------------------------------------------------------------------------------ | | `createdAt` | `readonly` | `Date` | When the policy was created. | | `document` | `readonly` | [`HttpPolicyDocument`](#httppolicydocument-1) | The saved policy document: Sail's normalized form of the document given at creation. | | `id` | `readonly` | `string` | The policy's stable identifier. | | `name` | `readonly` | `string` | The policy's name (the only mutable field). | | `updatedAt` | `readonly` | `Date` | When the policy's name last changed. | #### Methods ##### delete() > **delete**(): `Promise`\<`void`> Delete the policy. A policy still attached to a Sailbox cannot be deleted; throws [HttpPolicyInUseError](#httppolicyinuseerror) until every Sailbox clears or replaces it. ###### Returns `Promise`\<`void`> ##### rename() > **rename**(`name`): `Promise`\<[`HttpPolicy`](#httppolicy)> Rename the policy and resolve the updated policy object. The document cannot change; create a new policy to change behavior. Names follow the same rules as [HttpPolicy.create](#create). ###### Parameters | Parameter | Type | | --------- | -------- | | `name` | `string` | ###### Returns `Promise`\<[`HttpPolicy`](#httppolicy)> ##### create() > `static` **create**(`name`, `document`, `options?`): `Promise`\<[`HttpPolicy`](#httppolicy)> Create a policy from `document`. Every `${secrets.NAME}` in the document must name a secret that already exists. An invalid document throws [InvalidArgumentError](#invalidargumenterror) naming the field to fix. Sail saves a normalized form of the document (for example, host names are lowercased and defaults are filled in), so reading the policy back can return a different shape with the same behavior. Policy names must contain visible text, use at most 128 characters, and cannot contain tabs, line breaks, or other control characters. Sail does not retry this call. If the connection ends before the result arrives, list policies before trying again; a second call can create a second policy. ###### Parameters | Parameter | Type | | ---------- | --------------------------------------------- | | `name` | `string` | | `document` | [`HttpPolicyDocument`](#httppolicydocument-1) | | `options` | [`ClientOptions`](#clientoptions) | ###### Returns `Promise`\<[`HttpPolicy`](#httppolicy)> ##### get() > `static` **get**(`policyIdentifier`, `options?`): `Promise`\<[`HttpPolicy`](#httppolicy)> Fetch one policy by id, document included. Throws [NotFoundError](#notfounderror) when no policy has that id. ###### Parameters | Parameter | Type | | ------------------ | --------------------------------- | | `policyIdentifier` | `string` | | `options` | [`ClientOptions`](#clientoptions) | ###### Returns `Promise`\<[`HttpPolicy`](#httppolicy)> ##### list() > `static` **list**(`options?`): `Promise`\<[`HttpPolicySummary`](#httppolicysummary)\[]> List your organization's policies as summaries, without documents. Fetch a policy's document with [HttpPolicy.get](#get). ###### Parameters | Parameter | Type | | --------- | ----------------------------------------------------- | | `options` | [`ListHttpPoliciesOptions`](#listhttppoliciesoptions) | ###### Returns `Promise`\<[`HttpPolicySummary`](#httppolicysummary)\[]> *** ## ingressAuthHeaders() > **ingressAuthHeaders**(): `Record`\<`string`, `string`> Guest-side: headers that authenticate this Sailbox as an ingress allowlist source (only available inside a Sailbox guest). ### Returns `Record`\<`string`, `string`> *** ## Client A configured Sail client: the low-level, one-method-per-operation surface (one config snapshot; env vars are read at construction). Every client operation is here. The object-model API ([Sailbox](#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`, `options?`): `Promise`\<[`ImageSpec`](#imagespec)> Resolve an image definition and build it to ready, returning the content-addressed [ImageSpec](#imagespec) to create Sailboxes from. A bare Debian or devbox base image skips the build; `timeoutSeconds` bounds the whole pipeline (hashing, uploads, and the build). By default, Sail may reuse an existing ready build for this definition. `forceBuild` builds it again and waits for the fresh build to become ready: new Sailboxes use the fresh image once it is ready, Sailboxes that already exist keep the filesystem they were created with, and a forced build that fails changes nothing. For an image imported with [Image.fromRegistry](#fromregistry) through a tag, a forced build also asks the registry what the tag points at now and builds that version. The tag then means that version for your whole organization, while specs built earlier keep their pinned version. A forced build of an image built with [Image.fromDockerfile](#fromdockerfile) looks up the tags its `FROM` and `COPY --from` instructions name and moves those pins for your whole organization, while specs built earlier keep the versions their build used. If forced builds overlap, the last-requested one that succeeds decides which image new Sailboxes use and, for a tag, what the tag means. ##### Parameters | Parameter | Type | | --------------------- | ------------------------------------- | | `def` | [`ImageDefinition`](#imagedefinition) | | `timeoutSeconds` | `number` | | `options` | \{ `forceBuild?`: `boolean`; } | | `options.forceBuild?` | `boolean` | ##### Returns `Promise`\<[`ImageSpec`](#imagespec)> #### buildSpecToReady() > **buildSpecToReady**(`spec`, `timeoutSeconds`, `options?`): `Promise`\<[`ImageBuild`](#imagebuild-1)> Build an already-resolved spec to ready (submit + poll), bounded by `timeoutSeconds`. `forceBuild` builds the image again even if a build already exists; see [Client.buildImageDefinition](#buildimagedefinition). ##### Parameters | Parameter | Type | | --------------------- | ------------------------------ | | `spec` | [`ImageSpec`](#imagespec) | | `timeoutSeconds` | `number` | | `options` | \{ `forceBuild?`: `boolean`; } | | `options.forceBuild?` | `boolean` | ##### 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)> #### clearSailboxHttpPolicy() > **clearSailboxHttpPolicy**(`sailboxId`): `Promise`\<`void`> Clear a Sailbox's attached HTTP policy. The change applies to HTTPS connections the Sailbox opens after the call; connections already open keep the previous policy until they close. This also succeeds when no policy is attached. ##### Parameters | Parameter | Type | | ----------- | -------- | | `sailboxId` | `string` | ##### Returns `Promise`\<`void`> #### createFromCheckpoint() > **createFromCheckpoint**(`params`): `Promise`\<[`SailboxHandle`](#sailboxhandle)> Create a new Sailbox from a checkpoint. ##### Parameters | Parameter | Type | | --------- | ------------------------------------------------- | | `params` | [`FromCheckpointRequest`](#fromcheckpointrequest) | ##### Returns `Promise`\<[`SailboxHandle`](#sailboxhandle)> #### createHttpPolicy() > **createHttpPolicy**(`name`, `document`): `Promise`\<[`HttpPolicyInfo`](#httppolicyinfo)> Create an HTTP policy from JSON-encoded text. The document cannot change after creation. Most callers should use [HttpPolicy.create](#create), which accepts an object and documents the name rules. ##### Parameters | Parameter | Type | | ---------- | -------- | | `name` | `string` | | `document` | `string` | ##### Returns `Promise`\<[`HttpPolicyInfo`](#httppolicyinfo)> #### createSailbox() > **createSailbox**(`req`, `timeoutSeconds?`): `Promise`\<[`SailboxHandle`](#sailboxhandle)> Create a Sailbox. `timeoutSeconds` bounds each create attempt (default 600s); pass `0` for no client-side timeout. A timed-out attempt is retried, and a retry usually reattaches to the Sailbox already coming up rather than starting another. When the overall budget is exhausted the Sailbox may still be coming up server-side: find or terminate it by `name`. `image` defaults to a plain Debian base. ##### Parameters | Parameter | Type | Default value | | ---------------- | ----------------------------------------------- | ------------- | | `req` | [`CreateSailboxRequest`](#createsailboxrequest) | `undefined` | | `timeoutSeconds` | `number` | `600` | ##### Returns `Promise`\<[`SailboxHandle`](#sailboxhandle)> #### deleteHttpPolicy() > **deleteHttpPolicy**(`policyId`): `Promise`\<`void`> Delete an HTTP policy by id. While the policy is attached to a Sailbox, the call fails with a 409 [ApiError](#apierror) ([HttpPolicy.delete](#delete) maps that to [HttpPolicyInUseError](#httppolicyinuseerror)). ##### Parameters | Parameter | Type | | ---------- | -------- | | `policyId` | `string` | ##### Returns `Promise`\<`void`> #### deleteSecret() > **deleteSecret**(`name`): `Promise`\<`void`> Delete a secret by name. While an HTTP policy refers to it, the call fails with a 409 [ApiError](#apierror) ([Secret.delete](#delete-1) maps that to [SecretInUseError](#secretinuseerror)). ##### Parameters | Parameter | Type | | --------- | -------- | | `name` | `string` | ##### Returns `Promise`\<`void`> #### deleteVolume() > **deleteVolume**(`volumeId`, `allowMissing?`): `Promise`\<[`VolumeInfo`](#volumeinfo) | `null`> Delete a volume by id. `allowMissing` tolerates an already-deleted volume, resolving `null` instead of throwing. ##### Parameters | Parameter | Type | Default value | | -------------- | --------- | ------------- | | `volumeId` | `string` | `undefined` | | `allowMissing` | `boolean` | `false` | ##### Returns `Promise`\<[`VolumeInfo`](#volumeinfo) | `null`> #### downloadDir() > **downloadDir**(`sailboxId`, `dirs`): `Promise`\<`void`> Download a guest directory's contents into a local directory, named in `dirs`. ##### Parameters | Parameter | Type | | --------------- | ------------------------------------------------ | | `sailboxId` | `string` | | `dirs` | \{ `guestDir`: `string`; `localDir`: `string`; } | | `dirs.guestDir` | `string` | | `dirs.localDir` | `string` | ##### Returns `Promise`\<`void`> #### enableSsh() > **enableSsh**(`sailboxId`, `options?`): `Promise`\<[`SshEndpoint`](#sshendpoint) | `null`> Enable SSH on a Sailbox: trust the org SSH CA, start `sshd`, and expose guest port 22 as TCP once the CA-only daemon owns it. A non-empty `allowlist` restricts port 22 to those source addresses or ranges, replacing any existing restriction. With `wait` (the default), polls until the endpoint is reachable and returns it, throwing [TimeoutError](#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. By default a stream you are consuming pauses the command when you fall behind, so nothing is lost until a cancel or the exec timeout ends the pauses, and a stream you are not consuming keeps only its most recent 1 MiB; `outputMode` and `outputBufferBytes` change that (see [ExecProcess](#execprocess) and [ExecOptions](#execoptions)). `cwd`/`background` apply to string commands (see [ExecOptions](#execoptions)). Stopping the command is the caller's job via [ExecProcess.cancel](#cancel). ##### Parameters | Parameter | Type | | ----------- | -------------------------------- | | `sailboxId` | `string` | | `command` | `string` \| readonly `string`\[] | | `options` | [`ExecOptions`](#execoptions) | ##### Returns `Promise`\<[`ExecProcess`](#execprocess)> #### exposeListener() > **exposeListener**(`sailboxId`, `guestPort`, `protocol?`, `allowlist?`): `Promise`\<[`Listener`](#listener-1)> Expose a guest port at runtime. Re-exposing a port under the same protocol sets its `allowlist` to what you pass, so pass the whole list every time; an empty one clears the restriction and reopens the port. The route status starts "unknown": the response confirms configuration, not reachability. ##### Parameters | Parameter | Type | Default value | | ----------- | ------------------------------------- | ------------- | | `sailboxId` | `string` | `undefined` | | `guestPort` | `number` | `undefined` | | `protocol` | [`IngressProtocol`](#ingressprotocol) | `"http"` | | `allowlist` | readonly `string`\[] | `[]` | ##### Returns `Promise`\<[`Listener`](#listener-1)> #### findApp() > **findApp**(`name`, `mintIfMissing?`): `Promise`\<[`AppInfo`](#appinfo)> Find an app by name; `mintIfMissing` creates it when absent. ##### Parameters | Parameter | Type | Default value | | --------------- | --------- | ------------- | | `name` | `string` | `undefined` | | `mintIfMissing` | `boolean` | `false` | ##### Returns `Promise`\<[`AppInfo`](#appinfo)> #### getHttpPolicy() > **getHttpPolicy**(`policyId`): `Promise`\<[`HttpPolicyInfo`](#httppolicyinfo)> Fetch one HTTP policy by id, including its document. ##### Parameters | Parameter | Type | | ---------- | -------- | | `policyId` | `string` | ##### Returns `Promise`\<[`HttpPolicyInfo`](#httppolicyinfo)> #### getListener() > **getListener**(`sailboxId`, `guestPort`): `Promise`\<[`Listener`](#listener-1)> Fetch one listener by guest port without waking the Sailbox. ##### 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)> #### getSecret() > **getSecret**(`name`): `Promise`\<[`SecretInfo`](#secretinfo)> Fetch one secret's name and timestamps, never its value. ##### Parameters | Parameter | Type | | --------- | -------- | | `name` | `string` | ##### Returns `Promise`\<[`SecretInfo`](#secretinfo)> #### getVolume() > **getVolume**(`name`, `mintIfMissing?`): `Promise`\<[`VolumeInfo`](#volumeinfo)> Look up an NFS volume by name; `mintIfMissing` creates it when absent. ##### Parameters | Parameter | Type | Default value | | --------------- | --------- | ------------- | | `name` | `string` | `undefined` | | `mintIfMissing` | `boolean` | `false` | ##### Returns `Promise`\<[`VolumeInfo`](#volumeinfo)> #### ingressAuthHeaders() > **ingressAuthHeaders**(`sailboxId`): `Promise`\<`Record`\<`string`, `string`>> Ingress-identity headers for this Sailbox, as a name→value map. ##### Parameters | Parameter | Type | | ----------- | -------- | | `sailboxId` | `string` | ##### Returns `Promise`\<`Record`\<`string`, `string`>> #### listApps() > **listApps**(): `Promise`\<[`AppInfo`](#appinfo)\[]> Every app the current org owns, newest first. ##### Returns `Promise`\<[`AppInfo`](#appinfo)\[]> #### listDir() > **listDir**(`sailboxId`, `path`, `user?`): `Promise`\<[`DirEntry`](#direntry)\[]> List a directory's immediate entries as structured records. ##### Parameters | Parameter | Type | | ----------- | -------- | | `sailboxId` | `string` | | `path` | `string` | | `user?` | `string` | ##### Returns `Promise`\<[`DirEntry`](#direntry)\[]> #### listHttpPolicies() > **listHttpPolicies**(`params`): `Promise`\<[`HttpPolicyPage`](#httppolicypage)> List HTTP policies with paging and an optional id or name search. ##### Parameters | Parameter | Type | | ---------------- | ---------------------------------------------------------------- | | `params` | \{ `limit`: `number`; `offset`: `number`; `search?`: `string`; } | | `params.limit` | `number` | | `params.offset` | `number` | | `params.search?` | `string` | ##### Returns `Promise`\<[`HttpPolicyPage`](#httppolicypage)> #### 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)> #### listSecrets() > **listSecrets**(): `Promise`\<[`SecretInfo`](#secretinfo)\[]> List the organization's secret names and timestamps. ##### Returns `Promise`\<[`SecretInfo`](#secretinfo)\[]> #### listVolumes() > **listVolumes**(`maxObjects?`): `Promise`\<[`VolumeInfo`](#volumeinfo)\[]> List NFS volumes in the current org. ##### Parameters | Parameter | Type | | ------------- | -------- | | `maxObjects?` | `number` | ##### Returns `Promise`\<[`VolumeInfo`](#volumeinfo)\[]> #### makeDir() > **makeDir**(`sailboxId`, `path`, `user?`): `Promise`\<`void`> Create a directory and any missing parents (like `mkdir -p`); a no-op if it already exists. ##### Parameters | Parameter | Type | | ----------- | -------- | | `sailboxId` | `string` | | `path` | `string` | | `user?` | `string` | ##### Returns `Promise`\<`void`> #### orgSshCaPublicKey() > **orgSshCaPublicKey**(): `Promise`\<`string`> Fetch (creating on first use) the org SSH certificate authority public key. Used to preflight SSH before a Sailbox is provisioned. ##### Returns `Promise`\<`string`> #### pathExists() > **pathExists**(`sailboxId`, `path`, `user?`): `Promise`\<`boolean`> Whether `path` exists in the guest. ##### Parameters | Parameter | Type | | ----------- | -------- | | `sailboxId` | `string` | | `path` | `string` | | `user?` | `string` | ##### Returns `Promise`\<`boolean`> #### pauseSailbox() > **pauseSailbox**(`sailboxId`): `Promise`\<`void`> Pause a Sailbox in memory. ##### Parameters | Parameter | Type | | ----------- | -------- | | `sailboxId` | `string` | ##### Returns `Promise`\<`void`> #### readStream() > **readStream**(`sailboxId`, `path`): `Promise`\<[`FileStream`](#filestream)> Open a streaming read of a guest file. ##### Parameters | Parameter | Type | | ----------- | -------- | | `sailboxId` | `string` | | `path` | `string` | ##### Returns `Promise`\<[`FileStream`](#filestream)> #### removePath() > **removePath**(`sailboxId`, `path`, `user?`): `Promise`\<`void`> Remove a file or directory tree (like `rm -rf`); a no-op if it is already absent. ##### Parameters | Parameter | Type | | ----------- | -------- | | `sailboxId` | `string` | | `path` | `string` | | `user?` | `string` | ##### Returns `Promise`\<`void`> #### renameHttpPolicy() > **renameHttpPolicy**(`policyId`, `name`): `Promise`\<[`HttpPolicyInfo`](#httppolicyinfo)> Rename an HTTP policy. Its document stays unchanged. Names follow the same rules as [HttpPolicy.create](#create). ##### Parameters | Parameter | Type | | ---------- | -------- | | `policyId` | `string` | | `name` | `string` | ##### Returns `Promise`\<[`HttpPolicyInfo`](#httppolicyinfo)> #### resolveImage() > **resolveImage**(`def`): `Promise`\<[`ImageSpec`](#imagespec)> Resolve an image definition into a content-addressed [ImageSpec](#imagespec): the SDK walks local directories (gitignore-style `ignore`), hashes every file, and uploads content the server does not already have. ##### Parameters | Parameter | Type | | --------- | ------------------------------------- | | `def` | [`ImageDefinition`](#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)> #### sailboxHttpPolicy() > **sailboxHttpPolicy**(`sailboxId`): `Promise`\<[`HttpPolicyInfo`](#httppolicyinfo) | `null`> The HTTP policy attached to a Sailbox, or `null` when none is attached. ##### Parameters | Parameter | Type | | ----------- | -------- | | `sailboxId` | `string` | ##### Returns `Promise`\<[`HttpPolicyInfo`](#httppolicyinfo) | `null`> #### setSailboxAutoSleep() > **setSailboxAutoSleep**(`sailboxId`, `autoSleep`): `Promise`\<`void`> Replace when Sail may sleep a Sailbox on its own. Each call replaces the whole setting: switching to `{ automatic: false }` clears any minimum wait set earlier. Most callers use [Sailbox.setAutoSleep](#setautosleep). ##### Parameters | Parameter | Type | | ----------- | --------------------------- | | `sailboxId` | `string` | | `autoSleep` | [`AutoSleep`](#autosleep-4) | ##### Returns `Promise`\<`void`> #### setSailboxHttpPolicy() > **setSailboxHttpPolicy**(`sailboxId`, `policyId`): `Promise`\<`void`> Attach an HTTP policy to a Sailbox, replacing any previous one. The policy applies to HTTPS connections the Sailbox opens after the call; connections already open keep the previous policy until they close. ##### Parameters | Parameter | Type | | ----------- | -------- | | `sailboxId` | `string` | | `policyId` | `string` | ##### Returns `Promise`\<`void`> #### setSecret() > **setSecret**(`name`, `value`): `Promise`\<[`SecretInfo`](#secretinfo)> Set (create or update) an organization secret. Sail never returns the stored value. After this resolves, the next matching request from a Sailbox whose attached HTTP policy uses the secret gets the new value. Names and values follow the same rules as [Secret.set](#set). ##### Parameters | Parameter | Type | | --------- | -------- | | `name` | `string` | | `value` | `string` | ##### Returns `Promise`\<[`SecretInfo`](#secretinfo)> #### shell() > **shell**(`sailboxId`, `command?`, `options?`): `Promise`\<`number`> Open an interactive pty session on a Sailbox, bridged to the local terminal: raw keystrokes reach the remote process, output renders locally, and resizes propagate. Resolves with the remote process's exit code. Requires an interactive terminal (stdin and stdout TTYs). ##### Parameters | Parameter | Type | | ----------- | ------------------------------- | | `sailboxId` | `string` | | `command?` | `string` | | `options?` | [`ShellOptions`](#shelloptions) | ##### Returns `Promise`\<`number`> #### sleepSailbox() > **sleepSailbox**(`sailboxId`, `wakeAt?`): `Promise`\<`string` | `null`> Sleep a Sailbox to disk (wakes on traffic), optionally scheduling a wall-clock wake first. `wakeAt` is an RFC 3339 timestamp; the returned value is the effective (sooner) wake time, or null when no wake was requested. Most callers use [Sailbox.sleep](#sleep), which takes and returns `Date`. ##### Parameters | Parameter | Type | | ----------- | -------- | | `sailboxId` | `string` | | `wakeAt?` | `string` | ##### Returns `Promise`\<`string` | `null`> #### terminateSailbox() > **terminateSailbox**(`sailboxId`): `Promise`\<`void`> Terminate a Sailbox (idempotent). ##### Parameters | Parameter | Type | | ----------- | -------- | | `sailboxId` | `string` | ##### Returns `Promise`\<`void`> #### unexposeListener() > **unexposeListener**(`sailboxId`, `guestPort`): `Promise`\<`void`> Remove a runtime ingress port. ##### Parameters | Parameter | Type | | ----------- | -------- | | `sailboxId` | `string` | | `guestPort` | `number` | ##### Returns `Promise`\<`void`> #### upgradeSailbox() > **upgradeSailbox**(`sailboxId`): `Promise`\<[`UpgradeResult`](#upgraderesult)> Upgrade a Sailbox's runtime (now if running, else at next wake). ##### Parameters | Parameter | Type | | ----------- | -------- | | `sailboxId` | `string` | ##### Returns `Promise`\<[`UpgradeResult`](#upgraderesult)> #### uploadDir() > **uploadDir**(`sailboxId`, `dirs`): `Promise`\<`void`> Upload a local directory's contents into a guest directory, named in `dirs`. `user` gives the uploaded entries to that user instead of the image's `USER`. ##### Parameters | Parameter | Type | | --------------- | ------------------------------------------------------------------- | | `sailboxId` | `string` | | `dirs` | \{ `guestDir`: `string`; `localDir`: `string`; `user?`: `string`; } | | `dirs.guestDir` | `string` | | `dirs.localDir` | `string` | | `dirs.user?` | `string` | ##### Returns `Promise`\<`void`> #### waitForListener() > **waitForListener**(`sailboxId`, `guestPort`, `timeoutSeconds`): `Promise`\<[`Listener`](#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` | ##### Returns `Promise`\<[`Listener`](#listener-1)> #### writeFiles() > **writeFiles**(`sailboxId`, `files`, `options?`): `Promise`\<`void`> Write several complete files in one call, up to eight at a time, stopping at the first failure. ##### Parameters | Parameter | Type | | ----------- | ---------------------------------------------------------------------- | | `sailboxId` | `string` | | `files` | `Readonly`\<`Record`\<`string`, `Buffer` \| `Uint8Array` \| `string`>> | | `options` | [`WriteOptions`](#writeoptions) | ##### Returns `Promise`\<`void`> #### 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) *** ## 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) *** ## 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` *** ## 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. This is the same resolution a client performs at construction. ### Returns [`ResolvedConfig`](#resolvedconfig) *** ## isSailError() > **isSailError**(`err`): `err is SailError` Whether `err` is a [SailError](#sailerror), matched on the stable shape (`code` string plus `retryable` boolean) rather than the prototype chain. Use it where `instanceof` can lie: across realms (worker threads, `vm` contexts) or when two copies of the SDK are loaded. It does not survive `structuredClone` or `postMessage` serialization, which strip an Error's custom fields; send `{ name, message, code, retryable }` yourself when an error must cross a serialization boundary. ### Parameters | Parameter | Type | | --------- | --------- | | `err` | `unknown` | ### Returns `err is SailError` ## Types Plain data types accepted by and returned from the calls above. ### AddLocalDir A tree of local files copied into the image. #### Properties | Property | Type | Description | | ----------------------------------- | ---------------------------------------- | ------------------------------------------ | | `files?` | [`AddLocalDirFile`](#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?` | readonly `string`\[] | Gitignore-style patterns to skip (e.g. `"*.pyc"`, `"__pycache__/"`). | | `ignoreFile?` | `string` | A gitignore-style file whose patterns to skip (e.g. `.gitignore`). | *** ### AddLocalFile One local file copied into the image, referenced by content hash. #### Properties | Property | Type | Description | | ------------------------------------------- | -------- | ------------------------------------------------------------ | | `contentSha256?` | `string` | SHA-256 of the (already uploaded) file content. | | `mode?` | `number` | Permission bits (low 9); 0 means the builder default (0644). | | `remotePath?` | `string` | Absolute guest path to place the file at. | *** ### AddLocalFileOptions Options for [Image.addLocalFile](#addlocalfile). #### Properties | Property | Type | Description | | ------------------------- | -------- | ---------------------------------------------------------------- | | `mode?` | `number` | Unix mode bits (low 9); omitted uses the builder default (0644). | *** ### AppInfo A Sail app. #### Properties | Property | Type | Description | | ---------------------------------- | -------- | ------------------------- | | `createdAt` | `string` | Creation time (RFC 3339). | | `id` | `string` | Stable app id. | | `name` | `string` | App name. | *** ### AutoSleep > **AutoSleep** = [`AutomaticSleep`](#automaticsleep) | [`NeverSleep`](#neversleep) When Sail may put a Sailbox to sleep on its own. Sail sleeps Sailboxes that are doing nothing, freeing their memory and waking them the moment anything needs them again. Waking takes a couple of seconds: free for a batch job, unwelcome if someone is waiting at a terminal. An explicit idle window replaces Sail's default and can make automatic sleep happen sooner or later. The window only controls when Sail may consider sleeping the Sailbox. Sail still sleeps it only when it sits fully idle: no busy process, no imminent timer, nothing a sleep would interrupt. Calling `sleep()` yourself is unaffected, and so are `pause`, `resume`, and scheduled wakes. The two forms are alternatives, so `minSecondsBeforeSleep` cannot be combined with turning automatic sleep off. *** ### AutomaticSleep Let Sail decide when to sleep a Sailbox, optionally after a minimum wait. #### Properties | Property | Modifier | Type | Description | | --------------------------------------------------------- | ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `automatic?` | `readonly` | `true` | Sail decides when to sleep it. | | `minSecondsBeforeSleep?` | `readonly` | `number` | Use this idle window instead of Sail's default. Once it passes, Sail may sleep the Sailbox only when it is fully idle. Whole-second values from 1 through 3600 are accepted; 0 restores Sail's default, and other numeric values are rejected. | *** ### BaseImage > **BaseImage** = `"debian"` | `"devbox"` *** ### CancelOptions Options for cancelling an exec. #### Properties | Property | Type | Description | | ------------------------- | --------- | ------------------------------- | | `force?` | `boolean` | Send SIGKILL instead of SIGINT. | *** ### CheckpointOptions Options for [Sailbox.checkpoint](#checkpoint). #### Properties | Property | Type | Description | | ----------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name?` | `string` | Display name for the checkpoint handle. | | `ttlSeconds?` | `number` | Retention override in whole seconds (must be positive). Set it when you keep a checkpoint to reuse as a template, so the handle does not expire while you still need it; omitted uses the server default. | *** ### ClientConfig Explicit client configuration (an alternative to environment resolution). #### Extends * `Omit`\<`native.ClientConfig`, `"mode"`> #### Properties | Property | Type | Description | Inherited from | | ----------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | | `apiKey` | `string` | Bearer API key. Required. | `Omit.apiKey` | | `apiUrl?` | `string` | Override the Sail API URL. | `Omit.apiUrl` | | `ingressUrl?` | `string` | Override the listener ingress base URL (what `SAILBOX_INGRESS_URL` sets from the environment), for custom or self-hosted Sailbox stacks. | `Omit.ingressUrl` | | `sailboxApiUrl?` | `string` | Override the Sailbox-API URL. | `Omit.sailboxApiUrl` | *** ### ClientOptions Options for statics that select which [Client](#client) to use. #### Extended by * [`FindAppOptions`](#findappoptions) * [`FindVolumeOptions`](#findvolumeoptions) * [`ListVolumesOptions`](#listvolumesoptions) * [`ListHttpPoliciesOptions`](#listhttppoliciesoptions) * [`CreateSailboxOptions`](#createsailboxoptions) * [`FromCheckpointOptions`](#fromcheckpointoptions) * [`ListSailboxesOptions`](#listsailboxesoptions) * [`ListSailboxesPageOptions`](#listsailboxespageoptions) #### Properties | Property | Type | Description | | ----------------------------- | ------------------- | ------------------------------------------------------- | | `client?` | [`Client`](#client) | Use a specific client instead of the default (env) one. | *** ### CreateSailboxOptions Options for [Sailbox.create](#create-1): the create request plus a per-attempt timeout and an optional explicit client. `image` defaults to the prebuilt Debian base. #### Extends * `Omit`\<[`CreateSailboxRequest`](#createsailboxrequest), `"image"` | `"appId"` | `"volumeMounts"` | `"ingressPorts"` | `"visibility"`>.[`ClientOptions`](#clientoptions) #### Properties | Property | Type | Description | Overrides | Inherited from | | --------------------------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------- | | `app` | `string` \| [`App`](#app) | The owning app, or its id. | - | - | | `autoSleep?` | [`AutoSleep`](#autosleep-4) | When Sail may sleep this Sailbox on its own. Omit for the default. | - | [`CreateSailboxRequest`](#createsailboxrequest).[`autoSleep`](#autosleep-2) | | `client?` | [`Client`](#client) | Use a specific client instead of the default (env) one. | - | [`ClientOptions`](#clientoptions).[`client`](#client-2) | | `diskLimitGib?` | `number` | Disk limit in whole GiB within the size's range; the size's default when omitted. | - | `Omit.diskLimitGib` | | `image?` | [`ImageSpec`](#imagespec) \| [`Image`](#image) | Image spec, or an [Image](#image) builder (built and resolved at create). Defaults to the prebuilt Debian base, which needs no image build. | - | - | | `imageBuildTimeoutSeconds?` | `number` | Timeout in seconds for building a custom `Image` before create (1800). | `Omit.imageBuildTimeoutSeconds` | - | | `ingressPorts?` | readonly (`number` \| [`IngressPortInput`](#ingressportinput))\[] | Guest ports to expose: a bare number is HTTP shorthand. | - | - | | `memoryLimitGib?` | `number` | Memory limit in whole GiB within the size's range; the size's default when omitted. | - | `Omit.memoryLimitGib` | | `name` | `string` | The Sailbox name. | - | `Omit.name` | | `networkPolicy?` | [`NetworkPolicy`](#networkpolicy-4) | The Sailbox's network policy. Omit for `"public"`. | - | [`CreateSailboxRequest`](#createsailboxrequest).[`networkPolicy`](#networkpolicy-2) | | `size?` | [`SailboxSize`](#sailboxsize) | Resource size; `"m"` when omitted. | - | [`CreateSailboxRequest`](#createsailboxrequest).[`size`](#size-1) | | `timeoutSeconds?` | `number` | Bounds each create attempt (default 600s); pass `0` for no client-side timeout. A timed-out attempt is retried, and a retry usually reattaches to the Sailbox already coming up rather than starting another. When the overall budget is exhausted the Sailbox may still be coming up server-side: find or terminate it by `name`. | - | - | | `visibility?` | `"org"` \| `"private"` | Who may operate the Sailbox, fixed for its life. `"org"` (the default) lets any credential in your org exec, copy files, SSH, or run lifecycle operations on it; `"private"` restricts all of that to you. An org admin can override a private Sailbox with a recorded reason for exec, files, setting a wake time, and the pause, sleep, resume, terminate, and upgrade operations. SSH, exposing or removing listeners, checkpoint, and restore stay creator-only. `"private"` requires an API key minted by your user. SSH is enabled after create with [Sailbox.enableSsh](#enablessh-1). | - | - | | `volumes?` | `Readonly`\<`Record`\<`string`, `string` \| [`Volume`](#volume)>> | Shared volumes to mount, mapping an absolute guest path to a [Volume](#volume) or volume id. Volumes are currently in Alpha. To pilot them, reach out in the Sail Slack: [https://join.slack.com/t/sailresearchcrew/shared\_invite/zt-41pdcym9j-UU0Ey\~A\~r6n2H0DQVQsQHQ](https://join.slack.com/t/sailresearchcrew/shared_invite/zt-41pdcym9j-UU0Ey~A~r6n2H0DQVQsQHQ). | - | - | *** ### CreateSailboxRequest #### Extends * `Omit`\<`native.CreateSailboxRequest`, `"image"` | `"ingressPorts"` | `"size"` | `"volumeMounts"` | `"autoSleep"` | `"networkPolicy"` | `"visibility"` | `"networkAllowedHosts"`> #### Properties | Property | Type | Description | Inherited from | | ----------------------------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | | `appId` | `string` | Identifier of the owning app. | `Omit.appId` | | `autoSleep?` | [`AutoSleep`](#autosleep-4) | When Sail may sleep this Sailbox on its own. Omit for the default. | - | | `diskLimitGib?` | `number` | Disk limit in whole GiB within the size's range; the size's default when omitted. | `Omit.diskLimitGib` | | `image?` | [`ImageSpec`](#imagespec) | Image to boot; defaults to a plain Debian base when omitted. | - | | `imageBuildTimeoutSeconds?` | `number` | Budget in seconds for rebuilding the image if Sail needs to rebuild it before the Sailbox is created; the default build budget applies when omitted. | `Omit.imageBuildTimeoutSeconds` | | `ingressPorts?` | readonly [`IngressPortInput`](#ingressportinput)\[] | Guest ports to reserve for ingress. | - | | `memoryLimitGib?` | `number` | Memory limit in whole GiB within the size's range; the size's default when omitted. | `Omit.memoryLimitGib` | | `name` | `string` | The Sailbox name. | `Omit.name` | | `networkPolicy?` | [`NetworkPolicy`](#networkpolicy-4) | The Sailbox's network policy. Omit for `"public"`. | - | | `size?` | [`SailboxSize`](#sailboxsize) | Resource size; `"m"` when omitted. | - | | `visibility?` | `"org"` \| `"private"` | Who may operate the Sailbox: `"org"` (the default) lets any credential in your org exec, copy files, SSH, or run lifecycle operations on it; `"private"` restricts all of that to the creating user and requires a user-scoped API key. Fixed for the Sailbox's life. | - | | `volumeMounts?` | readonly [`VolumeMountInput`](#volumemountinput)\[] | NFS volumes to mount. | - | *** ### DeleteVolumeOptions Options for [Volume.delete](#delete-2). #### Properties | Property | Type | Description | | --------------------------------------- | --------- | ----------------------------------------------------------- | | `allowMissing?` | `boolean` | Tolerate a volume that is already gone instead of throwing. | *** ### DirEntry One entry in a directory listing from `Sailbox.fs.ls`, with `type` narrowed to [DirEntryType](#direntrytype-1). #### Extends * `Omit`\<`native.DirEntry`, `"type"`> #### Properties | Property | Type | Description | Inherited from | | -------------------------------------- | --------------------------------- | --------------------------------------------------------------------------- | ------------------- | | `mode` | `number` | Unix permission bits, e.g. `0o644`. The file-type bits are not included. | `Omit.mode` | | `modifiedTime` | `number` | Last-modified time as a Unix timestamp in seconds (with a fractional part). | `Omit.modifiedTime` | | `name` | `string` | The entry's base name, with no directory prefix. | `Omit.name` | | `size` | `number` | Size in bytes as reported by the guest. | `Omit.size` | | `type` | [`DirEntryType`](#direntrytype-1) | - | - | *** ### DirEntryType > **DirEntryType** = `"file"` | `"directory"` | `"symlink"` | `"other"` The kind of a directory entry, reported for the entry itself: a symlink is `"symlink"` regardless of what it points at. *** ### DockerfileContextDir One directory of a Dockerfile build context. #### Properties | Property | Type | Description | | ----------------------------------------- | -------- | ----------------------------------------------------------------- | | `mode?` | `number` | Directory mode permission bits; omitted means the default (0755). | | `relativePath?` | `string` | Slash-separated path relative to the context root. | *** ### DockerfileContextSymlink One symbolic link of a Dockerfile build context. #### Properties | Property | Type | Description | | ----------------------------------------- | -------- | ------------------------------------------------------------------------------------- | | `relativePath?` | `string` | Slash-separated path relative to the context root. | | `target?` | `string` | Raw link target, exactly as the link stores it; resolved only inside the built image. | *** ### DockerfileFromResolution What one external image reference in a Dockerfile resolved to when an image was built. #### Properties | Property | Type | Description | | --------------------------------- | -------- | ------------------------------------------------------------------- | | `digestRef?` | `string` | The digest-pinned form of the same reference the build used. | | `reference?` | `string` | The reference as the Dockerfile's `FROM` or `COPY --from` names it. | *** ### DockerfileImage Your own Dockerfile built into an image, with its resolved build context. A `RUN --mount` of type `cache`, `secret`, or `ssh`, a `bind` mount reading from another image, mount options that are not literal text, and `ONBUILD` instructions are rejected. #### Properties | Property | Type | Description | | --------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `buildArgs?` | `Record`\<`string`, `string`> | Values for the Dockerfile's `ARG` instructions, like `--build-arg`. Names may not start with the reserved `BUILDKIT_` prefix, and Docker's proxy names (`HTTP_PROXY`, `HTTPS_PROXY`, `FTP_PROXY`, `NO_PROXY`, `ALL_PROXY`, in any letter case) are rejected; a step that needs a proxy can set one inside its `RUN` command. | | `contextDirs?` | [`DockerfileContextDir`](#dockerfilecontextdir)\[] | Every directory in the context with its mode, so `COPY` of an empty directory works and directory modes survive like they do in a docker build. | | `contextFiles?` | [`AddLocalDirFile`](#addlocaldirfile)\[] | Content manifest of the build context the Dockerfile's `COPY` and `ADD` instructions read from; empty builds without a context. | | `contextSymlinks?` | [`DockerfileContextSymlink`](#dockerfilecontextsymlink)\[] | Symbolic links in the context, carried as links the way a docker build context carries them. | | `dockerfile?` | `string` | Full Dockerfile text. | | `pinnedFrom?` | [`DockerfileFromResolution`](#dockerfilefromresolution)\[] | The version each external image reference resolved to when this spec was built, filled in on the spec a completed build returns. A spec carrying these keeps naming the image its build produced, even after a forced build moves what the references mean for your organization; a forced build looks every reference up again instead. | *** ### DockerfileSourceInput A Dockerfile to build into the image, with its local build context. A `RUN --mount` of type `cache`, `secret`, or `ssh`, a `bind` mount reading from another image, mount options that are not literal text, and `ONBUILD` instructions are rejected. #### Properties | Property | Type | Description | | ------------------------------------ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `buildArgs?` | `Record`\<`string`, `string`> | Values for the Dockerfile's `ARG` instructions, like `--build-arg`. Names may not start with the reserved `BUILDKIT_` prefix, and Docker's proxy names (`HTTP_PROXY`, `HTTPS_PROXY`, `FTP_PROXY`, `NO_PROXY`, `ALL_PROXY`, in any letter case) are rejected; a step that needs a proxy can set one inside its `RUN` command. | | `contextDir?` | `string` | Local directory the Dockerfile's `COPY` and `ADD` instructions read from; if omitted, the build runs without a context. | | `dockerfile` | `string` | Path to a Dockerfile on this machine, or with `isContents` its full contents. | | `ignore?` | `string`\[] | `.dockerignore`-style patterns to skip in the context directory, applied after the `.dockerignore` rules in effect so they take precedence on conflict. | | `isContents?` | `boolean` | Read `dockerfile` as literal Dockerfile text instead of a path. | *** ### EnableSshOptions Options for enabling SSH on a Sailbox. #### Properties | Property | Type | Description | | --------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `allowlist?` | readonly `string`\[] | Source addresses or ranges allowed to reach port 22, replacing any existing restriction. Left empty, a first enable opens the port to any source, and a re-enable leaves an existing restriction unchanged. | | `timeoutSeconds?` | `number` | Give up waiting after this many seconds (default 60; `Infinity` waits indefinitely). | | `wait?` | `boolean` | Poll until the SSH route is ready (default true). | *** ### ExecOptions #### Extends * `Omit`\<`native.ExecStartOptions`, `"env"` | `"outputMode"` | `"pty"` | `"term"` | `"cols"` | `"rows"`> #### Properties | Property | Type | Description | Inherited from | | ------------------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | | `background?` | `boolean` | Detach the command so it keeps running and the call returns immediately; output is discarded (shell commands only, incompatible with `openStdin`/`pty`). | `Omit.background` | | `cwd?` | `string` | Working directory to run the command in (shell commands only). Unset starts the command in the image's working directory, or `/` when the image does not set one. | `Omit.cwd` | | `env?` | `Readonly`\<`Record`\<`string`, `string`>> | Extra environment for the command. Entries override the guest's defaults (including `LANG` and the `IS_SANDBOX=1` sandbox marker) and the image env, but a few reserved variables that identify the Sailbox (such as `SAILBOX_ID`) cannot be overridden. | - | | `idempotencyKey?` | `string` | Stable key so a reconnect reattaches to the same command. An exec has one live handle at a time: a second handle started with the same key takes over the stream, and the first stops receiving live output and resolves from a bounded recorded result. A first handle reconnecting after a dropped connection can race a handle that attached meanwhile, and either handle's result may come back incomplete; avoid overlapping same-key handles. The UTF-8 value can be up to 256 KiB. | `Omit.idempotencyKey` | | `openStdin?` | `boolean` | Leave stdin open for `writeStdin`. | `Omit.openStdin` | | `outputBufferBytes?` | `number` | Size of each stream's output buffer in bytes, 1 MiB by default. Must be between 64 KiB and 64 MiB. | `Omit.outputBufferBytes` | | `outputMode?` | [`OutputMode`](#outputmode-1) | What happens when a stream's output buffer fills; see [OutputMode](#outputmode-1). `"auto"` by default. | - | | `pty?` | `boolean` \| [`PtyConfig`](#ptyconfig) | Run the command under a pseudo-terminal: `true` for the default terminal, or a [PtyConfig](#ptyconfig) to set `term` and the initial window. `isatty()` is true, control bytes on stdin become signals, stdout and stderr merge onto one stream, and `resize` adjusts the window. Implies `openStdin`. | - | | `timeoutSeconds?` | `number` | Wall-clock limit in seconds before the server kills the command. | `Omit.timeoutSeconds` | | `user?` | `string` | Run the command as this guest user: a user name or numeric uid, optionally with a group appended after a colon (`"alice"`, `"1000"`, `"alice:staff"`, the Docker `USER` syntax). A named user must exist in the Sailbox's `/etc/passwd`; a numeric uid need not. `HOME` (and `USER`/`LOGNAME` when a name resolves) default to the resolved account, with `env` entries still winning. When unset, commands run as the image's `USER` if the image sets one, root otherwise; pass `"0:0"` to force root (`"root"` is a user name like any other, resolved through the Sailbox's `/etc/passwd`). Sailboxes created before user support shipped must call `upgrade()` once first; until then such execs fail rather than run as root. The exact spelling `"0:0"` needs no upgrade. | `Omit.user` | *** ### ExecResult The result of a finished exec. `stdout` and `stderr` hold only each stream's buffer, its most recent output (`outputBufferBytes`, 1 MiB by default). To get every byte, consume the live stream right after `exec()` returns; see `ExecProcess` for how consuming a stream affects the command. #### Properties | Property | Type | Description | | -------------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------- | | `exitCode` | `number` | The command's exit code. | | `stderr` | `string` | The most recent standard error, up to the exec's buffer size (1 MiB by default; see `stderrTruncated`). | | `stderrTruncated` | `boolean` | The command wrote more stderr than `stderr` holds, so older bytes are missing. | | `stdout` | `string` | The most recent standard output, up to the exec's buffer size (1 MiB by default; see `stdoutTruncated`). | | `stdoutTruncated` | `boolean` | The command wrote more stdout than `stdout` holds, so older bytes are missing. | | `timedOut` | `boolean` | Whether the command was killed for exceeding its timeout. | *** ### ExposeOptions Options for [Sailbox.expose](#expose). #### Properties | Property | Type | Description | | ----------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `allowlist?` | readonly `string`\[] | Sources allowed to reach the port: an address or a range, or a Sail app name on an `http` listener. An app name cannot read as an address or a range, and cannot contain a `/`. An address must not carry an IPv6 zone, such as `fe80::1%eth0`, which names an interface on one machine rather than a source. Empty allows all. | | `protocol?` | [`IngressProtocol`](#ingressprotocol) | Wire protocol to expose (default `"http"`). | *** ### FindAppOptions Options for [App.find](#find). #### Extends * [`ClientOptions`](#clientoptions) #### Properties | Property | Type | Description | Inherited from | | ----------------------------------------- | ------------------- | ------------------------------------------------------- | ------------------------------------------------------- | | `client?` | [`Client`](#client) | Use a specific client instead of the default (env) one. | [`ClientOptions`](#clientoptions).[`client`](#client-2) | | `mintIfMissing?` | `boolean` | Create the app when it does not exist yet. | - | *** ### FindVolumeOptions Options for [Volume.find](#find-1). #### Extends * [`ClientOptions`](#clientoptions) #### Properties | Property | Type | Description | Inherited from | | ------------------------------------------- | ------------------- | ------------------------------------------------------- | ------------------------------------------------------- | | `client?` | [`Client`](#client) | Use a specific client instead of the default (env) one. | [`ClientOptions`](#clientoptions).[`client`](#client-2) | | `mintIfMissing?` | `boolean` | Create the volume when it does not exist yet. | - | *** ### 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. | [`FromCheckpointRequest`](#fromcheckpointrequest).[`name`](#name-11) | | `timeoutSeconds?` | `number` | Whole seconds, positive when given. Bounds the call, since restoring a checkpoint can block for many minutes while the new Sailbox queues for capacity. A call that times out fails, and the restore may still finish in the background; the new Sailbox then shows up when you list Sailboxes. Unset waits without a bound. | [`FromCheckpointRequest`](#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. | | `timeoutSeconds?` | `number` | Whole seconds, positive when given. Bounds the call, since restoring a checkpoint can block for many minutes while the new Sailbox queues for capacity. A call that times out fails, and the restore may still finish in the background; the new Sailbox then shows up when you list Sailboxes. Unset waits without a bound. | *** ### FromDockerfileOptions Options for [Image.fromDockerfile](#fromdockerfile). #### Properties | Property | Type | Description | | ----------------------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `architecture?` | [`ImageArchitecture`](#imagearchitecture) | Target CPU architecture the image is built for (default `amd64`). | | `buildArgs?` | `Readonly`\<`Record`\<`string`, `string`>> | Values for the Dockerfile's `ARG` instructions, like `--build-arg`. Names may not start with the reserved `BUILDKIT_` prefix, and Docker's proxy names (`HTTP_PROXY`, `HTTPS_PROXY`, `FTP_PROXY`, `NO_PROXY`, `ALL_PROXY`, in any letter case) are rejected; a step that needs a proxy can set one inside its `RUN` command. | | `contextDir?` | `string` | Local directory the Dockerfile's `COPY` and `ADD` instructions read from; if omitted, the build runs without a context. | | `ignore?` | readonly `string`\[] | `.dockerignore`-style patterns to skip in the context directory, applied after the `.dockerignore` rules in effect so they take precedence on conflict. | *** ### FromRegistryOptions Options for [Image.fromRegistry](#fromregistry). #### Properties | Property | Type | Description | | ----------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `architecture?` | [`ImageArchitecture`](#imagearchitecture) | Require the image to have been built for this CPU architecture. Leave it unset to use the architecture the image was built for. | *** ### FsOptions Options for the directory helpers ([SailboxFs.mkdir](#mkdir), [SailboxFs.remove](#remove), [SailboxFs.exists](#exists), [SailboxFs.ls](#ls)). #### Properties | Property | Type | Description | | | | ------------------------- | -------- | -------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `user?` | `string` | Run the operation as this user (Docker's `USER` syntax: \`name | uid\[:group | gid]`), with its permissions enforced by the guest kernel. Unset runs as root, so the helpers work on any path; `"0:0"`is always root. A`user`other than`"0:0"\` requires a Sailbox whose guest honors requested users; on older Sailboxes the operation fails until [Sailbox.upgrade](#upgrade) is called. | *** ### HttpEndpoint The routable HTTPS address of an `http` listener. #### Properties | Property | Type | Description | | ---------------------- | -------- | ----------------------------------------- | | `kind` | `"http"` | - | | `url` | `string` | The HTTPS URL to reach the guest service. | *** ### HttpPolicyAddChange > **HttpPolicyAddChange** = \{ `headers`: [`HttpPolicyValueMap`](#httppolicyvaluemap); `query?`: [`HttpPolicyValueMap`](#httppolicyvaluemap); } | \{ `headers?`: [`HttpPolicyValueMap`](#httppolicyvaluemap); `query`: [`HttpPolicyValueMap`](#httppolicyvaluemap); } Headers or query parameters to append to a request. At least one of `headers` or `query` is required, and the union encodes that, so an empty `add` is a compile error. *** ### HttpPolicyDocument > **HttpPolicyDocument** = `object` A policy document: host patterns mapped to their rules. A key is an exact hostname (`api.example.com`), a single-label wildcard (`*.example.com`), or the catch-all `*`. Sail picks one host, most specific first, and host entries never combine. ```ts theme={null} const document: HttpPolicyDocument = { "api.example.com": { rules: [ { match: { path: { prefix: "/v1/" } }, request: { set: { headers: { authorization: "Bearer ${secrets.API_KEY}" } }, }, }, ], }, }; ``` Sail validates the document when you create the policy and identifies any field that needs to be fixed. See the [HTTP policy guide](/sailboxes-http-policies) for the accepted fields and examples. #### Index Signature \[`host`: `string`]: [`HttpPolicyHost`](#httppolicyhost) *** ### HttpPolicyForward Send the request to a different HTTPS host. `host` is an exact hostname; `port` defaults to 443. #### Properties | Property | Type | Description | | ----------------------- | -------- | ---------------------------------------------------- | | `host` | `string` | Exact hostname, without a scheme, port, or wildcard. | | `port?` | `number` | HTTPS port. Defaults to 443. | *** ### HttpPolicyHost The rules for one host, in order. #### Properties | Property | Type | Description | | --------------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `missing_alpn?` | `"http/1.1"` | How to treat an HTTPS connection that does not announce an HTTP version when it connects. By default such a connection passes through with the policy not applied. Set `"http/1.1"` to treat it as HTTP/1.1 so the rules apply. Allowed only on an exact host. Almost every HTTP client announces a version, so most policies do not need this. | | `rules` | readonly [`HttpPolicyRule`](#httppolicyrule)\[] | Rules for this host, in the order Sail tests them. | *** ### HttpPolicyInfo A policy's id, name, and document. Timestamps are RFC 3339 strings. #### Properties | Property | Type | Description | | ---------------------------------- | -------- | ------------------------------------------------------------------------------------------------- | | `createdAt` | `string` | When the policy was created (RFC 3339). | | `document` | `string` | The saved policy document as JSON text: Sail's normalized form of the document given at creation. | | `id` | `string` | The policy's stable identifier. | | `name` | `string` | The policy's name (the only mutable field). | | `updatedAt` | `string` | When the policy's name last changed (RFC 3339). | *** ### HttpPolicyLike > **HttpPolicyLike** = [`HttpPolicy`](#httppolicy) | [`HttpPolicySummary`](#httppolicysummary) | `string` A policy object, listing summary, or policy id accepted by [Sailbox.setHttpPolicy](#sethttppolicy). *** ### HttpPolicyListItem One HTTP policy returned by [Client.listHttpPolicies](#listhttppolicies). #### Properties | Property | Type | Description | | -------------------------------------------------------- | ----------- | ----------------------------------------------------------- | | `attachmentCount` | `number` | How many Sailboxes the policy is currently attached to. | | `createdAt` | `string` | When the policy was created, as an RFC 3339 string. | | `hostCount` | `number` | How many hosts the document covers. | | `id` | `string` | The policy's stable identifier. | | `name` | `string` | The policy's name. | | `referencedSecretNames` | `string`\[] | The secret names the document refers to. | | `ruleCount` | `number` | How many rules the document carries across every host. | | `updatedAt` | `string` | When the policy's name last changed, as an RFC 3339 string. | *** ### HttpPolicyMatcher > **HttpPolicyMatcher** = `string` | \{ `equals`: `string`; } | \{ `prefix`: `string`; } | \{ `one_of`: readonly `string`\[]; } Match one exact string, a prefix, or one string from a list. A plain string is an exact match. *** ### HttpPolicyNameValueMatcher > **HttpPolicyNameValueMatcher** = \{ `name`: [`HttpPolicyMatcher`](#httppolicymatcher); `present?`: `true`; `value?`: [`HttpPolicyMatcher`](#httppolicymatcher); } | \{ `name?`: [`HttpPolicyMatcher`](#httppolicymatcher); `present?`: `true`; `value`: [`HttpPolicyMatcher`](#httppolicymatcher); } | \{ `name`: [`HttpPolicyMatcher`](#httppolicymatcher); `present`: `false`; `value?`: `never`; } Match a header or query parameter by name, value, or both. Every condition needs a `name` or a `value`; `present` defaults to `true`, meaning a header or parameter matching the condition must be present. Set `present` to `false` with `name` alone to require that name to be absent. The union encodes those rules, so a condition with neither field, or a `value` combined with `present: false`, is a compile error. *** ### HttpPolicyPage One page returned by [Client.listHttpPolicies](#listhttppolicies). #### Properties | Property | Type | Description | | ---------------------------- | ---------------------------------------------- | ------------------------------------------------- | | `hasMore` | `boolean` | Whether another page is available. | | `items` | [`HttpPolicyListItem`](#httppolicylistitem)\[] | The policies on this page. | | `limit` | `number` | The requested page size. | | `offset` | `number` | The requested zero-based offset. | | `total` | `number` | The number of matching policies across all pages. | *** ### HttpPolicyRemoveChange > **HttpPolicyRemoveChange** = \{ `headers`: readonly `string`\[]; `query?`: readonly `string`\[]; } | \{ `headers?`: readonly `string`\[]; `query`: readonly `string`\[]; } Header and query parameter names to delete from a request. At least one of `headers` or `query` is required, and the union encodes that, so an empty `remove` is a compile error. *** ### HttpPolicyRequestChange > **HttpPolicyRequestChange** = \{ `add?`: [`HttpPolicyAddChange`](#httppolicyaddchange); `remove?`: [`HttpPolicyRemoveChange`](#httppolicyremovechange); `set`: [`HttpPolicySetChange`](#httppolicysetchange); } | \{ `add`: [`HttpPolicyAddChange`](#httppolicyaddchange); `remove?`: [`HttpPolicyRemoveChange`](#httppolicyremovechange); `set?`: [`HttpPolicySetChange`](#httppolicysetchange); } | \{ `add?`: [`HttpPolicyAddChange`](#httppolicyaddchange); `remove`: [`HttpPolicyRemoveChange`](#httppolicyremovechange); `set?`: [`HttpPolicySetChange`](#httppolicysetchange); } Change the outbound request before it is sent. `set` replaces or creates values, `add` appends, `remove` deletes. At least one operation is required, and the union encodes that, so an empty change is a compile error. Only `set.headers` and `set.query` may contain a `${secrets.NAME}` reference. *** ### HttpPolicyRequestMatch > **HttpPolicyRequestMatch** = \{ `headers?`: readonly [`HttpPolicyNameValueMatcher`](#httppolicynamevaluematcher)\[]; `method`: [`HttpPolicyStringList`](#httppolicystringlist); `path?`: [`HttpPolicyMatcher`](#httppolicymatcher); `query?`: readonly [`HttpPolicyNameValueMatcher`](#httppolicynamevaluematcher)\[]; } | \{ `headers?`: readonly [`HttpPolicyNameValueMatcher`](#httppolicynamevaluematcher)\[]; `method?`: [`HttpPolicyStringList`](#httppolicystringlist); `path`: [`HttpPolicyMatcher`](#httppolicymatcher); `query?`: readonly [`HttpPolicyNameValueMatcher`](#httppolicynamevaluematcher)\[]; } | \{ `headers`: readonly [`HttpPolicyNameValueMatcher`](#httppolicynamevaluematcher)\[]; `method?`: [`HttpPolicyStringList`](#httppolicystringlist); `path?`: [`HttpPolicyMatcher`](#httppolicymatcher); `query?`: readonly [`HttpPolicyNameValueMatcher`](#httppolicynamevaluematcher)\[]; } | \{ `headers?`: readonly [`HttpPolicyNameValueMatcher`](#httppolicynamevaluematcher)\[]; `method?`: [`HttpPolicyStringList`](#httppolicystringlist); `path?`: [`HttpPolicyMatcher`](#httppolicymatcher); `query`: readonly [`HttpPolicyNameValueMatcher`](#httppolicynamevaluematcher)\[]; } The conditions a request must meet for a rule to apply. At least one condition is required, and the union encodes that, so an empty `match` is a compile error. `method` is one or more case-sensitive HTTP methods, such as `GET`; `path` matches the absolute request path; `headers` and `query` are condition lists in which every entry must match. *** ### HttpPolicyResponse Return a response without sending an HTTP request to the destination. #### Properties | Property | Type | Description | | ----------------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------- | | `body?` | `string` | Response body. Set a content-type header when needed. Not allowed with status 204 or 304. | | `headers?` | [`HttpPolicyValueMap`](#httppolicyvaluemap) | Headers to return. | | `status` | `number` | HTTP status code to return. | *** ### HttpPolicyRule > **HttpPolicyRule** = \{ `forward?`: `never`; `match?`: [`HttpPolicyRequestMatch`](#httppolicyrequestmatch); `request?`: `never`; `respond`: [`HttpPolicyResponse`](#httppolicyresponse); } | \{ `forward?`: [`HttpPolicyForward`](#httppolicyforward); `match?`: [`HttpPolicyRequestMatch`](#httppolicyrequestmatch); `request?`: [`HttpPolicyRequestChange`](#httppolicyrequestchange); `respond?`: `never`; } One rule. `match` narrows which requests it covers; omitting it matches every request, which is only allowed on the last rule. The first matching rule decides the outcome, so order matters. A rule can return a response without sending the request (`respond`), forward the request to another HTTPS host (`forward`), change the request before it is sent (`request`), or send it unchanged. `forward` and `request` combine; `respond` cannot be combined with either, and the union encodes that, so a rule that mixes them is a compile error. *** ### HttpPolicySetChange > **HttpPolicySetChange** = \{ `headers?`: [`HttpPolicyValueMap`](#httppolicyvaluemap); `path`: `string`; `query?`: [`HttpPolicyValueMap`](#httppolicyvaluemap); } | \{ `headers`: [`HttpPolicyValueMap`](#httppolicyvaluemap); `path?`: `string`; `query?`: [`HttpPolicyValueMap`](#httppolicyvaluemap); } | \{ `headers?`: [`HttpPolicyValueMap`](#httppolicyvaluemap); `path?`: `string`; `query`: [`HttpPolicyValueMap`](#httppolicyvaluemap); } Values to replace or create on a request. At least one of `path`, `headers`, or `query` is required, and the union encodes that, so an empty `set` is a compile error. `path` is a replacement absolute path. Values under `headers` and `query` are templates: `${secrets.NAME}` inserts a secret, and a literal dollar sign must be written `$$`. Stored secret references are allowed only under `headers` and `query`, never in `path`. *** ### HttpPolicyStringList > **HttpPolicyStringList** = `string` | readonly `string`\[] One string or a nonempty list of strings. *** ### HttpPolicySummary A policy as returned by [HttpPolicy.list](#list-1), with usage counts but without the document. Fetch the full policy with [HttpPolicy.get](#get). #### Properties | Property | Type | Description | | ---------------------------------------------------------- | ----------- | ------------------------------------------------------- | | `attachmentCount` | `number` | How many Sailboxes the policy is currently attached to. | | `createdAt` | `Date` | When the policy was created. | | `hostCount` | `number` | How many hosts the document covers. | | `id` | `string` | The policy's stable identifier. | | `name` | `string` | The policy's name. | | `referencedSecretNames` | `string`\[] | The secret names the document refers to. | | `ruleCount` | `number` | How many rules the document carries across every host. | | `updatedAt` | `Date` | When the policy's name last changed. | *** ### HttpPolicyValueMap > **HttpPolicyValueMap** = `object` Header or query parameter names mapped to one or more values. #### Index Signature \[`name`: `string`]: [`HttpPolicyStringList`](#httppolicystringlist) *** ### ImageArchitecture > **ImageArchitecture** = `"amd64"` | `"arm64"` *** ### ImageBuild The state of a custom image build. #### Extends * `Omit`\<`native.ImageBuild`, `"status"`> #### Properties | Property | Type | Description | Inherited from | | ------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | | `dockerfilePins?` | [`DockerfileFromResolution`](#dockerfilefromresolution)\[] | What each external image reference resolved to when the spec's source is a Dockerfile; absent otherwise. Carrying these in the spec's `pinnedFrom` keeps creating from the image this build produced, even after a forced build moves what the references mean for your organization. | `Omit.dockerfilePins` | | `errorMessage?` | `string` | Human-readable failure detail; present when `status` is `failed`. | `Omit.errorMessage` | | `imageId` | `string` | The content-addressed image id. | `Omit.imageId` | | `resolvedOciRef?` | `string` | The digest-pinned form of the spec's registry reference when the spec's source is an OCI image; absent otherwise. Creating from this reference instead of the submitted tag keeps naming the same registry content even if the tag has moved since. | `Omit.resolvedOciRef` | | `status` | [`ImageBuildStatus`](#imagebuildstatus-1) | - | - | *** ### ImageBuildOptions Options for [Image.build](#build). #### Properties | Property | Type | Description | | --------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `client?` | [`Client`](#client) | Use a specific client instead of the default (env) one. | | `forceBuild?` | `boolean` | Build the image again even if a build already exists, and wait for the fresh build to become ready. New Sailboxes use the fresh image once it is ready, Sailboxes that already exist keep the filesystem they were created with, and a forced build that fails changes nothing. For an image imported with [Image.fromRegistry](#fromregistry) through a tag, a forced build also asks the registry what the tag points at now and builds that version. The tag then means that version for your whole organization, while specs built earlier keep their pinned version. A forced build of an image built with [Image.fromDockerfile](#fromdockerfile) looks up the tags its `FROM` and `COPY --from` instructions name and moves those pins for your whole organization, while specs built earlier keep the versions their build used. If forced builds overlap, the last-requested one that succeeds decides which image new Sailboxes use and, for a tag, what the tag means. | | `timeoutSeconds?` | `number` | Timeout in seconds bounding the whole pipeline, including hashing, uploads, the build, and any automatic retries (default 1800). | *** ### ImageBuildStatus > **ImageBuildStatus** = `"unknown"` | `"queued"` | `"building"` | `"ready"` | `"failed"` The status of a custom image build. *** ### ImageBuildStep > **ImageBuildStep** = \{ `addLocalDir?`: `never`; `addLocalFile?`: `never`; `aptInstall`: [`PackageInstall`](#packageinstall); `pipInstall?`: `never`; `runCommand?`: `never`; } | \{ `addLocalDir?`: `never`; `addLocalFile?`: `never`; `aptInstall?`: `never`; `pipInstall`: [`PackageInstall`](#packageinstall); `runCommand?`: `never`; } | \{ `addLocalDir?`: `never`; `addLocalFile?`: `never`; `aptInstall?`: `never`; `pipInstall?`: `never`; `runCommand`: [`RunCommand`](#runcommand-2); } | \{ `addLocalDir?`: `never`; `addLocalFile`: [`AddLocalFile`](#addlocalfile-1); `aptInstall?`: `never`; `pipInstall?`: `never`; `runCommand?`: `never`; } | \{ `addLocalDir`: [`AddLocalDir`](#addlocaldir-1); `addLocalFile?`: `never`; `aptInstall?`: `never`; `pipInstall?`: `never`; `runCommand?`: `never`; } One build step: exactly one operation. Each union member `never`-types the other operations, so a step that sets two of them is a compile error (a bare union of the operations would accept it). *** ### ImageDefinition A custom image definition: a base, registry, or Dockerfile image plus ordered build steps, where local-file steps still reference paths on this machine. #### Properties | Property | Type | Description | | ----------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `architecture?` | `string` | Target CPU architecture: `amd64` or `arm64`. Unset means `amd64` with `base` and `dockerfile`, and with `ociRef` means whichever architecture the registry image was built for (`amd64` when it was built for both). Setting it with `ociRef` requires the image to provide that architecture. | | `base?` | `string` | Base image to build on: `debian` or `devbox`. The devbox base is a prebuilt development environment that includes Docker, with the daemon started automatically when the Sailbox boots and kept running across sleeps. The daemon can take a few seconds to accept commands right after boot. If it stops, it is not restarted automatically. Mutually exclusive with `ociRef` and `dockerfile`. | | `dockerfile?` | [`DockerfileSourceInput`](#dockerfilesourceinput) | Your own Dockerfile built into the image; mutually exclusive with `base` and `ociRef`. Every image its `FROM` (and `COPY --from`) instructions name must live on a supported public registry (`docker.io`, `ghcr.io`, `public.ecr.aws`, or `quay.io`; a short name like `python:3.12` means `docker.io/library/python:3.12`). Each named image is pinned to the version its tag pointed at the first time your organization used it, and those pinned versions become part of the built image's identity, so rebuilding the same spec reuses the same image even after a tag moves. A forced build looks the tags up again and builds what they point at now. The built image's `ENV`, `WORKDIR`, and `USER` become the Sailbox defaults for commands you run; its `ENTRYPOINT` and `CMD` are not run, because a Sailbox manages its own processes. | | `env?` | `Record`\<`string`, `string`> | Environment variables baked into the image. | | `ociRef?` | `string` | Your own image as the root filesystem: a reference to a Debian- or Ubuntu-based image whose first segment names a supported public registry (`docker.io`, `ghcr.io`, `public.ecr.aws`, or `quay.io`), with an optional `:tag` or `@sha256:<64 hex>` pin (no tag means the `latest` tag). A tag is pinned for your organization once an image has been built from it: later builds keep getting that version, even if the tag moves upstream. A forced build looks the tag up again and moves the pin for your whole organization. If forced builds of the same tag overlap, the last-requested one that succeeds decides what the tag means, no matter which build finishes first. A digest names exactly one image, so it never moves. The image's `ENV`, `WORKDIR`, and `USER` become the Sailbox defaults for commands you run; its `ENTRYPOINT` and `CMD` are not run, because a Sailbox manages its own processes. Mutually exclusive with `base` and `dockerfile`. | | `steps?` | [`ImageDefinitionStep`](#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 or registry image plus ordered build steps. #### Extends * `Omit`\<`native.ImageSpec`, `"base"` | `"buildSteps"` | `"architecture"` | `"filesystem"`> #### Properties | Property | Type | Description | Inherited from | | ----------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------- | | `architecture?` | [`ImageArchitecture`](#imagearchitecture) | Target CPU architecture. Unset means `amd64` with `base` and `dockerfile`, and with `ociRef` means whichever architecture the registry image was built for (`amd64` when it was built for both). Setting it with `ociRef` requires the image to provide that architecture. | - | | `base?` | [`BaseImage`](#baseimage) | Base image to build on. The `devbox` base is a prebuilt development environment that includes Docker, with the daemon started automatically when the Sailbox boots and kept running across sleeps. The daemon can take a few seconds to accept commands right after boot. If it stops, it is not restarted automatically. Mutually exclusive with `ociRef` and `dockerfile`. | - | | `buildSteps?` | [`ImageBuildStep`](#imagebuildstep)\[] | Ordered build steps applied on top of the image source. | - | | `dockerfile?` | [`DockerfileImage`](#dockerfileimage) | Your own Dockerfile built into the image; mutually exclusive with `base` and `ociRef`. Every image its `FROM` (and `COPY --from`) instructions name must live on a supported public registry (`docker.io`, `ghcr.io`, `public.ecr.aws`, or `quay.io`; a short name like `python:3.12` means `docker.io/library/python:3.12`). Each named image is pinned to the version its tag pointed at the first time your organization used it, and those pinned versions become part of the built image's identity, so rebuilding the same spec reuses the same image even after a tag moves. A forced build looks the tags up again and builds what they point at now. The built image's `ENV`, `WORKDIR`, and `USER` become the Sailbox defaults for commands you run; its `ENTRYPOINT` and `CMD` are not run, because a Sailbox manages its own processes. | `Omit.dockerfile` | | `env?` | `Record`\<`string`, `string`> | Environment variables baked into the image. | `Omit.env` | | `ociRef?` | `string` | Your own image as the root filesystem: a reference to a Debian- or Ubuntu-based image whose first segment names a supported public registry (`docker.io`, `ghcr.io`, `public.ecr.aws`, or `quay.io`), with an optional `:tag` or `@sha256:<64 hex>` pin (no tag means the `latest` tag). A tag is pinned for your organization once an image has been built from it: later builds keep getting that version, even if the tag moves upstream. A forced build looks the tag up again and moves the pin for your whole organization. If forced builds of the same tag overlap, the last-requested one that succeeds decides what the tag means, no matter which build finishes first. A digest names exactly one image, so it never moves. The image's `ENV`, `WORKDIR`, and `USER` become the Sailbox defaults for commands you run; its `ENTRYPOINT` and `CMD` are not run, because a Sailbox manages its own processes. Mutually exclusive with `base` and `dockerfile`. | `Omit.ociRef` | *** ### IngressPortInput A guest port to reserve for ingress at create time. #### Extends * `Omit`\<`native.IngressPortInput`, `"protocol"` | `"allowlist"`> #### Properties | Property | Type | Description | Inherited from | | ----------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | | `allowlist?` | readonly `string`\[] | Sources allowed to reach the port: an address or a range, or a Sail app name on an `http` listener. An app name cannot read as an address or a range, and cannot contain a `/`. An address must not carry an IPv6 zone, such as `fe80::1%eth0`, which names an interface on one machine rather than a source. Empty allows all. | - | | `guestPort` | `number` | The in-guest port to expose (1-65535). | `Omit.guestPort` | | `protocol` | [`IngressProtocol`](#ingressprotocol) | `http` or `tcp`. | - | *** ### IngressProtocol > **IngressProtocol** = `"tcp"` | `"http"` The protocol you request when exposing a port. *** ### IngressScheme > **IngressScheme** = `"path"` | `"subdomain"` How a listener's URL is addressed under `ingressBase`. *** ### ListHttpPoliciesOptions Options for [HttpPolicy.list](#list-1). #### Extends * [`ClientOptions`](#clientoptions) #### Properties | Property | Type | Description | Inherited from | | ----------------------------- | ------------------- | ------------------------------------------------------- | ------------------------------------------------------- | | `client?` | [`Client`](#client) | Use a specific client instead of the default (env) one. | [`ClientOptions`](#clientoptions).[`client`](#client-2) | | `limit?` | `number` | Cap the total number of policies returned. | - | | `search?` | `string` | Filter by id or name, case-insensitively. | - | *** ### ListSailboxesOptions Options for [Sailbox.list](#list-2): the server-side filters, a total-cap `limit`, and an optional `client`. #### Extends * `Omit`\<[`ListSailboxesQuery`](#listsailboxesquery), `"limit"` | `"offset"`>.[`ClientOptions`](#clientoptions) #### Properties | Property | Type | Description | Inherited from | | ----------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | `appId?` | `string` | Filter to one app by its id. | `Omit.appId` | | `client?` | [`Client`](#client) | Use a specific client instead of the default (env) one. | [`ClientOptions`](#clientoptions).[`client`](#client-2) | | `limit?` | `number` | Cap on the total number of Sailboxes returned, bounding the fetch for large orgs; omit to fetch every match. | - | | `order?` | [`SailboxListOrder`](#sailboxlistorder) | Result ordering; `"newest_active"` (most recently active first) when omitted; `"newest_created"` lists the newest-created first. | [`ListSailboxesPageOptions`](#listsailboxespageoptions).[`order`](#order-1) | | `search?` | `string` | Substring filter on the Sailbox name. | `Omit.search` | | `status?` | [`SailboxStatusFilter`](#sailboxstatusfilter) | Filter by lifecycle status. | [`ListSailboxesPageOptions`](#listsailboxespageoptions).[`status`](#status-9) | *** ### ListSailboxesPageOptions Options for [Sailbox.listPage](#listpage): the same filters as [ListSailboxesOptions](#listsailboxesoptions), plus `limit`/`offset` page selection and an optional `client`. #### Extends * [`ListSailboxesQuery`](#listsailboxesquery).[`ClientOptions`](#clientoptions) #### Properties | Property | Type | Description | Inherited from | | ------------------------------ | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | `appId?` | `string` | Filter to one app by its id. | [`ListSailboxesQuery`](#listsailboxesquery).[`appId`](#appid-5) | | `client?` | [`Client`](#client) | Use a specific client instead of the default (env) one. | [`ClientOptions`](#clientoptions).[`client`](#client-2) | | `limit?` | `number` | Page size. | [`ListSailboxesQuery`](#listsailboxesquery).[`limit`](#limit-4) | | `offset?` | `number` | Page offset. | [`ListSailboxesQuery`](#listsailboxesquery).[`offset`](#offset-2) | | `order?` | [`SailboxListOrder`](#sailboxlistorder) | Result ordering; `"newest_active"` (most recently active first) when omitted; `"newest_created"` lists the newest-created first. | [`ListSailboxesQuery`](#listsailboxesquery).[`order`](#order-2) | | `search?` | `string` | Substring filter on the Sailbox name. | [`ListSailboxesQuery`](#listsailboxesquery).[`search`](#search-3) | | `status?` | [`SailboxStatusFilter`](#sailboxstatusfilter) | Filter by lifecycle status. | [`ListSailboxesQuery`](#listsailboxesquery).[`status`](#status-10) | *** ### ListSailboxesQuery Filters for listing Sailboxes. #### Extends * `Omit`\<`native.ListSailboxesQuery`, `"status"` | `"order"`> #### Extended by * [`ListSailboxesPageOptions`](#listsailboxespageoptions) #### Properties | Property | Type | Description | Inherited from | | ------------------------------ | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------- | | `appId?` | `string` | Filter to one app by its id. | `Omit.appId` | | `limit?` | `number` | Page size. | `Omit.limit` | | `offset?` | `number` | Page offset. | `Omit.offset` | | `order?` | [`SailboxListOrder`](#sailboxlistorder) | Result ordering; `"newest_active"` (most recently active first) when omitted; `"newest_created"` lists the newest-created first. | - | | `search?` | `string` | Substring filter on the Sailbox name. | `Omit.search` | | `status?` | [`SailboxStatusFilter`](#sailboxstatusfilter) | Filter by lifecycle status. | - | *** ### ListVolumesOptions Options for [Volume.list](#list-4). #### Extends * [`ClientOptions`](#clientoptions) #### Properties | Property | Type | Description | Inherited from | | ----------------------------------- | ------------------- | ------------------------------------------------------- | ------------------------------------------------------- | | `client?` | [`Client`](#client) | Use a specific client instead of the default (env) one. | [`ClientOptions`](#clientoptions).[`client`](#client-2) | | `maxObjects?` | `number` | Maximum number of volumes to return. | - | *** ### 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-3) | Wire protocol exposed. | | `routeStatus` | [`ListenerRouteStatus`](#listenerroutestatus-1) | Status of the listener's ingress route. | *** ### ListenerEndpoint > **ListenerEndpoint** = [`HttpEndpoint`](#httpendpoint) | [`TcpEndpoint`](#tcpendpoint) How to reach an exposed listener; discriminate on `kind`. *** ### ListenerRouteStatus > **ListenerRouteStatus** = `"unknown"` | `"pending"` | `"active"` | `"restoring"` | `"unavailable"` | `string` & `object` Status of a listener's ingress route (open: tolerates unknown values). *** ### LocalDirInput A local directory tree to bake into the image (walked, hashed, and uploaded at resolve; symlinks skipped, file modes preserved). #### Properties | Property | Type | Description | | ------------------------------------- | ----------- | ------------------------------------------------------------------ | | `ignore?` | `string`\[] | Gitignore-style patterns to skip. | | `ignoreFile?` | `string` | A gitignore-style file whose patterns to skip (e.g. `.gitignore`). | | `localPath` | `string` | Path on this machine. | | `remotePath` | `string` | Absolute POSIX path of the directory root inside the image. | *** ### LocalFileInput One local file to bake into the image (hashed and uploaded at resolve). #### Properties | Property | Type | Description | | ------------------------------------ | -------- | --------------------------------------------------------------------------------- | | `localPath` | `string` | Path on this machine. | | `mode?` | `number` | Permission bits (low 9); omitted uses the builder default (0644). | | `remotePath` | `string` | Absolute POSIX path inside the image; a trailing `/` appends the source basename. | *** ### NetworkAllowlist Restrict the destinations a Sailbox can reach, chosen when it is created and fixed for its whole life. Each entry is a hostname, a `*.` wildcard hostname (one extra name part), an IPv4 address, or an IPv4 range in CIDR form such as `203.0.113.0/24`. Give at least one entry and at most 128; a list that breaks the entry rules is rejected before the Sailbox is created. Only connections the Sailbox opens are limited, so `ingressPorts` and SSH still work. The [network policy guide](https://docs.sailresearch.com/sailboxes-network-policy) has the entry rules and what each entry allows. #### Properties | Property | Modifier | Type | Description | | -------------------------------------- | ---------- | -------------------- | ----------------------------------------------------- | | `allowedHosts` | `readonly` | readonly `string`\[] | The destinations the Sailbox may reach; at least one. | | `mode` | `readonly` | `"allowlist"` | Always `"allowlist"`. | *** ### NetworkPolicy > **NetworkPolicy** = `"public"` | `"no_network"` | [`NetworkAllowlist`](#networkallowlist) How a Sailbox may reach the network, chosen at creation and fixed for its life. `"public"` leaves network access open (the default); `"no_network"` cuts the Sailbox off from other hosts and the internet, so it cannot make outbound connections or expose inbound services and name resolution does not work. Running commands is unaffected (`exec` and the shell reach the Sailbox over a Sail-internal path, not its network), and mounted volumes and other platform features it was created with keep working. A [NetworkAllowlist](#networkallowlist) restricts outbound access to a list of destinations instead. *** ### NetworkPolicyInfo A Sailbox's network policy as reported by [Sailbox.get](#get-1)/[Sailbox.list](#list-2). `mode` is the raw wire mode (`"no_network"` or `"allowlist"`); it is not narrowed to the [NetworkPolicy](#networkpolicy-4) create union, so a mode a newer backend adds is reported faithfully. `allowedHosts` carries the destinations in allowlist mode. Absent on a snapshot means public. The fields are `readonly`: the object a Sailbox returns is frozen, so this type matches the runtime and a caller cannot rewrite an audited policy. #### Properties | Property | Modifier | Type | Description | | ---------------------------------------- | ---------- | -------------------- | ---------------------------------------------------------------- | | `allowedHosts` | `readonly` | readonly `string`\[] | Allowlist destinations when the mode uses them; empty otherwise. | | `mode` | `readonly` | `string` | The policy mode, for example `"no_network"`. | *** ### NeverSleep Stop Sail sleeping a Sailbox on its own. `minSecondsBeforeSleep` belongs to [AutomaticSleep](#automaticsleep), so it cannot be combined with this. #### Properties | Property | Modifier | Type | Description | | ----------------------------------------------------------- | ---------- | ----------- | ------------------------------------------- | | `automatic` | `readonly` | `false` | Stop Sail sleeping this Sailbox on its own. | | `minSecondsBeforeSleep?` | `readonly` | `undefined` | - | *** ### OutputMode > **OutputMode** = `"auto"` | `"pipe"` | `"tail"` What happens when a stream's output buffer fills. Each stream has its own buffer, 1 MiB by default (`outputBufferBytes` in [ExecOptions](#execoptions)). Sending `cancel()`, and the exec timeout, end every pause: from then on each stream keeps only its most recent bytes, so a consumer more than a buffer behind skips. A command that ignores the cancel signal keeps running that way; `cancel({ force: true })` stops it. The command keeps its original timeout. If this handle attaches to a command launched earlier under the same `idempotencyKey`, this handle's pause deadline starts when the attachment succeeds, so it can release the pauses one full timeout after that; `cancel()` and `close()` release them at once. * `"auto"`, the default: a stream you are consuming pauses the command when its buffer fills and resumes as you read, like a pipe; a stream you are not consuming never pauses the command and keeps only its most recent bytes. * `"pipe"`: both streams pause the command when their buffer fills, until you consume them, so nothing is lost while you are late to start. Consume both streams, or the command stays paused on the one you ignore. Once a stream is released, it goes back to keeping only its most recent bytes. Not available with `pty`. * `"tail"`: the command never pauses for you. Each stream keeps only its most recent bytes, even while you are consuming it, so a slow consumer skips output without notice; `stdoutTruncated` and `stderrTruncated` say only that the result holds less than the command wrote. A pty command always behaves this way. *** ### PackageInstall A set of packages to install (apt or pip). #### Properties | Property | Type | Description | | ------------------------------- | ----------- | -------------- | | `packages?` | `string`\[] | Package names. | *** ### Protocol > **Protocol** = `"tcp"` | `"http"` | `string` & `object` The protocol reported on a listener (open: tolerates unknown values). *** ### PtyConfig The pseudo-terminal a `pty` exec runs under. Every field has a default, so `{}` (or `pty: true`) is a usable terminal. #### Properties | Property | Type | Description | | ----------------------- | -------- | ----------------------------------------------- | | `cols?` | `number` | Initial width in columns (default 80). | | `rows?` | `number` | Initial height in rows (default 24). | | `term?` | `string` | `$TERM` for the pty (default `xterm-256color`). | *** ### ResolvedConfig The config resolved from the environment and `~/.sail`. #### Extends * `Omit`\<`native.ResolvedConfig`, `"ingressScheme"` | `"mode"`> #### Properties | Property | Type | Description | Inherited from | | ------------------------------------------ | ----------------------------------- | ----------------------------------------------------- | -------------------- | | `apiKey?` | `string` | The resolved API key; absent when none is configured. | `Omit.apiKey` | | `apiUrl` | `string` | Sail API URL. | `Omit.apiUrl` | | `ingressBase` | `string` | Base host/URL public listeners are addressed under. | `Omit.ingressBase` | | `ingressScheme` | [`IngressScheme`](#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. | *** ### RunOptions Options for [Sailbox.run](#run): the subset of [ExecOptions](#execoptions) that fits a buffered, run-to-completion command. #### Extends * `Pick`\<[`ExecOptions`](#execoptions), `"timeoutSeconds"` | `"cwd"` | `"env"` | `"user"` | `"idempotencyKey"` | `"outputBufferBytes"`> #### Properties | Property | Type | Description | Inherited from | | --------------------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | | `check?` | `boolean` | Reject with `CommandFailedError` (carrying the completed result) when the command exits nonzero or times out, instead of resolving. | - | | `cwd?` | `string` | Working directory to run the command in (shell commands only). Unset starts the command in the image's working directory, or `/` when the image does not set one. | `Pick.cwd` | | `env?` | `Readonly`\<`Record`\<`string`, `string`>> | Extra environment for the command. Entries override the guest's defaults (including `LANG` and the `IS_SANDBOX=1` sandbox marker) and the image env, but a few reserved variables that identify the Sailbox (such as `SAILBOX_ID`) cannot be overridden. | [`ExecOptions`](#execoptions).[`env`](#env-1) | | `idempotencyKey?` | `string` | Stable key so a reconnect reattaches to the same command. An exec has one live handle at a time: a second handle started with the same key takes over the stream, and the first stops receiving live output and resolves from a bounded recorded result. A first handle reconnecting after a dropped connection can race a handle that attached meanwhile, and either handle's result may come back incomplete; avoid overlapping same-key handles. The UTF-8 value can be up to 256 KiB. | `Pick.idempotencyKey` | | `outputBufferBytes?` | `number` | Size of each stream's output buffer in bytes, 1 MiB by default. Must be between 64 KiB and 64 MiB. | `Pick.outputBufferBytes` | | `signal?` | `AbortSignal` | Aborting rejects with the signal's reason and force-cancels the remote command (SIGKILL, like [ExecProcess.cancel](#cancel) with `force`), briefly retrying transient failures. Best effort: the kill is sent once the submission settles (an abort mid-submission cancels the command as soon as its launch is confirmed), and a kill that still fails leaves the command running. | - | | `timeoutSeconds?` | `number` | Wall-clock limit in seconds before the server kills the command. | `Pick.timeoutSeconds` | | `user?` | `string` | Run the command as this guest user: a user name or numeric uid, optionally with a group appended after a colon (`"alice"`, `"1000"`, `"alice:staff"`, the Docker `USER` syntax). A named user must exist in the Sailbox's `/etc/passwd`; a numeric uid need not. `HOME` (and `USER`/`LOGNAME` when a name resolves) default to the resolved account, with `env` entries still winning. When unset, commands run as the image's `USER` if the image sets one, root otherwise; pass `"0:0"` to force root (`"root"` is a user name like any other, resolved through the Sailbox's `/etc/passwd`). Sailboxes created before user support shipped must call `upgrade()` once first; until then such execs fail rather than run as root. The exact spelling `"0:0"` needs no upgrade. | `Pick.user` | *** ### SailboxCheckpoint A durable checkpoint handle. #### Extends * `Omit`\<`native.SailboxCheckpoint`, `"status"` | `"expiresAt"`> #### Properties | Property | Type | Description | Inherited from | | -------------------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | | `checkpointGeneration` | `number` | Checkpoint generation captured by this checkpoint. | `Omit.checkpointGeneration` | | `checkpointId` | `string` | The checkpoint id. | `Omit.checkpointId` | | `expiresAt?` | `Date` | When the checkpoint expires: seven days out unless a TTL asked for a different window. Starting a Sailbox from it after that fails. | - | | `sailboxId` | `string` | The Sailbox the checkpoint was taken from. | `Omit.sailboxId` | | `status` | [`SailboxStatus`](#sailboxstatus-1) | - | - | *** ### SailboxDeprecation > **SailboxDeprecation** = `native.SailboxDeprecation` Actionable notice that a Sailbox's runtime should be upgraded: a `deadline` date and a `message` with upgrade instructions. *** ### SailboxHandle Returned by create / resume / fromCheckpoint: the Sailbox's identity and lifecycle status. #### Properties | Property | Type | Description | | ---------------------------------- | ----------------------------------- | ----------------------------------------------------- | | `name` | `string` | The caller-supplied Sailbox name. | | `sailboxId` | `string` | The Sailbox's stable identifier. | | `status` | [`SailboxStatus`](#sailboxstatus-1) | Lifecycle status at the time the operation completed. | *** ### SailboxInfo A read snapshot of a Sailbox (get / list). Timestamps are RFC 3339 strings. #### Extends * `Omit`\<`native.SailboxInfo`, `"status"` | `"autoSleep"` | `"networkPolicy"`> #### Properties | Property | Modifier | Type | Description | Inherited from | | -------------------------------------------------------- | ---------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | --------------------------- | | `appId` | `public` | `string` | Identifier of the owning app. | `Omit.appId` | | `appName` | `public` | `string` | Name of the owning app. | `Omit.appName` | | `architecture` | `public` | `string` | CPU architecture (for example `arm64`). | `Omit.architecture` | | `autoSleep?` | `public` | [`AutoSleep`](#autosleep-4) | When Sail may sleep this Sailbox on its own. | - | | `checkpointGeneration` | `public` | `number` | Monotonic checkpoint generation counter. | `Omit.checkpointGeneration` | | `cpuRequestedVcpu` | `public` | `number` | Requested CPU, in vCPUs. | `Omit.cpuRequestedVcpu` | | `cpuUsedVcpu` | `public` | `number` | Current CPU usage, in vCPUs. | `Omit.cpuUsedVcpu` | | `createdAt` | `public` | `string` | When the Sailbox was created (RFC 3339). | `Omit.createdAt` | | `createdByUserId?` | `public` | `string` | The user whose credential created this Sailbox (for a restore, the user who ran it). Absent for service-key creates. | `Omit.createdByUserId` | | `deprecation?` | `public` | `SailboxDeprecation` | Actionable runtime deprecation notice, when an upgrade is needed. | `Omit.deprecation` | | `diskRequestedBytes` | `public` | `number` | Requested disk, in bytes. | `Omit.diskRequestedBytes` | | `diskUsedBytes` | `public` | `number` | Current disk usage, in bytes. | `Omit.diskUsedBytes` | | `errorMessage?` | `public` | `string` | Human-readable error detail when the Sailbox is in an error state. | `Omit.errorMessage` | | `guestSchemaVersion?` | `public` | `number` | The Sailbox runtime schema version the Sailbox last booted with. | `Omit.guestSchemaVersion` | | `imageId` | `public` | `string` | Identifier of the image the Sailbox was created from. | `Omit.imageId` | | `lastCheckpointedAt?` | `public` | `string` | When the most recent checkpoint was taken, if any (RFC 3339). | `Omit.lastCheckpointedAt` | | `memoryMib` | `public` | `number` | Configured memory, in MiB. | `Omit.memoryMib` | | `memoryRequestedBytes` | `public` | `number` | Requested memory, in bytes. | `Omit.memoryRequestedBytes` | | `memoryUsedBytes` | `public` | `number` | Current memory usage, in bytes. | `Omit.memoryUsedBytes` | | `name` | `public` | `string` | The Sailbox name. | `Omit.name` | | `networkPolicy?` | `readonly` | [`NetworkPolicyInfo`](#networkpolicyinfo) | The Sailbox's network policy; absent means public. Frozen when read. | - | | `sailboxId` | `public` | `string` | The Sailbox id. | `Omit.sailboxId` | | `startedAt?` | `public` | `string` | When the Sailbox first started running, if it ever has (RFC 3339). A resume does not rewrite it. | `Omit.startedAt` | | `stateDiskSizeGib` | `public` | `number` | Configured state-disk size, in GiB. | `Omit.stateDiskSizeGib` | | `status` | `public` | [`SailboxStatus`](#sailboxstatus-1) | - | - | | `updatedAt` | `public` | `string` | When the Sailbox was last updated (RFC 3339). | `Omit.updatedAt` | | `vcpuCount` | `public` | `number` | Configured number of vCPUs. | `Omit.vcpuCount` | | `visibility?` | `public` | `string` | `"private"` when access is restricted to the creator; absent/`"org"` is the default org-wide access. | `Omit.visibility` | | `volumeMounts` | `public` | `SailboxVolumeMount`\[] | Volumes attached to this Sailbox and the paths they are mounted at. Empty when the Sailbox has none. | `Omit.volumeMounts` | *** ### SailboxInfoPage One page of list results plus the pagination envelope. #### Extends * `Omit`\<`native.SailboxInfoPage`, `"items"`> #### Properties | Property | Type | Description | Inherited from | | ------------------------------ | -------------------------------- | ------------------------------------------ | -------------- | | `hasMore` | `boolean` | Whether more results exist past this page. | `Omit.hasMore` | | `items` | [`SailboxInfo`](#sailboxinfo)\[] | - | - | | `limit` | `number` | The page size that was applied. | `Omit.limit` | | `offset` | `number` | The offset that was applied. | `Omit.offset` | | `total` | `number` | Total matching Sailboxes across all pages. | `Omit.total` | *** ### SailboxListOrder > **SailboxListOrder** = `"newest_active"` | `"newest_created"` Result ordering for a Sailbox list: most recently active first, or newest created first. *** ### SailboxPage One page of [Sailbox](#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` | *** ### SailboxSize > **SailboxSize** = `"s"` | `"m"` | `"l"` Named resource size; each sets the vCPU count plus default memory/disk. *** ### SailboxStatus > **SailboxStatus** = `"running"` | `"paused"` | `"sleeping"` | `"failed"` | `"terminated"` | `string` & `object` Lifecycle status of a Sailbox. Open: tolerates values added server-side. *** ### SailboxStatusFilter > **SailboxStatusFilter** = `"running"` | `"paused"` | `"sleeping"` | `"failed"` | `"terminated"` The closed set of statuses accepted as a list filter. *** ### SecretInfo A secret's name and timestamps. Sail never returns the stored value, so no value field exists. Timestamps are RFC 3339 strings. #### Properties | Property | Type | Description | | ----------------------------------- | -------- | --------------------------------------------------- | | `createdAt` | `string` | When the secret was first set (RFC 3339). | | `name` | `string` | The secret's name, unique within your organization. | | `updatedAt` | `string` | When the secret's value last changed (RFC 3339). | *** ### ShellOptions Options for [Sailbox.shell](#shell-1). #### Properties | Property | Type | Description | | | | --------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `cwd?` | `string` | Working directory for the session. Unset starts it in the image's working directory, or `/` when the image does not set one. | | | | `env?` | `Readonly`\<`Record`\<`string`, `string`>> | Extra environment for the session, with the precedence and reserved names of [ExecOptions.env](#env-1). | | | | `noForward?` | `boolean` | While attached, the Sailbox's browser opens and localhost servers reach your machine, files dragged onto the terminal upload and paste as guest paths, and Ctrl+V forwards your clipboard. On devbox images the clipboard is two-way (pastes land on the Sailbox's clipboard, and what you copy inside the Sailbox comes back); other images upload a pasted image as a file and paste its path. Set `true` to turn all of it off, for example for an untrusted or automated session. | | | | `shell?` | `string` | Login shell to run when no command is given (default: the guest's `$SHELL`, else `/bin/bash`). Ignored when a command is given. | | | | `term?` | `string` | `$TERM` for the remote pty (default: the local `$TERM`). | | | | `timeoutSeconds?` | `number` | Wall-clock limit for the session in seconds; omit for no limit. | | | | `user?` | `string` | Run the session as this user (Docker's `USER` syntax: \`name | uid\[:group | gid]`). Unset runs as the image's `USER`when the image sets one, root otherwise: the same identity [Sailbox.exec](#exec-1) uses.`"0:0"`is always root. A`user`other than`"0:0"\` requires a Sailbox whose guest honors requested users; on older Sailboxes the session fails until [Sailbox.upgrade](#upgrade) is called. | *** ### SshEndpoint The public TCP endpoint a Sailbox's SSH listener is reachable at. #### Properties | Property | Type | Description | | ------------------------ | -------- | ----------------- | | `host` | `string` | Hostname to dial. | | `port` | `number` | Port to dial. | *** ### TcpEndpoint The address to dial for a `tcp` listener. #### Properties | Property | Type | Description | | ------------------------ | -------- | ----------------- | | `host` | `string` | Hostname to dial. | | `kind` | `"tcp"` | - | | `port` | `number` | Port to dial. | *** ### UpgradeResult The outcome of a Sailbox runtime upgrade. #### Extends * `Omit`\<`native.UpgradeResult`, `"status"`> #### Properties | Property | Type | Description | Inherited from | | ----------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | | `applied` | `boolean` | True when no upgrade is left to apply, either because the Sailbox took one just now or because it was already current. False when the upgrade is recorded and takes effect the next time the Sailbox wakes. | `Omit.applied` | | `status` | [`SailboxStatus`](#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 | | --------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `signal?` | `AbortSignal` | Aborting stops the wait and rejects with the signal's reason. An abandoned in-flight probe winds down on its own (by `timeoutSeconds` at the latest); it does not touch the listener. Because the wind-down relies on the timeout, `signal` requires a finite `timeoutSeconds`. | | `timeoutSeconds?` | `number` | Give up waiting after this many seconds (default 60; `Infinity` waits indefinitely). | *** ### WriteOptions Options for uploading a file. #### Properties | Property | Type | Description | | | | ----------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `createParents?` | `boolean` | Create missing parent directories. | | | | `mode?` | `number` | Unix mode bits for the written file (default `0o644`). | | | | `user?` | `string` | Owner for the written file and any parent directories the write creates, in Docker's `USER` syntax: \`name | uid\[:group | gid]`. The write itself always runs as root, like `COPY --chown`, so it succeeds even where that owner could not write. Unset follows the image's `USER`when the image sets one, root otherwise: the same identity commands run as, so an uploaded file is usable by the code in the Sailbox. Pass`"0:0"`to force root ownership. Requires a Sailbox whose guest honors requested users; on older Sailboxes the write fails until [Sailbox.upgrade](#upgrade) is called, except with the exact spelling`"0:0"\`, which needs none. | ## Errors Errors thrown by this SDK surface. All of them extend [SailError](#sailerror), so an `instanceof SailError` check matches everything below. ### 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?`, `details?`): [`SailError`](#sailerror) ###### Parameters | Parameter | Type | Default value | | --------- | ------------------ | ------------- | | `message` | `string` | `undefined` | | `code` | `string` | `"SailError"` | | `details` | `SailErrorDetails` | `{}` | ###### Returns [`SailError`](#sailerror) ###### Overrides `Error.constructor` #### Properties | Property | Modifier | Type | Description | | ----------------------------------- | ---------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `code` | `readonly` | `string` | Stable, language-neutral error code (e.g. `"NotFound"`). | | `retryable` | `readonly` | `boolean` | Advisory: `true` when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient exec failure). `false` when the failure is deterministic (bad argument, missing resource, permission). The SDK's built-in retry already covers the transient window for most calls; this classifies what leaks past it. | *** ### ApiError A non-2xx API response. #### Extends * [`SailError`](#sailerror) #### Extended by * [`SecretInUseError`](#secretinuseerror) * [`HttpPolicyInUseError`](#httppolicyinuseerror) #### Constructors ##### Constructor > **new ApiError**(`message`, `details?`): [`ApiError`](#apierror) ###### Parameters | Parameter | Type | | --------- | ------------------ | | `message` | `string` | | `details` | `SailErrorDetails` | ###### Returns [`ApiError`](#apierror) ###### Overrides [`SailError`](#sailerror).[`constructor`](#constructor-15) #### Properties | Property | Modifier | Type | Description | Inherited from | | -------------------------------- | ---------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | `body?` | `readonly` | `unknown` | Parsed response body from the failed request, when available. | - | | `code` | `readonly` | `string` | Stable, language-neutral error code (e.g. `"NotFound"`). | [`SailError`](#sailerror).[`code`](#code-15) | | `retryable` | `readonly` | `boolean` | Advisory: `true` when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient exec failure). `false` when the failure is deterministic (bad argument, missing resource, permission). The SDK's built-in retry already covers the transient window for most calls; this classifies what leaks past it. | [`SailError`](#sailerror).[`retryable`](#retryable-15) | | `status?` | `readonly` | `number` | HTTP status code returned by the API, when the failure carries one. | - | *** ### BrokenPipeError A stream (e.g. exec stdin) was closed and can no longer be written. #### Extends * [`SailError`](#sailerror) #### Constructors ##### Constructor > **new BrokenPipeError**(`message`, `details?`): [`BrokenPipeError`](#brokenpipeerror) ###### Parameters | Parameter | Type | | --------- | ------------------ | | `message` | `string` | | `details` | `SailErrorDetails` | ###### Returns [`BrokenPipeError`](#brokenpipeerror) ###### Overrides [`SailError`](#sailerror).[`constructor`](#constructor-15) #### Properties | Property | Modifier | Type | Description | Inherited from | | ---------------------------------- | ---------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | `code` | `readonly` | `string` | Stable, language-neutral error code (e.g. `"NotFound"`). | [`SailError`](#sailerror).[`code`](#code-15) | | `retryable` | `readonly` | `boolean` | Advisory: `true` when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient exec failure). `false` when the failure is deterministic (bad argument, missing resource, permission). The SDK's built-in retry already covers the transient window for most calls; this classifies what leaks past it. | [`SailError`](#sailerror).[`retryable`](#retryable-15) | *** ### CommandFailedError Thrown by [Sailbox.run](#run) with `check` when the command exits nonzero or times out. Carries the completed result as [result](#result). #### Extends * [`SailboxExecutionError`](#sailboxexecutionerror) #### Constructors ##### Constructor > **new CommandFailedError**(`message`, `result`): [`CommandFailedError`](#commandfailederror) ###### Parameters | Parameter | Type | | --------- | --------------------------- | | `message` | `string` | | `result` | [`ExecResult`](#execresult) | ###### Returns [`CommandFailedError`](#commandfailederror) ###### Overrides [`SailboxExecutionError`](#sailboxexecutionerror).[`constructor`](#constructor-12) #### Properties | Property | Modifier | Type | Description | Inherited from | | ---------------------------------- | ---------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | `code` | `readonly` | `string` | Stable, language-neutral error code (e.g. `"NotFound"`). | [`SailboxExecutionError`](#sailboxexecutionerror).[`code`](#code-12) | | `result` | `readonly` | [`ExecResult`](#execresult) | - | - | | `retryable` | `readonly` | `boolean` | Advisory: `true` when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient exec failure). `false` when the failure is deterministic (bad argument, missing resource, permission). The SDK's built-in retry already covers the transient window for most calls; this classifies what leaks past it. | [`SailboxExecutionError`](#sailboxexecutionerror).[`retryable`](#retryable-12) | | `rpcStatus` | `readonly` | `string` | Transport status classifying the failure (for example `"unavailable"`), empty when the failure carries no status. Distinct from [code](#code-15), which stays the taxonomy discriminator on every SailError. | [`SailboxExecutionError`](#sailboxexecutionerror).[`rpcStatus`](#rpcstatus-2) | *** ### FileNotFoundError A remote file path does not exist. #### Extends * [`SailError`](#sailerror) #### Constructors ##### Constructor > **new FileNotFoundError**(`message`, `details?`): [`FileNotFoundError`](#filenotfounderror) ###### Parameters | Parameter | Type | | --------- | ------------------ | | `message` | `string` | | `details` | `SailErrorDetails` | ###### Returns [`FileNotFoundError`](#filenotfounderror) ###### Overrides [`SailError`](#sailerror).[`constructor`](#constructor-15) #### Properties | Property | Modifier | Type | Description | Inherited from | | ---------------------------------- | ---------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | `code` | `readonly` | `string` | Stable, language-neutral error code (e.g. `"NotFound"`). | [`SailError`](#sailerror).[`code`](#code-15) | | `retryable` | `readonly` | `boolean` | Advisory: `true` when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient exec failure). `false` when the failure is deterministic (bad argument, missing resource, permission). The SDK's built-in retry already covers the transient window for most calls; this classifies what leaks past it. | [`SailError`](#sailerror).[`retryable`](#retryable-15) | *** ### HttpPolicyInUseError Deleting an HTTP policy that is still attached to a Sailbox. Clear or replace it on every Sailbox first, then delete it. #### Extends * [`ApiError`](#apierror) #### Constructors ##### Constructor > **new HttpPolicyInUseError**(`message`, `details?`): [`HttpPolicyInUseError`](#httppolicyinuseerror) ###### Parameters | Parameter | Type | | --------- | ------------------ | | `message` | `string` | | `details` | `SailErrorDetails` | ###### Returns [`HttpPolicyInUseError`](#httppolicyinuseerror) ###### Inherited from [`ApiError`](#apierror).[`constructor`](#constructor) #### Properties | Property | Modifier | Type | Description | Inherited from | | ---------------------------------- | ---------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | `body?` | `readonly` | `unknown` | Parsed response body from the failed request, when available. | [`ApiError`](#apierror).[`body`](#body) | | `code` | `readonly` | `string` | Stable, language-neutral error code (e.g. `"NotFound"`). | [`ApiError`](#apierror).[`code`](#code) | | `retryable` | `readonly` | `boolean` | Advisory: `true` when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient exec failure). `false` when the failure is deterministic (bad argument, missing resource, permission). The SDK's built-in retry already covers the transient window for most calls; this classifies what leaks past it. | [`ApiError`](#apierror).[`retryable`](#retryable) | | `status?` | `readonly` | `number` | HTTP status code returned by the API, when the failure carries one. | [`ApiError`](#apierror).[`status`](#status) | *** ### ImageBuildError A custom image could not be built or its local content could not be uploaded. #### Extends * [`SailError`](#sailerror) #### Constructors ##### Constructor > **new ImageBuildError**(`message`, `details?`): [`ImageBuildError`](#imagebuilderror) ###### Parameters | Parameter | Type | | --------- | ------------------ | | `message` | `string` | | `details` | `SailErrorDetails` | ###### Returns [`ImageBuildError`](#imagebuilderror) ###### Overrides [`SailError`](#sailerror).[`constructor`](#constructor-15) #### Properties | Property | Modifier | Type | Description | Inherited from | | ---------------------------------- | ---------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | `code` | `readonly` | `string` | Stable, language-neutral error code (e.g. `"NotFound"`). | [`SailError`](#sailerror).[`code`](#code-15) | | `retryable` | `readonly` | `boolean` | Advisory: `true` when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient exec failure). `false` when the failure is deterministic (bad argument, missing resource, permission). The SDK's built-in retry already covers the transient window for most calls; this classifies what leaks past it. | [`SailError`](#sailerror).[`retryable`](#retryable-15) | *** ### InternalError An unexpected internal SDK failure. #### Extends * [`SailError`](#sailerror) #### Constructors ##### Constructor > **new InternalError**(`message`, `details?`): [`InternalError`](#internalerror) ###### Parameters | Parameter | Type | | --------- | ------------------ | | `message` | `string` | | `details` | `SailErrorDetails` | ###### Returns [`InternalError`](#internalerror) ###### Overrides [`SailError`](#sailerror).[`constructor`](#constructor-15) #### Properties | Property | Modifier | Type | Description | Inherited from | | ---------------------------------- | ---------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | `code` | `readonly` | `string` | Stable, language-neutral error code (e.g. `"NotFound"`). | [`SailError`](#sailerror).[`code`](#code-15) | | `retryable` | `readonly` | `boolean` | Advisory: `true` when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient exec failure). `false` when the failure is deterministic (bad argument, missing resource, permission). The SDK's built-in retry already covers the transient window for most calls; this classifies what leaks past it. | [`SailError`](#sailerror).[`retryable`](#retryable-15) | *** ### InvalidArgumentError Invalid arguments or configuration (bad request, missing/invalid API key). #### Extends * [`SailError`](#sailerror) #### Constructors ##### Constructor > **new InvalidArgumentError**(`message`, `details?`): [`InvalidArgumentError`](#invalidargumenterror) ###### Parameters | Parameter | Type | | --------- | ------------------ | | `message` | `string` | | `details` | `SailErrorDetails` | ###### Returns [`InvalidArgumentError`](#invalidargumenterror) ###### Overrides [`SailError`](#sailerror).[`constructor`](#constructor-15) #### Properties | Property | Modifier | Type | Description | Inherited from | | ---------------------------------- | ---------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | `code` | `readonly` | `string` | Stable, language-neutral error code (e.g. `"NotFound"`). | [`SailError`](#sailerror).[`code`](#code-15) | | `retryable` | `readonly` | `boolean` | Advisory: `true` when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient exec failure). `false` when the failure is deterministic (bad argument, missing resource, permission). The SDK's built-in retry already covers the transient window for most calls; this classifies what leaks past it. | [`SailError`](#sailerror).[`retryable`](#retryable-15) | *** ### NotFoundError The Sailbox, volume, or other resource does not exist (or is another org's). #### Extends * [`SailError`](#sailerror) #### Constructors ##### Constructor > **new NotFoundError**(`message`, `details?`): [`NotFoundError`](#notfounderror) ###### Parameters | Parameter | Type | | --------- | ------------------ | | `message` | `string` | | `details` | `SailErrorDetails` | ###### Returns [`NotFoundError`](#notfounderror) ###### Overrides [`SailError`](#sailerror).[`constructor`](#constructor-15) #### Properties | Property | Modifier | Type | Description | Inherited from | | ---------------------------------- | ---------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | `code` | `readonly` | `string` | Stable, language-neutral error code (e.g. `"NotFound"`). | [`SailError`](#sailerror).[`code`](#code-15) | | `retryable` | `readonly` | `boolean` | Advisory: `true` when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient exec failure). `false` when the failure is deterministic (bad argument, missing resource, permission). The SDK's built-in retry already covers the transient window for most calls; this classifies what leaks past it. | [`SailError`](#sailerror).[`retryable`](#retryable-15) | *** ### PermissionDeniedError The credential is not permitted to perform the operation. #### Extends * [`SailError`](#sailerror) #### Constructors ##### Constructor > **new PermissionDeniedError**(`message`, `details?`): [`PermissionDeniedError`](#permissiondeniederror) ###### Parameters | Parameter | Type | | --------- | ------------------ | | `message` | `string` | | `details` | `SailErrorDetails` | ###### Returns [`PermissionDeniedError`](#permissiondeniederror) ###### Overrides [`SailError`](#sailerror).[`constructor`](#constructor-15) #### Properties | Property | Modifier | Type | Description | Inherited from | | ---------------------------------- | ---------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | `code` | `readonly` | `string` | Stable, language-neutral error code (e.g. `"NotFound"`). | [`SailError`](#sailerror).[`code`](#code-15) | | `retryable` | `readonly` | `boolean` | Advisory: `true` when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient exec failure). `false` when the failure is deterministic (bad argument, missing resource, permission). The SDK's built-in retry already covers the transient window for most calls; this classifies what leaks past it. | [`SailError`](#sailerror).[`retryable`](#retryable-15) | *** ### SailboxCreationError A Sailbox could not be created (provisioning failed). #### Extends * [`SailError`](#sailerror) #### Constructors ##### Constructor > **new SailboxCreationError**(`message`, `details?`): [`SailboxCreationError`](#sailboxcreationerror) ###### Parameters | Parameter | Type | | --------- | ------------------ | | `message` | `string` | | `details` | `SailErrorDetails` | ###### Returns [`SailboxCreationError`](#sailboxcreationerror) ###### Overrides [`SailError`](#sailerror).[`constructor`](#constructor-15) #### Properties | Property | Modifier | Type | Description | Inherited from | | ----------------------------------- | ---------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | `body?` | `readonly` | `unknown` | Parsed response body from the failed create request, when available. | - | | `code` | `readonly` | `string` | Stable, language-neutral error code (e.g. `"NotFound"`). | [`SailError`](#sailerror).[`code`](#code-15) | | `retryable` | `readonly` | `boolean` | Advisory: `true` when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient exec failure). `false` when the failure is deterministic (bad argument, missing resource, permission). The SDK's built-in retry already covers the transient window for most calls; this classifies what leaks past it. | [`SailError`](#sailerror).[`retryable`](#retryable-15) | | `status?` | `readonly` | `number` | HTTP status code returned by the create request, when the failure carries one. | - | *** ### SailboxExecRequestNotFoundError The exec request could not be found (for example after the Sailbox moved machines). #### Extends * [`SailboxExecutionError`](#sailboxexecutionerror) #### Constructors ##### Constructor > **new SailboxExecRequestNotFoundError**(`message`, `details?`): [`SailboxExecRequestNotFoundError`](#sailboxexecrequestnotfounderror) ###### Parameters | Parameter | Type | | --------- | ------------------ | | `message` | `string` | | `details` | `SailErrorDetails` | ###### Returns [`SailboxExecRequestNotFoundError`](#sailboxexecrequestnotfounderror) ###### Overrides [`SailboxExecutionError`](#sailboxexecutionerror).[`constructor`](#constructor-12) #### Properties | Property | Modifier | Type | Description | Inherited from | | ----------------------------------- | ---------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | `code` | `readonly` | `string` | Stable, language-neutral error code (e.g. `"NotFound"`). | [`SailboxExecutionError`](#sailboxexecutionerror).[`code`](#code-12) | | `retryable` | `readonly` | `boolean` | Advisory: `true` when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient exec failure). `false` when the failure is deterministic (bad argument, missing resource, permission). The SDK's built-in retry already covers the transient window for most calls; this classifies what leaks past it. | [`SailboxExecutionError`](#sailboxexecutionerror).[`retryable`](#retryable-12) | | `rpcStatus` | `readonly` | `string` | Transport status classifying the failure (for example `"unavailable"`), empty when the failure carries no status. Distinct from [code](#code-15), which stays the taxonomy discriminator on every SailError. | [`SailboxExecutionError`](#sailboxexecutionerror).[`rpcStatus`](#rpcstatus-2) | *** ### SailboxExecutionError Base class for failures during an exec. #### Extends * [`SailError`](#sailerror) #### Extended by * [`CommandFailedError`](#commandfailederror) * [`SailboxTerminatedError`](#sailboxterminatederror) * [`SailboxExecRequestNotFoundError`](#sailboxexecrequestnotfounderror) * [`SailboxHostLostError`](#sailboxhostlosterror) #### Constructors ##### Constructor > **new SailboxExecutionError**(`message`, `code?`, `details?`): [`SailboxExecutionError`](#sailboxexecutionerror) ###### Parameters | Parameter | Type | Default value | | --------- | ------------------ | ------------------------- | | `message` | `string` | `undefined` | | `code` | `string` | `"SailboxExecutionError"` | | `details` | `SailErrorDetails` | `{}` | ###### Returns [`SailboxExecutionError`](#sailboxexecutionerror) ###### Overrides [`SailError`](#sailerror).[`constructor`](#constructor-15) #### Properties | Property | Modifier | Type | Description | Inherited from | | ----------------------------------- | ---------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | `code` | `readonly` | `string` | Stable, language-neutral error code (e.g. `"NotFound"`). | [`SailError`](#sailerror).[`code`](#code-15) | | `retryable` | `readonly` | `boolean` | Advisory: `true` when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient exec failure). `false` when the failure is deterministic (bad argument, missing resource, permission). The SDK's built-in retry already covers the transient window for most calls; this classifies what leaks past it. | [`SailError`](#sailerror).[`retryable`](#retryable-15) | | `rpcStatus` | `readonly` | `string` | Transport status classifying the failure (for example `"unavailable"`), empty when the failure carries no status. Distinct from [code](#code-15), which stays the taxonomy discriminator on every SailError. | - | *** ### SailboxHostLostError The machine hosting the Sailbox was lost while an exec was in flight. #### Extends * [`SailboxExecutionError`](#sailboxexecutionerror) #### Constructors ##### Constructor > **new SailboxHostLostError**(`message`, `details?`): [`SailboxHostLostError`](#sailboxhostlosterror) ###### Parameters | Parameter | Type | | --------- | ------------------ | | `message` | `string` | | `details` | `SailErrorDetails` | ###### Returns [`SailboxHostLostError`](#sailboxhostlosterror) ###### Overrides [`SailboxExecutionError`](#sailboxexecutionerror).[`constructor`](#constructor-12) #### Properties | Property | Modifier | Type | Description | Inherited from | | ----------------------------------- | ---------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | `code` | `readonly` | `string` | Stable, language-neutral error code (e.g. `"NotFound"`). | [`SailboxExecutionError`](#sailboxexecutionerror).[`code`](#code-12) | | `retryable` | `readonly` | `boolean` | Advisory: `true` when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient exec failure). `false` when the failure is deterministic (bad argument, missing resource, permission). The SDK's built-in retry already covers the transient window for most calls; this classifies what leaks past it. | [`SailboxExecutionError`](#sailboxexecutionerror).[`retryable`](#retryable-12) | | `rpcStatus` | `readonly` | `string` | Transport status classifying the failure (for example `"unavailable"`), empty when the failure carries no status. Distinct from [code](#code-15), which stays the taxonomy discriminator on every SailError. | [`SailboxExecutionError`](#sailboxexecutionerror).[`rpcStatus`](#rpcstatus-2) | *** ### SailboxTerminatedError The Sailbox was terminated while an exec was in flight. #### Extends * [`SailboxExecutionError`](#sailboxexecutionerror) #### Constructors ##### Constructor > **new SailboxTerminatedError**(`message`, `details?`): [`SailboxTerminatedError`](#sailboxterminatederror) ###### Parameters | Parameter | Type | | --------- | ------------------ | | `message` | `string` | | `details` | `SailErrorDetails` | ###### Returns [`SailboxTerminatedError`](#sailboxterminatederror) ###### Overrides [`SailboxExecutionError`](#sailboxexecutionerror).[`constructor`](#constructor-12) #### Properties | Property | Modifier | Type | Description | Inherited from | | ----------------------------------- | ---------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | `code` | `readonly` | `string` | Stable, language-neutral error code (e.g. `"NotFound"`). | [`SailboxExecutionError`](#sailboxexecutionerror).[`code`](#code-12) | | `retryable` | `readonly` | `boolean` | Advisory: `true` when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient exec failure). `false` when the failure is deterministic (bad argument, missing resource, permission). The SDK's built-in retry already covers the transient window for most calls; this classifies what leaks past it. | [`SailboxExecutionError`](#sailboxexecutionerror).[`retryable`](#retryable-12) | | `rpcStatus` | `readonly` | `string` | Transport status classifying the failure (for example `"unavailable"`), empty when the failure carries no status. Distinct from [code](#code-15), which stays the taxonomy discriminator on every SailError. | [`SailboxExecutionError`](#sailboxexecutionerror).[`rpcStatus`](#rpcstatus-2) | *** ### SecretInUseError Deleting a secret that HTTP policies still refer to. Delete those policies first, then delete the secret. #### Extends * [`ApiError`](#apierror) #### Constructors ##### Constructor > **new SecretInUseError**(`message`, `details?`): [`SecretInUseError`](#secretinuseerror) ###### Parameters | Parameter | Type | | --------- | ------------------ | | `message` | `string` | | `details` | `SailErrorDetails` | ###### Returns [`SecretInUseError`](#secretinuseerror) ###### Inherited from [`ApiError`](#apierror).[`constructor`](#constructor) #### Properties | Property | Modifier | Type | Description | Inherited from | | ----------------------------------- | ---------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | `body?` | `readonly` | `unknown` | Parsed response body from the failed request, when available. | [`ApiError`](#apierror).[`body`](#body) | | `code` | `readonly` | `string` | Stable, language-neutral error code (e.g. `"NotFound"`). | [`ApiError`](#apierror).[`code`](#code) | | `retryable` | `readonly` | `boolean` | Advisory: `true` when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient exec failure). `false` when the failure is deterministic (bad argument, missing resource, permission). The SDK's built-in retry already covers the transient window for most calls; this classifies what leaks past it. | [`ApiError`](#apierror).[`retryable`](#retryable) | | `status?` | `readonly` | `number` | HTTP status code returned by the API, when the failure carries one. | [`ApiError`](#apierror).[`status`](#status) | *** ### TimeoutError A request exceeded its timeout. #### Extends * [`SailError`](#sailerror) #### Constructors ##### Constructor > **new TimeoutError**(`message`, `details?`): [`TimeoutError`](#timeouterror) ###### Parameters | Parameter | Type | | --------- | ------------------ | | `message` | `string` | | `details` | `SailErrorDetails` | ###### Returns [`TimeoutError`](#timeouterror) ###### Overrides [`SailError`](#sailerror).[`constructor`](#constructor-15) #### Properties | Property | Modifier | Type | Description | Inherited from | | ----------------------------------- | ---------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | `code` | `readonly` | `string` | Stable, language-neutral error code (e.g. `"NotFound"`). | [`SailError`](#sailerror).[`code`](#code-15) | | `retryable` | `readonly` | `boolean` | Advisory: `true` when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient exec failure). `false` when the failure is deterministic (bad argument, missing resource, permission). The SDK's built-in retry already covers the transient window for most calls; this classifies what leaks past it. | [`SailError`](#sailerror).[`retryable`](#retryable-15) | *** ### TransportError A network/connection transport failure. #### Extends * [`SailError`](#sailerror) #### Constructors ##### Constructor > **new TransportError**(`message`, `details?`): [`TransportError`](#transporterror) ###### Parameters | Parameter | Type | | --------- | ------------------ | | `message` | `string` | | `details` | `SailErrorDetails` | ###### Returns [`TransportError`](#transporterror) ###### Overrides [`SailError`](#sailerror).[`constructor`](#constructor-15) #### Properties | Property | Modifier | Type | Description | Inherited from | | ----------------------------------- | ---------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | `code` | `readonly` | `string` | Stable, language-neutral error code (e.g. `"NotFound"`). | [`SailError`](#sailerror).[`code`](#code-15) | | `retryable` | `readonly` | `boolean` | Advisory: `true` when retrying the same call may succeed (a transport failure, HTTP 429 or a gateway 5xx, a transient exec failure). `false` when the failure is deterministic (bad argument, missing resource, permission). The SDK's built-in retry already covers the transient window for most calls; this classifies what leaks past it. | [`SailError`](#sailerror).[`retryable`](#retryable-15) |