Use blueprints

Create reusable Devbox configurations with client.blueprints. Create, fetch, list, update, and delete blueprints, or iterate through every blueprint in a workspace.

`blueprints.create()`

Create a named blueprint from a complete definition.

Example

import { createDevboxClient } from "@namespacelabs/sdk/devbox";

const client = createDevboxClient();
const blueprint = await client.blueprints.create("node-development", {
  image: "builtin:agents",
  size: "m",
  environment: { NODE_ENV: "development" },
  volumeSizeGB: 50,
});

API reference

create(name: string, definition: BlueprintDefinition, options?: OperationOptions): Promise<Blueprint>

Arguments and options

string

required

The blueprint name.

BlueprintDefinition

required

The complete configuration. See Blueprint definitions.

OperationOptions

Hide properties

AbortSignal

Cancels the operation when aborted.

number

The operation timeout in milliseconds.

The SDK defaults site to "iad" and access to "private". Blueprint sizes are resolved by the SDK and must be "s", "m", "l", or "xl". volumeSizeGB must be a non-negative safe integer.

Return value

Returns the created Blueprint.

`blueprints.get()`

Fetch a blueprint by name.

Example

const blueprint = await client.blueprints.get("node-development");

API reference

get(name: string, options?: OperationOptions): Promise<Blueprint>

Arguments and options

string

required

The blueprint name.

OperationOptions

Optional cancellation signal and timeout.

Return value

Returns the matching Blueprint.

`blueprints.list()`

List one page of blueprints.

Example

const page = await client.blueprints.list({
  limit: 25,
  orderBy: "updated",
});

API reference

list(options?: ListBlueprintsOptions): Promise<Page<Blueprint>>

Arguments and options

ListBlueprintsOptions

Hide properties

string

An opaque cursor returned by the previous page.

number

The maximum entries to return. Must be a non-negative safe integer.

"created" | "updated"

The timestamp used to order results.

AbortSignal

Cancels the operation when aborted.

number

The operation timeout in milliseconds.

Return value

Returns a Page<Blueprint>.

`blueprints.iterate()`

Iterate through all blueprints, fetching additional pages automatically.

Example

for await (const blueprint of client.blueprints.iterate({ orderBy: "created" })) {
  console.log(blueprint.name);
}

API reference

iterate(options?: Omit<ListBlueprintsOptions, "cursor">): AsyncIterableIterator<Blueprint>

Arguments and options

Accepts the limit, orderBy, signal, and timeoutMs list options. Do not pass a cursor because iteration manages pagination.

Return value

Returns an async iterator of Blueprint objects.

`blueprints.update()`

Replace the complete definition of an existing blueprint.

Example

const current = await client.blueprints.get("node-development");

const updated = await client.blueprints.update("node-development", {
  ...current.definition,
  size: "l",
  environment: {
    ...current.definition.environment,
    CI: "true",
  },
});

API reference

update(name: string, definition: BlueprintDefinition, options?: OperationOptions): Promise<Blueprint>

Arguments and options

string

required

The blueprint name.

BlueprintDefinition

required

The complete replacement definition.

OperationOptions

Optional cancellation signal and timeout.

The same defaults and validation as create() apply.

update() replaces the stored definition wholesale. It first resolves the blueprint by name, then performs a last-write-wins update without compare-and-swap protection. Preserve fields explicitly, and avoid concurrent updates that could silently overwrite each other.

Return value

Returns the updated Blueprint.

`blueprints.delete()`

Delete a blueprint by name.

Example

await client.blueprints.delete("node-development");

API reference

delete(name: string, options?: OperationOptions): Promise<void>

Arguments and options

string

required

The blueprint name.

OperationOptions

Optional cancellation signal and timeout.

Return value

The promise resolves after the blueprint has been deleted.

Blueprint definitions

interface BlueprintDefinition {
  image: string;
  size?: MachineSize;
  site?: string;
  description?: string;
  access?: "private" | "workspace";
  environment?: Record<string, string>;
  volumeSizeGB?: number;
  ephemeral?: boolean | { stoppedRetentionMs?: number };
  features?: string[];
  networkPolicy?: { allowedDomains: string[]; advisory?: boolean };
  busyTimeoutMs?: number;
}

string

required

An image name or a full image reference. Strings containing /, @, or : are treated as full references.

MachineSize

One of "s", "m", "l", or "xl".

string

The site where Devboxes are created. Defaults to "iad".

string

A description shown with the blueprint.

"private" | "workspace"

Who can use the blueprint. Defaults to "private".

Record<string, string>

Environment variables added to Devboxes.

number

Persistent volume size in GB. Must be a non-negative safe integer.

boolean | { stoppedRetentionMs?: number }

Enables ephemeral behavior. The object form sets retention after stopping.

string[]

Devbox feature names to enable.

NetworkPolicy

Egress policy for the Devbox.

Hide properties

string[]

required

Domains the Devbox may access.

boolean

Reports violations without enforcement. Defaults to false.

number

Minimum time the Devbox remains busy.

Blueprint fields

string

required

The immutable blueprint ID.

string

required

The blueprint name.

bigint

required

The blueprint version.

Date

When the blueprint was created.

Date

When the blueprint was last updated.

BlueprintDefinition

required

The stored definition.

Page fields

Blueprint[]

required

The blueprints in this page.

string

An opaque cursor for the next page. Its absence means there are no more results.

See Create and manage Devboxes to create a Devbox from a blueprint and Manage images to register images used by blueprints.

Devbox SDK

Automation

CLI

`blueprints.create()`

Example

API reference

Arguments and options

Return value

`blueprints.get()`

Example

API reference

Arguments and options

Return value

`blueprints.list()`

Example

API reference

Arguments and options

Return value

`blueprints.iterate()`

Example

API reference

Arguments and options

Return value

`blueprints.update()`

Example

API reference

Arguments and options

Return value

`blueprints.delete()`

Example

API reference

Arguments and options

Return value

Blueprint definitions

Blueprint fields

Page fields

​blueprints.create()

​Example

​API reference

​Arguments and options

​Return value

​blueprints.get()

​Example

​API reference

​Arguments and options

​Return value

​blueprints.list()

​Example

​API reference

​Arguments and options

​Return value

​blueprints.iterate()

​Example

​API reference

​Arguments and options

​Return value

​blueprints.update()

​Example

​API reference

​Arguments and options

​Return value

​blueprints.delete()

​Example

​API reference

​Arguments and options

​Return value

​Blueprint definitions

​Blueprint fields

​Page fields

​Related documentation

`blueprints.create()`

Example

API reference

Arguments and options

Return value

`blueprints.get()`

Example

API reference

Arguments and options

Return value

`blueprints.list()`

Example

API reference

Arguments and options

Return value

`blueprints.iterate()`

Example

API reference

Arguments and options

Return value

`blueprints.update()`

Example

API reference

Arguments and options

Return value

`blueprints.delete()`

Example

API reference

Arguments and options

Return value

Blueprint definitions

Blueprint fields

Page fields

Related documentation