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.

TypeScript
Copy
1export interface SuccessEnvelope<T> {
2  status: "success";
3  data: T;
4}
5
6export interface FailEnvelope {
7  status: "fail";
8  /** Field-keyed object or plain string depending on the endpoint. */
9  data: Record<string, unknown> | string;
10}
11
12export interface ErrorEnvelope {
13  status: "error";
14  message: string;
15  code: number;
16}
17
18export type JSendEnvelope<T> = SuccessEnvelope<T> | FailEnvelope | ErrorEnvelope;

Client & request options

RetryOptions

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

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

RetryReason

TypeScript
Copy
1export 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.

TypeScript
Copy
1export interface ClientHooks {
2  onRequest?: (ctx: RequestHookContext) => void | Promise<void>;
3  onResponse?: (ctx: ResponseHookContext) => void | Promise<void>;
4  onRetry?: (ctx: RetryHookContext) => void | Promise<void>;
5}

CreateosSandboxClientOptions

Construction options for CreateosSandboxClient. All fields are optional.

RequestOptions

Per-call overrides accepted by every SDK method.

ExecOptions

TypeScript
Copy
1export 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

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

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

TypeScript
Copy
1export 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.

TypeScript
Copy
1export interface NetworkEntry {
2  id: string;
3}

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.

TypeScript
Copy
1export type SandboxStatus =
2  | "creating"
3  | "running"
4  | "pausing"
5  | "paused"
6  | "resuming"
7  | "forking"
8  | "error"
9  | "destroying"
10  | "destroyed"
11  | "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: node_selector, ingress_enabled, ingress_url_template, and ingress_bytes are absent from the published OpenAPI spec. 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.

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

AddSSHPubkeysResponse

TypeScript
Copy
1export interface AddSSHPubkeysResponse {
2  /** Total `ssh_pubkeys` on the sandbox after the add. */
3  count: number;
4}

DestroyedResponse

TypeScript
Copy
1export interface DestroyedResponse {
2  /** True when the sandbox was already terminal or was reclaimed inline. */
3  status: Extract<SandboxStatus, "destroying" | "destroyed" | "paused" | "error">;
4}

SetEgressRequest

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

EgressView

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

TypeScript
Copy
1export interface EgressView {
2  id: string;
3  /** Active `host:port` allow rules. Empty = allow all. */
4  egress: string[];
5}

BandwidthView

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

RechargeBandwidthRequest

TypeScript
Copy
1export interface RechargeBandwidthRequest {
2  /** Bytes to add to the quota. */
3  add_bytes: number;
4}

ResizeSandboxRequest

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

ResizeSandboxResponse

TypeScript
Copy
1export interface ResizeSandboxResponse {
2  /** Disk size in MiB after the grow. */
3  disk_mib: number;
4}

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.

TypeScript
Copy
1export interface ExecResponse {
2  result: ExecResult;
3  /** Wall-clock time the command ran, in milliseconds. */
4  exec_ms: number;
5}

ExecStreamEvent

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

TypeScript
Copy
1export type ExecStreamEvent =
2  | { type: "stdout";    data: string }
3  | { type: "stderr";    data: string }
4  | { type: "exit";      exitCode: number }
5  | { type: "error";     message: string }
6  | { 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

TypeScript
Copy
1export 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.

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

TemplateLogEvent

One NDJSON line from a template build log stream.

TemplateLogsOptions

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

TypeScript
Copy
1export interface TemplateLogsOptions extends RequestOptions {
2  /** Filter to one build attempt. Default = all attempts. */
3  attempt?: number;
4}

Disks

DiskKind

TypeScript
Copy
1export 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.

TypeScript
Copy
1export interface DiskCredentials {
2  access_key: string;
3  secret_key: string;
4}

DiskCreateRequest

Body of POST /v1/disks.

DiskView

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

DiskMountStatus

TypeScript
Copy
1export type DiskMountStatus = "pending" | "mounted" | "error" | "unmounting";

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. See fc-sdk issue #70.

DetachDiskOptions

Options for Sandbox.detachDisk.

DiskDeletedResponse

TypeScript
Copy
1export interface DiskDeletedResponse {
2  deleted: boolean;
3}

DiskDetachedResponse

TypeScript
Copy
1export interface DiskDetachedResponse {
2  detached: boolean;
3}

Networks

NetworkCreateRequest

TypeScript
Copy
1export interface NetworkCreateRequest {
2  name: string;
3}

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.

TypeScript
Copy
1export interface OKResponse {
2  ok: boolean;
3}

HealthzResponse

Liveness probe result. Returned by healthz().

TypeScript
Copy
1export interface HealthzResponse {
2  /** True once the control plane process is up. */
3  up: boolean;
4}

ReadyzResponse

Readiness probe result. Returned by readyz().

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