Create and manage Devboxes - Namespace Documentation

Create Devboxes from an image, a macOS base image, or a blueprint. This page also covers listing Devboxes and controlling their lifecycle through resource and handle methods.

Connection-backed operations, including commands, file access, terminals, and display access, automatically start a stopped Devbox. Explicitly call start() when you need to wait for readiness before another operation.

`devboxes.create()`

Create a Devbox and return an operational handle. Devboxes start by default. Set start: false to create one without activating it.

Example

Create a Linux Devbox from an image:

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

const client = createDevboxClient();

const devbox = await client.devboxes.create({
  name: "sdk-example",
  imageName: "builtin:agents",
});

API reference

create(input: CreateDevboxInput, options?: OperationOptions): Promise<Devbox>

Arguments and options

CreateDevboxInput

required

The Devbox name and configuration.

Hide common properties

string

required

The Devbox name.

string

default:"iad"

The site where the Devbox is created. For blueprint creation, omitting this property preserves the blueprint’s site.

string

A description of the Devbox’s intended use.

"private" | "workspace"

The access mode. When omitted, the service chooses the tenant default. For blueprint creation, omitting this property preserves the blueprint’s access mode.

boolean

default:"true"

Whether to start the Devbox and wait for it to become ready during creation.

Hide direct creation properties

"linux" | "macos"

default:"linux"

The operating system. macOS Devboxes use a Namespace-managed Apple Silicon base image and cannot set image or imageName.

string

An image reference, or a registered image name without /, @, or :. Use imageName to explicitly select an image by name. Cannot be combined with imageName, os: "macos", or blueprint.

string

A built-in or registered image name, such as "builtin:agents". Cannot be combined with image, os: "macos", or blueprint.

MachineSize

A named machine size. Linux creation passes the name to the service, which can accept sizes added after this SDK release. macOS supports "m" (6 vCPUs, 14 GB) and "l" (12 vCPUs, 28 GB), and defaults to "m".

number

The volume size in GB. The value must be a non-negative safe integer.

string

A repository to check out in the Devbox.

Record<string, string>

Environment variables added to the Devbox.

boolean | { stoppedRetentionMs?: number }

Enables automatic expiration. The object form configures how long the stopped Devbox is retained.

boolean

Whether the Devbox runs in privileged mode.

string[]

Feature names to enable.

NetworkPolicy

Restricts outbound network access.

Hide properties

string[]

required

Domains allowed by the policy.

boolean

default:"false"

Whether violations are advisory instead of enforced.

Hide blueprint creation properties

string

required

The blueprint name. This variant accepts only name, blueprint, site, purpose, access, and start. Direct creation properties cannot be combined with a blueprint.

OperationOptions

Cancellation and timeout options. See Shared operation options.

Return value

Returns a Devbox handle. Its id, name, and info properties describe the created Devbox. A started Devbox reports info.state as "running"; one created with start: false reports "stopped".

More examples

Create a macOS Devbox

const mac = await client.devboxes.create({
  name: "sdk-mac",
  os: "macos",
  size: "m",
});

Create a stopped Devbox from a blueprint

const devbox = await client.devboxes.create({
  name: "sdk-blueprint",
  blueprint: "typescript",
  start: false,
});

`devboxes.get()`

Fetch a Devbox by ID or name. Unlike list(), this call resolves the current runtime state.

Example

const devbox = await client.devboxes.get("sdk-example");

API reference

get(ref: string, options?: OperationOptions): Promise<Devbox>

Arguments and options

string

required

The Devbox ID or name.

OperationOptions

Cancellation and timeout options. See Shared operation options.

Return value

Returns a new Devbox handle whose info.state is "running" or "stopped".

`devboxes.list()`

Return one page of Devboxes. Listing avoids per-Devbox runtime lookups, so each returned handle has info.state set to "unknown" and no instanceId.

Example

const page = await client.devboxes.list({
  limit: 20,
  orderBy: "last-used",
});
page.items.forEach((devbox) => console.log(devbox.info));

API reference

list(options?: ListDevboxesOptions): Promise<Page<Devbox>>

Arguments and options

ListDevboxesOptions

Pagination, filtering, cancellation, and timeout options.

Hide properties

string

The opaque nextCursor from the previous page.

number

The maximum number of entries requested. The value must be a non-negative safe integer.

"created" | "last-used"

The field used to order results.

boolean

When set, return only ephemeral or only non-ephemeral Devboxes.

AbortSignal

Cancels the request when aborted.

number

The request timeout in milliseconds.

Return value

Returns items: Devbox[] and an optional opaque nextCursor. Pass nextCursor as the next call’s cursor, or use iterate() to traverse every page automatically. Call refresh() on a listed handle before relying on its runtime state.

`devboxes.iterate()`

Iterate over all Devboxes, fetching subsequent pages automatically. Handles have the same "unknown" state semantics as list().

Example

for await (const devbox of client.devboxes.iterate({ ephemeral: false })) {
  console.log(devbox.name);
}

API reference

iterate(options?: Omit<ListDevboxesOptions, "cursor">): AsyncIterableIterator<Devbox>

Arguments and options

Omit<ListDevboxesOptions, "cursor">

The limit, orderBy, ephemeral, signal, and timeoutMs options from list(). Pagination cursors are managed internally.

Return value

Returns an async iterator that yields each Devbox from every page.

`devboxes.start()`

Start a Devbox and wait for readiness. Start it by ID or name, or use devbox.start() when you already have a Devbox object.

By ID or name
Devbox Object

Example

const devbox = await client.devboxes.start("sdk-example");

API reference

start(ref: string, options?: OperationOptions): Promise<Devbox>

Arguments and options

string

required

The Devbox ID or name.

OperationOptions

Cancellation and timeout options. See Shared operation options.

Return value

Returns a ready Devbox object with refreshed information and info.state set to "running".

Example

const devbox = await client.devboxes.get("sdk-example");
await devbox.start();

API reference

start(options?: OperationOptions): Promise<this>

Arguments and options

OperationOptions

Cancellation and timeout options. See Shared operation options.

Return value

Updates and returns the same Devbox object, with refreshed information and info.state set to "running".

`devboxes.stop()`

Stop a Devbox and invalidate its cached connection. Stop it by ID or name, or use devbox.stop() when you already have a Devbox object.

By ID or name
Devbox Object

Example

const devbox = await client.devboxes.stop("sdk-example");

API reference

stop(ref: string, options?: OperationOptions): Promise<Devbox>

Arguments and options

string

required

The Devbox ID or name.

OperationOptions

Cancellation and timeout options. See Shared operation options.

Return value

Returns a Devbox object with refreshed information and info.state set to "stopped".

Running a command or using another connection-backed API on this object starts the Devbox again automatically.

Example

const devbox = await client.devboxes.get("sdk-example");
await devbox.stop();

API reference

stop(options?: OperationOptions): Promise<this>

Arguments and options

OperationOptions

Cancellation and timeout options. See Shared operation options.

Return value

Updates and returns the same Devbox object, with refreshed information and info.state set to "stopped".

Running a command or using another connection-backed API on this object starts the Devbox again automatically.

`devboxes.delete()`

Delete a Devbox and invalidate its cached connection. Delete it by ID or name, or use devbox.delete() when you already have a Devbox object.

By ID or name
Devbox Object

Example

await client.devboxes.delete("sdk-example");

API reference

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

Arguments and options

string

required

The Devbox ID or name.

OperationOptions

Cancellation and timeout options. See Shared operation options.

Return value

Returns no value. The promise resolves after the Devbox has been deleted.

Example

const devbox = await client.devboxes.get("sdk-example");
await devbox.delete();

API reference

delete(options?: OperationOptions): Promise<void>

Arguments and options

OperationOptions

Cancellation and timeout options. See Shared operation options.

Return value

Returns no value. The promise resolves after the Devbox has been deleted.

The object is not marked as deleted. Do not call any of its properties or methods after delete() resolves.

`devbox.refresh()`

Re-fetch this Devbox, resolve its authoritative runtime state, and replace the handle’s info snapshot.

Example

const devbox = await client.devboxes.get("sdk-example");
await devbox.refresh();

API reference

refresh(options?: OperationOptions): Promise<this>

Arguments and options

OperationOptions

Cancellation and timeout options. See Shared operation options.

Return value

Returns the same handle with current information and info.state set to "running" or "stopped".

`devbox.update()`

Update mutable Devbox settings and replace the handle’s info snapshot. This method preserves the state and instance ID currently recorded by the handle.

Example

const devbox = await client.devboxes.get("sdk-example");
await devbox.update({
  size: "m",
  busyTimeoutMs: 10 * 60_000,
});

API reference

update(input: UpdateDevboxInput, options?: OperationOptions): Promise<this>

Arguments and options

UpdateDevboxInput

required

The settings to update.

Hide properties

MachineSize

A size known to this SDK. Linux supports "s", "m", "l", and "xl"; macOS supports "m" and "l". Unlike Linux creation, updates resolve the size client-side and reject unknown names.

number

The volume size in GB. The value must be a non-negative safe integer.

number

The minimum duration in milliseconds for which the Devbox remains busy.

boolean

Whether the Devbox runs in privileged mode.

NetworkPolicy

The outbound network policy, with allowedDomains and optional advisory properties as described under create().

OperationOptions

Cancellation and timeout options. See Shared operation options.

Return value

Returns the same handle with updated info. Call refresh() if another actor may have changed the Devbox’s runtime state.

Devbox information

Every handle exposes immutable id and name accessors and a read-only info snapshot. Lifecycle methods replace this snapshot, so read devbox.info again after awaiting one of those methods.

interface DevboxInfo {
  id: string;
  name: string;
  state: "running" | "stopped" | "unknown";
  instanceId?: string;
  image: string;
  imageName?: string;
  blueprint?: { id: string; name: string };
  size?: MachineSize;
  shape?: InstanceShape;
  site?: string;
  creator?: string;
  createdAt?: Date;
  lastUsedAt?: Date;
  workspaceDir?: string;
  defaultDir?: string;
  user?: string;
  shell?: string;
  volumeSizeGB?: number;
  purpose?: string;
  ephemeral: boolean;
}

get(), refresh(), start(), and stop() resolve runtime state. list() and iterate() report "unknown" and omit instanceId. Connection-backed operations update the local snapshot to "running", but info is not a live subscription to server-side changes. The optional shape contains vCPUs, memoryMB, and optional architecture and os fields. Other optional fields are absent when the service does not provide them.

Shared operation options

All methods on this page accept OperationOptions.

OperationOptions

Controls cancellation and timeout behavior.

Hide properties

AbortSignal

Cancels the operation when the signal is aborted.

number

The operation timeout in milliseconds.

Run commands

Execute structured commands and shell scripts.

Work with files

Transfer and manipulate Devbox files.

Use blueprints

Define reusable Devbox configurations.

​devboxes.create()

​Example

​API reference

​Arguments and options

​Return value

​More examples

​Create a macOS Devbox

​Create a stopped Devbox from a blueprint

​devboxes.get()

​Example

​API reference

​Arguments and options

​Return value

​devboxes.list()

​Example

​API reference

​Arguments and options

​Return value

​devboxes.iterate()

​Example

​API reference

​Arguments and options

​Return value

​devboxes.start()

​Example

​API reference

​Arguments and options

​Return value

​Example

​API reference

​Arguments and options

​Return value

​devboxes.stop()

​Example

​API reference

​Arguments and options

​Return value

​Example

​API reference

​Arguments and options

​Return value

​devboxes.delete()

​Example

​API reference

​Arguments and options

​Return value

​Example

​API reference

​Arguments and options

​Return value

​devbox.refresh()

​Example

​API reference

​Arguments and options

​Return value

​devbox.update()

​Example

​API reference

​Arguments and options

​Return value

​Devbox information

​Shared operation options

​Related documentation

Run commands

Work with files

Use blueprints

`devboxes.create()`

Example

API reference

Arguments and options

Return value

More examples

Create a macOS Devbox

Create a stopped Devbox from a blueprint

`devboxes.get()`

Example

API reference

Arguments and options

Return value

`devboxes.list()`

Example

API reference

Arguments and options

Return value

`devboxes.iterate()`

Example

API reference

Arguments and options

Return value

`devboxes.start()`

Example

API reference

Arguments and options

Return value

Example

API reference

Arguments and options

Return value

`devboxes.stop()`

Example

API reference

Arguments and options

Return value

Example

API reference

Arguments and options

Return value

`devboxes.delete()`

Example

API reference

Arguments and options

Return value

Example

API reference

Arguments and options

Return value

`devbox.refresh()`

Example

API reference

Arguments and options

Return value

`devbox.update()`

Example

API reference

Arguments and options

Return value

Devbox information

Shared operation options

Related documentation