Types

All types in this file mirror the createos-sandbox control-plane JSON HTTP API. Fields use the server's snake_case names so JSON parses without translation. When the server uses omitempty on a field, the TypeScript field is marked optional (?): the key is absent from the wire payload rather than sent as null. List endpoints return a doubly-nested pagination envelope { data: { data: [...], pagination: { total, limit, offset, count } } }; rootfs is the lone exception (a plain view). The server clamps limit to 500; drive paging from the reported total, not the requested page size. Every type here is re-exported via export * from "./types.js" in index.ts, making the entire surface public.

See also: Client · Sandbox · Sub-APIs

At a glance

• Package: @nodeops-createos/sandbox (npm)
• Import: import { createClient } from "@nodeops-createos/sandbox"
• Base URL: https://api.sb.createos.sh (override with CREATEOS_SANDBOX_BASE_URL)
• Auth: API key via the apiKey option or CREATEOS_SANDBOX_API_KEY

JSend envelope

The control plane wraps every response in one of three JSend shapes. The SDK unwraps these transparently; consumers only see them when using the raw CreateosSandboxHttp transport directly.

export interface SuccessEnvelope<T> {
  status: "success";
  data: T;
}
 
export interface FailEnvelope {
  status: "fail";
  /** Field-keyed object or plain string depending on the endpoint. */
  data: Record<string, unknown> | string;
}
 
export interface ErrorEnvelope {
  status: "error";
  message: string;
  code: number;
}
 
export type JSendEnvelope<T> =
  | SuccessEnvelope<T>
  | FailEnvelope
  | ErrorEnvelope;

Client & request options

RetryOptions

Exponential-backoff retry policy. Omit a field to keep its default.

export interface RetryOptions {
  maxRetries?: number; // Extra attempts after the first. Default 2 (3 total).
  baseDelayMs?: number; // Base backoff delay in ms. Default 500.
  maxDelayMs?: number; // Backoff ceiling in ms. Default 30000.
}

RetryReason

export type RetryReason = "network" | "status" | "rate-limit";

RequestHookContext

Delivered to ClientHooks.onRequest. All credentials are pre-redacted.

ResponseHookContext

Extends RequestHookContext.

RetryHookContext

Extends Omit<ResponseHookContext, "status">.

ClientHooks

Optional lifecycle hooks for zero-dep observability. Every payload is pre-redacted. Throws inside a hook are swallowed. Hooks are awaited in the request path; keep hook work cheap or dispatch slow work without returning the promise.

export interface ClientHooks {
  onRequest?: (ctx: RequestHookContext) => void | Promise<void>;
  onResponse?: (ctx: ResponseHookContext) => void | Promise<void>;
  onRetry?: (ctx: RetryHookContext) => void | Promise<void>;
}

CreateosSandboxClientOptions

Construction options for CreateosSandboxClient. All fields are optional.

RequestOptions

Per-call overrides accepted by every SDK method.

ExecOptions

export type ExecOptions = RequestOptions;

Alias for RequestOptions; passed to Sandbox.runCommand and Sandbox.streamCommand.

Catalog & identity

Shape

A sandbox sizing preset. Returned by listShapes().

RootfsEntry

Metadata for one built-in rootfs image in the catalog.

RootfsData

export interface RootfsData {
  /** Available rootfs catalog names usable as `CreateSandboxRequest.rootfs`. */
  rootfs: string[];
  /** Name used when a create request omits `rootfs`. */
  default: string;
  /** Rich per-rootfs metadata; absent when the catalog is empty. */
  entries?: RootfsEntry[];
}

Response from listRootfs(). entries is absent when the catalog is empty. This endpoint returns a plain view, not the paginated envelope used by all other list routes.

HostStatus

export type HostStatus = "active" | "draining" | "dead";

Scheduling state of a worker host.

HostPublic

A worker host visible to the caller. Returned by listHosts().

WhoAmIStatsView

Per-state sandbox counts for the calling identity.

WhoAmIView

Identity behind the configured API key. Returned by whoami().

Sandbox

NetworkEntry

References an overlay network by id in CreateSandboxRequest.networks.

export interface NetworkEntry {
  id: string;
}

CreateSandboxRequest

Body of POST /v1/sandboxes. Only shape is required.

Note: bandwidth_quota_bytes is not settable at create time; the server returns 400 for any non-zero value. Grow the quota post-create with Sandbox.rechargeBandwidth().

node_selector and ingress_* fields are not described in the published OpenAPI spec; verify against the live API.

CreateSandboxResponse

Result of POST /v1/sandboxes, returned before the SDK fetches the full SandboxView. Records the resolved placement and boot timing.

SandboxStatus

Lifecycle state of a sandbox. Transitional states (pausing, resuming, forking, creating, destroying) settle into a steady or terminal one.

export type SandboxStatus =
  | "creating"
  | "running"
  | "pausing"
  | "paused"
  | "resuming"
  | "forking"
  | "error"
  | "destroying"
  | "destroyed"
  | "failed";

SandboxView

Full server-side projection of a sandbox. Backs the Sandbox handle and is returned by get/list endpoints. Optional fields are omitted by the server (omitempty) rather than sent as null.

Wire drift: ingress_url_template is present on the SDK SandboxView but absent from the published OpenAPI SandboxView schema. Verify against the live API.

ListSandboxesOptions

Extends RequestOptions.

ForkSandboxRequest

Optional overrides applied to a fork. Omitted fields inherit from the source.

PatchSandboxRequest

Body of the sandbox PATCH endpoint, used by Sandbox.setIngress and Sandbox.setAutoPause. Omitted fields are left unchanged.

AddSSHPubkeysRequest

Body of Sandbox.addSSHPubkeys: keys to add to a live sandbox.

export interface AddSSHPubkeysRequest {
  /** OpenSSH-formatted public keys. Keys already present are de-duplicated. */
  keys: string[];
}

AddSSHPubkeysResponse

export interface AddSSHPubkeysResponse {
  /** Total `ssh_pubkeys` on the sandbox after the add. */
  count: number;
}

DestroyedResponse

export interface DestroyedResponse {
  /** Id of the sandbox accepted for destruction. */
  id: string;
  /** Status reached by the destroy call. `destroying` for an async reclaim;
   *  `destroyed` when the call was a no-op on an already terminal row or
   *  could be reclaimed inline (paused/error). */
  status: Extract<SandboxStatus, "destroying" | "destroyed">;
}

SetEgressRequest

export interface SetEgressRequest {
  /** `host:port` allow rules. `null`, omitted, or `[]` means allow all. */
  egress?: string[] | null;
}

EgressView

The sandbox's current egress allowlist. Returned by getEgress / setEgress.

export interface EgressView {
  id: string;
  /** Active `host:port` allow rules. Empty = allow all. */
  egress: string[];
}

BandwidthView

Bandwidth quota and usage counters. Returned by getBandwidth / rechargeBandwidth.

RechargeBandwidthRequest

export interface RechargeBandwidthRequest {
  /** Bytes to add to the quota. */
  add_bytes: number;
}

ResizeSandboxRequest

export interface ResizeSandboxRequest {
  /** New overlay disk size in MiB. Must be larger than the current size. */
  disk_mib: number;
}

ResizeSandboxResponse

export interface ResizeSandboxResponse {
  /** Disk size in MiB after the grow. */
  disk_mib: number;
}

Command execution

ExecRequest

Wire request body for POST /v1/sandboxes/:id/exec.

ExecResult

Buffered output of a completed command. Returned by runCommand.

ExecResponse

Result of runCommand: the buffered output plus timing.

export interface ExecResponse {
  result: ExecResult;
  /** Wall-clock time the command ran, in milliseconds. */
  exec_ms: number;
}

ExecStreamEvent

Discriminated union yielded by Sandbox.streamCommand. Switch on type to handle each kind of event; TypeScript narrows the payload.

export type ExecStreamEvent =
  | { type: "stdout"; data: string }
  | { type: "stderr"; data: string }
  | { type: "exit"; exitCode: number }
  | { type: "error"; message: string }
  | { type: "heartbeat" };

ExecStreamFrame

Raw NDJSON frame as emitted by the server. Exposed for advanced users who want to bypass the ExecStreamEvent projection (e.g. log forwarders that need the snake_case shape).

Handle option types

CreateSandboxOptions

Extends RequestOptions. Passed to CreateosSandboxClient.createSandbox.

WaitOptions

Options for the Sandbox.waitUntil* pollers.

Templates

TemplateStatus

export type TemplateStatus = "pending" | "building" | "ready" | "failed";

ready once the rootfs image is usable as a sandbox rootfs.

TemplateCreateRequest

Body of templates.create: a Dockerfile to build into a sandbox rootfs.

TemplateView

A custom rootfs template. Returned by the templates endpoints.

GetTemplateOptions

Extends RequestOptions.

export interface GetTemplateOptions extends RequestOptions {
  /** Set to `"dockerfile"` to include the original build source in the response. */
  include?: "dockerfile";
}

TemplateLogEvent

One NDJSON line from a template build log stream.

TemplateLogsOptions

Options for templates.logs / templates.followLogs. Extends RequestOptions.

export interface TemplateLogsOptions extends RequestOptions {
  /** Filter to one build attempt. Default = all attempts. */
  attempt?: number;
}

Disks

DiskKind

export type DiskKind = "s3";

Storage backend for a registered disk. Only "s3" today (covers AWS S3, Cloudflare R2, MinIO, and any S3-compatible endpoint).

DiskConfig

Non-secret S3 disk configuration. Persisted server-side as JSON.

DiskCredentials

Bucket credentials. Sent only on create; AES-GCM-encrypted at rest and never returned by any read endpoint.

export interface DiskCredentials {
  access_key: string;
  secret_key: string;
}

DiskCreateRequest

Body of POST /v1/disks.

DiskView

User-facing projection of a registered disk. Credentials never appear here.

DiskMountStatus

The server returns pending, mounted, or failed. Some SDK versions still declare the following incompatible union:

export type DiskMountStatus = "pending" | "mounted" | "error" | "unmounting";

Do not check only for error: a failed mount arrives as failed. Until your SDK type includes it, compare the value as a string, for example String(disk.mount_status) === "failed". The server does not emit unmounting as a mount status.

DiskAttachment

One element of CreateSandboxRequest.disks or the body of the attach endpoint.

SandboxDiskView

Per-attachment projection. Returned from GET /v1/sandboxes/:id/disks.

AttachDiskOptions

Options for Sandbox.attachDisk.

Note: detachDisk requires the disk_<ulid> id, not the name.

DetachDiskOptions

Options for Sandbox.detachDisk.

DiskDeletedResponse

export interface DiskDeletedResponse {
  deleted: boolean;
}

DiskDetachedResponse

export interface DiskDetachedResponse {
  detached: boolean;
}

Networks

NetworkCreateRequest

export interface NetworkCreateRequest {
  name: string;
}

NetworkMember

A sandbox attached to an overlay network, with its address on that network.

Network

An overlay network. Returned by the networks endpoints.

Misc / probe responses

OKResponse

Generic acknowledgement returned by endpoints with no richer payload.

export interface OKResponse {
  ok: boolean;
}

HealthzResponse

Liveness probe result. Returned by healthz().

export interface HealthzResponse {
  /** True once the control plane process is up. */
  up: boolean;
}

ReadyzResponse

Readiness probe result. Returned by readyz().

export interface ReadyzResponse {
  /** True once the control plane is ready to serve traffic. */
  ready: boolean;
  /** Why the control plane is not ready, when `ready` is false. */
  reason?: string;
  /** Milliseconds since the scheduler last completed a healthy pass. */
  scheduler_last_ok_ms_ago?: number;
}