Templates, networks & disks

TemplatesApi, NetworksApi, and DisksApi are catalog and cross-sandbox sub-APIs reached from the client via client.templates, client.networks, and client.disks. Per-sandbox disk and network operations (attach, detach, mount) live on the Sandbox handle — see Sandbox.

These classes are also exported types from @nodeops-createos/sandbox but are never constructed directly; obtain instances through CreateosSandboxClient.

TypeScript
1import { CreateosSandboxClient } from "@nodeops-createos/sandbox";
2
3const client = new CreateosSandboxClient({
4  apiKey: process.env.CREATEOS_SANDBOX_API_KEY,
5});

Every method can also throw CreateosSandboxServerError on a 5xx response and CreateosSandboxConnectionError on a network failure. Per-method Throws sections list only the 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

TemplatesApi

Reached via client.templates. Templates are custom rootfs images built from a Dockerfile. Once a template reaches status: "ready" it can be referenced as the rootfs field when creating a sandbox (see CreateSandboxOptions).

templates.list

TypeScript
1list(options?: RequestOptions): Promise<TemplateView[]>

Fetches all templates owned by the caller. Transparently pages through every page and returns the full array; the server clamps limit to 500 per page.

Parameters

Name	Type	Required	Description
`options`	`RequestOptions`	No	Per-request timeout, abort signal, headers, retry override.

Returns

Promise<TemplateView[]> — every template visible to the caller.

Throws

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

Example

TypeScript
1const templates = await client.templates.list();
2console.log(templates.map((t) => t.id));

templates.iterate

TypeScript
1iterate(options?: RequestOptions): AsyncGenerator<TemplateView>

Async generator equivalent of list. Fetches one page at a time and yields each template individually — useful when processing large catalogs without buffering the whole list. The server clamps limit to 500 per page.

Parameters

Name	Type	Required	Description
`options`	`RequestOptions`	No	Per-request timeout, abort signal, headers, retry override.

Returns

AsyncGenerator<TemplateView>

Example

TypeScript
1for await (const t of client.templates.iterate()) {
2  console.log(t.id, t.status);
3}

templates.create

TypeScript
1create(request: TemplateCreateRequest, options?: RequestOptions): Promise<TemplateView>

Submits a Dockerfile to the control plane to build a new rootfs image. The returned TemplateView will typically have status: "pending" or "building" — poll templates.get or stream logs with templates.followLogs to wait for "ready".

Parameters

Name	Type	Required	Description
`request`	`TemplateCreateRequest`	Yes	See fields below.
`options`	`RequestOptions`	No	Per-request timeout, abort signal, headers, retry override.

TemplateCreateRequest fields

Field	Type	Required	Description
`name`	`string`	Yes	User-scoped template name.
`dockerfile`	`string`	Yes	Dockerfile source built into the rootfs image.
`base`	`string`	No	Base rootfs catalog name to build on top of. Empty = host default.

Returns

Promise<TemplateView> — the created template, usually in "pending" or "building" state.

Throws

CreateosSandboxValidationError — request body malformed or Dockerfile rejected.
CreateosSandboxAuthError — API key missing or revoked.
CreateosSandboxPermissionError — caller hit a quota.
CreateosSandboxTimeoutError — per-request timeout elapsed.

Example

TypeScript
1const tpl = await client.templates.create({
2  name: "my-devbox",
3  dockerfile: "FROM debian:trixie-slim\nRUN apt-get update",
4});
5console.log(tpl.id, tpl.status);

templates.get

TypeScript
1get(id: string, options?: GetTemplateOptions): Promise<TemplateView>

Looks up a template by id. Pass include: "dockerfile" to include the original Dockerfile source in the response under tpl.dockerfile.

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Template id (`tpl_…`).
`options`	`GetTemplateOptions`	No	Extends `RequestOptions`. See fields below.

GetTemplateOptions fields (extends RequestOptions)

Field	Type	Required	Description
`include`	`"dockerfile"`	No	Set to `"dockerfile"` to include the original build source in the response.

Returns

Promise<TemplateView>

Throws

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

Example

TypeScript
1const tpl = await client.templates.get("tpl_01h…", { include: "dockerfile" });
2console.log(tpl.status, tpl.dockerfile);

templates.delete

TypeScript
1delete(id: string, options?: RequestOptions): Promise<OKResponse>

Deletes a template. Existing sandboxes built from it are unaffected.

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Template id to delete.
`options`	`RequestOptions`	No	Per-request timeout, abort signal, headers, retry override.

Returns

Promise<OKResponse> — { ok: true } on success.

Throws

CreateosSandboxNotFoundError — template id does not exist.
CreateosSandboxAuthError — API key missing or revoked.
CreateosSandboxPermissionError — template belongs to another tenant.
CreateosSandboxTimeoutError — per-request timeout elapsed.

Example

TypeScript
1await client.templates.delete("tpl_01h…");

templates.logs

TypeScript
1logs(id: string, options?: TemplateLogsOptions): Promise<string>

Fetches the build log so far as a plain-text string. Returns whatever has been written to the build log at the moment of the call; for a live tail use templates.followLogs.

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Template id.
`options`	`TemplateLogsOptions`	No	Extends `RequestOptions`. See fields below.

TemplateLogsOptions fields (extends RequestOptions)

Field	Type	Required	Description
`attempt`	`number`	No	Filter to one build attempt. Default = all attempts.

Returns

Promise<string> — the accumulated build log as plain text.

Throws

CreateosSandboxNotFoundError — no template (or attempt) with that id exists.
CreateosSandboxAuthError — API key missing or revoked.
CreateosSandboxPermissionError — template belongs to another tenant.
CreateosSandboxTimeoutError — per-request timeout elapsed.

Example

TypeScript
1const output = await client.templates.logs("tpl_01h…");
2process.stdout.write(output);

templates.followLogs

TypeScript
1followLogs(id: string, options?: TemplateLogsOptions): AsyncGenerator<TemplateLogEvent>

Streams the build log as an async generator of NDJSON events, following the build in real time until it finishes. Each yielded TemplateLogEvent has an optional line field with a log line. When the build completes the final event has { final: true, status: "ready" | "failed" }. Streaming requests are not retried by the transport.

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Template id.
`options`	`TemplateLogsOptions`	No	`attempt` to tail a specific build attempt; other `RequestOptions` fields apply.

Returns

AsyncGenerator<TemplateLogEvent> where TemplateLogEvent has:

Field	Type	Description
`ts`	`string?`	RFC 3339 timestamp of the event.
`level`	`string?`	Log level string.
`line`	`string?`	One line of build output.
`attempt`	`number?`	Build attempt index.
`final`	`boolean?`	`true` on the terminal frame.
`status`	`string?`	`"ready"` or `"failed"` on the terminal frame.

Throws

CreateosSandboxNotFoundError — no template (or attempt) with that id exists.
CreateosSandboxAuthError — API key missing or revoked.
CreateosSandboxPermissionError — template belongs to another tenant.
CreateosSandboxTimeoutError — per-request timeout elapsed.

Example

TypeScript
1for await (const event of client.templates.followLogs("tpl_01h…")) {
2  if (event.line) process.stdout.write(event.line);
3  if (event.final) console.log("Build finished:", event.status);
4}

NetworksApi

Reached via client.networks. Overlay networks let multiple sandboxes communicate over a private virtual LAN. Create the network here, then attach sandboxes to it via sandbox.attachNetwork or at create time via CreateSandboxRequest.networks (see Sandbox).

networks.list

TypeScript
1list(options?: RequestOptions): Promise<Network[]>

Fetches all overlay networks owned by the caller. Transparently pages through every page and returns the full array; the server clamps limit to 500 per page.

Parameters

Name	Type	Required	Description
`options`	`RequestOptions`	No	Per-request timeout, abort signal, headers, retry override.

Returns

Promise<Network[]>

Throws

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

Example

TypeScript
1const nets = await client.networks.list();
2console.log(nets.map((n) => n.id));

networks.iterate

TypeScript
1iterate(options?: RequestOptions): AsyncGenerator<Network>

Async generator equivalent of list. Fetches one page at a time and yields each network individually.

Parameters

Name	Type	Required	Description
`options`	`RequestOptions`	No	Per-request timeout, abort signal, headers, retry override.

Returns

AsyncGenerator<Network>

Example

TypeScript
1for await (const n of client.networks.iterate()) {
2  console.log(n.id, n.name);
3}

networks.create

TypeScript
1create(request: NetworkCreateRequest, options?: RequestOptions): Promise<Network>

Creates an overlay network. Members are attached later via sandbox.attachNetwork on the Sandbox handle — see Sandbox.

Parameters

Name	Type	Required	Description
`request`	`NetworkCreateRequest`	Yes	See fields below.
`options`	`RequestOptions`	No	Per-request timeout, abort signal, headers, retry override.

NetworkCreateRequest fields

Field	Type	Required	Description
`name`	`string`	Yes	User-scoped network name.

Returns

Promise<Network> where Network has id, name, created_at, and optionally member_count and members.

Throws

CreateosSandboxValidationError — request body malformed or CIDR conflicts.
CreateosSandboxAuthError — API key missing or revoked.
CreateosSandboxPermissionError — caller hit a quota.
CreateosSandboxTimeoutError — per-request timeout elapsed.

Example

TypeScript
1const net = await client.networks.create({ name: "team-net" });
2console.log(net.id);

networks.get

TypeScript
1get(id: string, options?: RequestOptions): Promise<Network>

Looks up an overlay network by id. The detail response includes the members array of attached sandboxes with their per-network addresses.

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Network id (`net_…`).
`options`	`RequestOptions`	No	Per-request timeout, abort signal, headers, retry override.

Returns

Promise<Network>

Throws

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

Example

TypeScript
1const net = await client.networks.get("net_01h…");
2console.log(net.members);

networks.delete

TypeScript
1delete(id: string, options?: RequestOptions): Promise<OKResponse>

Deletes an overlay network. Member sandboxes are detached but not destroyed. Returns CreateosSandboxValidationError if the network still has active members — detach them first.

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Network id to delete.
`options`	`RequestOptions`	No	Per-request timeout, abort signal, headers, retry override.

Returns

Promise<OKResponse> — { ok: true } on success.

Throws

CreateosSandboxNotFoundError — network id does not exist.
CreateosSandboxValidationError — network still has active members.
CreateosSandboxAuthError — API key missing or revoked.
CreateosSandboxPermissionError — network belongs to another tenant.
CreateosSandboxTimeoutError — per-request timeout elapsed.

Example

TypeScript
1await client.networks.delete("net_01h…");

DisksApi

Reached via client.disks. Disks are user-registered S3 buckets that can be mounted into one or more sandboxes. The control plane HEADs the bucket when you register a disk, so bad credentials or a typo in the bucket name returns 400 immediately.

Per-sandbox mount and unmount operations (attachDisk, detachDisk) live on the Sandbox handle — see Sandbox. Note that detachDisk requires the disk's id (disk_<ulid>), not its name; use disks.get to resolve a name to an id first.

The control plane returns HTTP 503 when the operator has not provisioned a disk-credential cipher key — this is a configuration state, not a transient failure, and surfaces as CreateosSandboxServerError.

disks.list

TypeScript
1list(options?: RequestOptions): Promise<DiskView[]>

Fetches all registered S3 disks owned by the caller. Transparently pages through every page and returns the full array; the server clamps limit to 500 per page.

Parameters

Name	Type	Required	Description
`options`	`RequestOptions`	No	Per-request timeout, abort signal, headers, retry override.

Returns

Promise<DiskView[]>

Throws

CreateosSandboxAuthError — API key missing or revoked.
CreateosSandboxServerError — 5xx from the control plane, including 503 when the disks API is not configured by the operator.
CreateosSandboxTimeoutError — per-request timeout elapsed.

Example

TypeScript
1const disks = await client.disks.list();
2console.log(disks.map((d) => d.name));

disks.iterate

TypeScript
1iterate(options?: RequestOptions): AsyncGenerator<DiskView>

Async generator equivalent of list. Fetches one page at a time and yields each disk individually.

Parameters

Name	Type	Required	Description
`options`	`RequestOptions`	No	Per-request timeout, abort signal, headers, retry override.

Returns

AsyncGenerator<DiskView>

Example

TypeScript
1for await (const d of client.disks.iterate()) {
2  console.log(d.name, d.kind);
3}

disks.create

TypeScript
1create(request: DiskCreateRequest, options?: RequestOptions): Promise<DiskView>

Registers an S3 bucket as a mountable disk. The server HEADs the bucket before accepting — a bad bucket name or invalid credentials returns a 400 (CreateosSandboxValidationError).

Parameters

Name	Type	Required	Description
`request`	`DiskCreateRequest`	Yes	See fields below.
`options`	`RequestOptions`	No	Per-request timeout, abort signal, headers, retry override.

DiskCreateRequest fields

Field	Type	Required	Description
`name`	`string`	Yes	User-scoped name. Must match `^[a-z0-9][a-z0-9-]{0,62}$`.
`kind`	`DiskKind`	Yes	Currently `"s3"`.
`config`	`DiskConfig`	Yes	Non-secret S3 config: `bucket`, `endpoint`, optional `region`, optional `use_path_style`.
`credentials`	`DiskCredentials`	Yes	`access_key` and `secret_key`. Stored encrypted server-side; never returned in responses.

Returns

Promise<DiskView> — the registered disk's public view (id, name, kind, config, created_at). Credentials are not echoed back.

Throws

CreateosSandboxValidationError — bucket HEAD failed or credentials rejected.
CreateosSandboxAuthError — API key missing or revoked.
CreateosSandboxPermissionError — caller hit a quota.
CreateosSandboxServerError — 5xx from the control plane, including 503 when the disks API is not configured.
CreateosSandboxTimeoutError — per-request timeout elapsed.

Example

TypeScript
1const disk = await client.disks.create({
2  name: "shared-data",
3  kind: "s3",
4  config: {
5    bucket: "my-bucket",
6    endpoint: "https://s3.us-east-1.amazonaws.com",
7    region: "us-east-1",
8  },
9  credentials: {
10    access_key: process.env.AWS_ACCESS_KEY_ID!,
11    secret_key: process.env.AWS_SECRET_ACCESS_KEY!,
12  },
13});
14console.log(disk.id);

disks.get

TypeScript
1get(idOrName: string, options?: RequestOptions): Promise<DiskView>

Looks up a disk by its id (disk_<ulid>) or by its user-scoped name. Use this to resolve a name to an id when you need the disk_<ulid> form required by sandbox.detachDisk.

Parameters

Name	Type	Required	Description
`idOrName`	`string`	Yes	Disk id (`disk_…`) or user-scoped name.
`options`	`RequestOptions`	No	Per-request timeout, abort signal, headers, retry override.

Returns

Promise<DiskView>

Throws

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

Example

TypeScript
1const disk = await client.disks.get("shared-data");
2console.log(disk.id, disk.config.bucket);

disks.delete

TypeScript
1delete(idOrName: string, options?: RequestOptions): Promise<DiskDeletedResponse>

Deletes a disk registration. Returns CreateosSandboxValidationError if the disk is still attached to a non-destroyed sandbox — detach it first via sandbox.detachDisk.

Parameters

Name	Type	Required	Description
`idOrName`	`string`	Yes	Disk id (`disk_…`) or user-scoped name.
`options`	`RequestOptions`	No	Per-request timeout, abort signal, headers, retry override.

Returns

Promise<DiskDeletedResponse> — { deleted: true } on success.

Throws

CreateosSandboxNotFoundError — disk id or name does not exist.
CreateosSandboxValidationError — disk is still attached to a sandbox.
CreateosSandboxAuthError — API key missing or revoked.
CreateosSandboxPermissionError — disk belongs to another tenant.
CreateosSandboxTimeoutError — per-request timeout elapsed.

Example

TypeScript
1await client.disks.delete("shared-data");

disks.rotateCredentials

TypeScript
1rotateCredentials(
2  idOrName: string,
3  credentials: DiskCredentials,
4  options?: RequestOptions,
5): Promise<DiskView>

Rotates a disk's S3 credentials. Replaces the stored access_key / secret_key without touching any other disk config. Sandboxes currently holding the disk pick up the new credentials on their next resume.

Parameters

Name	Type	Required	Description
`idOrName`	`string`	Yes	Disk id (`disk_…`) or user-scoped name.
`credentials`	`DiskCredentials`	Yes	`{ access_key, secret_key }` — the new credentials to store.
`options`	`RequestOptions`	No	Per-request timeout, abort signal, headers, retry override.

Returns

Promise<DiskView> — the disk's public view after the update. Credentials are not echoed back.

Throws

CreateosSandboxValidationError — access_key or secret_key is empty.
CreateosSandboxNotFoundError — disk id or name does not exist.
CreateosSandboxAuthError — API key missing or revoked.
CreateosSandboxPermissionError — disk belongs to another tenant.
CreateosSandboxTimeoutError — per-request timeout elapsed.

Example

TypeScript
1await client.disks.rotateCredentials("shared-data", {
2  access_key: process.env.NEW_AWS_ACCESS_KEY_ID!,
3  secret_key: process.env.NEW_AWS_SECRET_ACCESS_KEY!,
4});

100,000+ Builders. One Workspace.