CreateosSandboxClient

The SDK entry point. Owns transport configuration (auth, base URL, timeouts, retries) and exposes catalog and identity calls, the sandbox factory, and the templates / networks / disks sub-APIs. Every method reaches the control plane and also throws CreateosSandboxServerError on 5xx responses and CreateosSandboxConnectionError on network failure; per-method Throws sections list only conditions specific to that call.

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

Construction

import { createClient } from "@nodeops-createos/sandbox";
 
// Read credentials from environment variables
const box = createClient();
 
// Explicit options
const box = createClient({
  baseUrl: "https://api.sb.createos.sh",
  apiKey: process.env.CREATEOS_SANDBOX_API_KEY,
});

createClient is the recommended entry point. CreateosSandboxClient is the underlying class it wraps: createClient(options) is exactly new CreateosSandboxClient(options). Reach for the class directly only when you need to subclass it or reference it as a type.

new CreateosSandboxClient(options?)

new CreateosSandboxClient(options: CreateosSandboxClientOptions = {}): CreateosSandboxClient

Resolves options against environment defaults and constructs the transport. Throws CreateosSandboxError synchronously for invalid options (invalid baseUrl URL, both apiKey and authHeaders provided, no fetch available).

Options

Env-var resolution order: explicit option wins, then environment variable, then the built-in default.

retry shape (RetryOptions):

Idempotent methods (GET/HEAD/PUT/DELETE) retry on network errors and 408/500/502/503/504. Non-idempotent methods retry only on 429/503. Streaming requests are never retried.

hooks shape (ClientHooks):

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

If a hook returns a promise it adds its own latency to the call, so keep hook work cheap, or dispatch slow work without awaiting the promise. Errors thrown inside a hook are swallowed so a misbehaving observer cannot crash a real request.

createClient(options?)

function createClient(
  options?: CreateosSandboxClientOptions,
): CreateosSandboxClient;

Convenience factory. Equivalent to new CreateosSandboxClient(options).

Example

import { createClient } from "@nodeops-createos/sandbox";
 
const box = createClient({ apiKey: process.env.CREATEOS_SANDBOX_API_KEY });

Accessors

Sandbox factory

createSandbox

createSandbox(
  request: CreateSandboxRequest,
  options?: CreateSandboxOptions,
): Promise<Sandbox>

Creates a sandbox and, by default, waits until it reaches running before resolving. Pass { wait: false } to return a Sandbox handle as soon as the server row exists (status will be creating).

Internally the SDK issues POST /v1/sandboxes, then immediately fetches the full SandboxView via GET /v1/sandboxes/:id (the create response lacks status and created_at required by the handle). When wait is not false it then polls waitUntilRunning with a budget of waitTimeoutMs (default 120 s).

CreateSandboxRequest fields

bandwidth_quota_bytes is not settable at create time; the server rejects a non-zero value. Grow bandwidth post-create with Sandbox.rechargeBandwidth().

CreateSandboxOptions fields

Extends RequestOptions.

Throws

• CreateosSandboxValidationError: shape or rootfs unknown.
• CreateosSandboxAuthError: API key missing or revoked.
• CreateosSandboxPermissionError: caller hit quota.
• CreateosSandboxTimeoutError: per-request timeout or wait budget elapsed.

Example

import { createClient } from "@nodeops-createos/sandbox";
 
const box = createClient();
const sandbox = await box.createSandbox({
  shape: "s-4vcpu-4gb",
  rootfs: "devbox:1",
  envs: { CI: "1" },
});
try {
  const { result } = await sandbox.runCommand("bash", ["-c", "echo hello"]);
  console.log(result.stdout);
} finally {
  await sandbox.destroy();
}

getSandbox

getSandbox(id: string, options?: RequestOptions): Promise<Sandbox>

Connects to an existing sandbox by id. Returns a Sandbox handle backed by the current server-side view.

Parameters

Returns Promise<Sandbox>

Throws

• CreateosSandboxNotFoundError: no sandbox with that id exists.
• CreateosSandboxAuthError: API key missing or revoked.
• CreateosSandboxPermissionError: sandbox belongs to another tenant.
• CreateosSandboxTimeoutError: per-request timeout elapsed.

Example

const sandbox = await box.getSandbox("sb-01h…");
console.log(sandbox.status);

getSandboxByIP

getSandboxByIP(ip: string, options?: RequestOptions): Promise<Sandbox>

Connects to an existing sandbox by its VM private IP.

Parameters

Returns Promise<Sandbox>

Throws

• CreateosSandboxNotFoundError: no sandbox with that IP exists.
• CreateosSandboxAuthError: API key missing or revoked.
• CreateosSandboxPermissionError: sandbox belongs to another tenant.
• CreateosSandboxTimeoutError: per-request timeout elapsed.

Example

const sandbox = await box.getSandboxByIP("10.0.0.42");
console.log(sandbox.id);

listSandboxes

listSandboxes(options?: ListSandboxesOptions): Promise<Sandbox[]>

Lists the caller's sandboxes as connected Sandbox handles. Walks every page by default (server caps pages at 500 items). Pass limit to cap the total number of handles returned.

Parameters (ListSandboxesOptions) extends RequestOptions.

Returns Promise<Sandbox[]>

Throws

• CreateosSandboxAuthError: API key missing or revoked.
• CreateosSandboxTimeoutError: per-request timeout elapsed.

Example

const running = await box.listSandboxes({ status: "running" });
for (const s of running) console.log(s.id, s.ip);

iterateSandboxes

iterateSandboxes(options?: ListSandboxesOptions): AsyncGenerator<Sandbox>

Streams the caller's sandboxes as connected handles, fetching one page at a time. Prefer over listSandboxes when the list may be large and you want to start processing before every page is fetched.

Accepts the same ListSandboxesOptions as listSandboxes.

Returns AsyncGenerator<Sandbox>

Example

for await (const s of box.iterateSandboxes({ status: "running" })) {
  console.log(s.id, s.ip);
}

Catalog & identity

whoami

whoami(options?: RequestOptions): Promise<WhoAmIView>

Returns the identity associated with the configured API key.

Returns Promise<WhoAmIView>: { user_id: string; stats: WhoAmIStatsView }.

Throws

• CreateosSandboxAuthError: API key missing or revoked.
• CreateosSandboxTimeoutError: per-request timeout elapsed.

Example

const me = await box.whoami();
console.log(me.user_id, me.stats.running);

listShapes

listShapes(options?: RequestOptions): Promise<Shape[]>

Lists the available sandbox shapes (vCPU / RAM / disk presets). Unauthenticated; no API key required.

Returns Promise<Shape[]>: each Shape has id, vcpu, mem_mib, default_disk_mib, and optional cpu_quota_pct. See Shape for the full type.

Throws

• CreateosSandboxTimeoutError: per-request timeout elapsed.

Example

const shapes = await box.listShapes();
console.log(shapes.map((s) => `${s.id}: ${s.vcpu} vCPU, ${s.mem_mib} MiB`));

listRootfs

listRootfs(options?: RequestOptions): Promise<RootfsData>

Lists the catalog of built-in rootfs images. Unauthenticated. The response carries the default name used when a create request omits rootfs, a plain rootfs string array of valid names, and optional rich entries metadata.

Returns Promise<RootfsData>: { rootfs: string[]; default: string; entries?: RootfsEntry[] }.

Throws

• CreateosSandboxTimeoutError: per-request timeout elapsed.

Example

const catalog = await box.listRootfs();
console.log("default rootfs:", catalog.default);
console.log("available:", catalog.rootfs);

listHosts

listHosts(options?: RequestOptions): Promise<HostPublic[]>

Lists the worker hosts visible to the caller. Walks every page.

Returns Promise<HostPublic[]>: each entry has id, status ("active" | "draining" | "dead"), free_mib, vm_count, and optional rootfses.

Throws

• CreateosSandboxAuthError: API key missing or revoked.
• CreateosSandboxPermissionError: caller cannot enumerate hosts.
• CreateosSandboxTimeoutError: per-request timeout elapsed.

Example

const hosts = await box.listHosts();
console.log(hosts.map((h) => `${h.id}: ${h.free_mib} MiB free`));

iterateHosts

iterateHosts(options?: RequestOptions): AsyncGenerator<HostPublic>

Streams worker hosts one page at a time. Prefer over listHosts for large fleets.

Returns AsyncGenerator<HostPublic>

Example

for await (const h of box.iterateHosts()) console.log(h.id, h.status);

healthz

healthz(options?: RequestOptions): Promise<HealthzResponse>

Liveness probe. Unauthenticated. Returns { up: true } once the control plane is accepting traffic. Does not check database or scheduler readiness; use readyz for that.

Returns Promise<HealthzResponse>: { up: boolean }.

Throws

• CreateosSandboxTimeoutError: per-request timeout elapsed.

Example

const { up } = await box.healthz();
console.log("live:", up);

readyz

readyz(options?: RequestOptions): Promise<ReadyzResponse>

Readiness probe. Unauthenticated. Returns { ready: false, reason } instead of throwing when the server responds 503: callers can distinguish "not ready yet" from a real error without catching. Retries are disabled for this call.

Returns Promise<ReadyzResponse>: { ready: boolean; reason?: string; scheduler_last_ok_ms_ago?: number }.

Throws

• CreateosSandboxTimeoutError: per-request timeout elapsed.
• CreateosSandboxServerError: any non-503 error response.

Example

const r = await box.readyz();
if (!r.ready) {
  console.warn("control plane not ready:", r.reason);
}

Per-request options (RequestOptions)

Every method accepts an optional RequestOptions object as its last argument. These override the client-level defaults for that single call.

Example: cancel a slow list

const controller = new AbortController();
setTimeout(() => controller.abort(), 5_000);
 
const sandboxes = await box.listSandboxes({ signal: controller.signal });

Sub-APIs

The client exposes three sub-API objects for operations on named resources:

Full method reference: Sub-APIs.

See also

• Sandbox: per-sandbox operations returned by factory methods above.
• Sub-APIs: TemplatesApi, NetworksApi, DisksApi.
• Errors: full error class hierarchy.
• Types: wire type reference.
• Helpers: CreateosSandboxHttp transport (accessed via box.http).