> ## Documentation Index
> Fetch the complete documentation index at: https://namespace.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create and manage Devboxes

> Create, inspect, update, start, stop, and delete Devboxes with the TypeScript SDK.

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.

<Info>
  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.
</Info>

## `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:

```typescript {5-8} theme={null}
import { createDevboxClient } from "@namespacelabs/sdk/devbox";

const client = createDevboxClient();

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

### API reference

```typescript theme={null}
create(input: CreateDevboxInput, options?: OperationOptions): Promise<Devbox>
```

#### Arguments and options

<ResponseField name="input" type="CreateDevboxInput" required>
  The Devbox name and configuration.

  <Expandable title="common properties" defaultOpen>
    <ResponseField name="name" type="string" required>
      The Devbox name.
    </ResponseField>

    <ResponseField name="site" type="string" default="iad">
      The site where the Devbox is created. For blueprint creation, omitting this property preserves the blueprint's site.
    </ResponseField>

    <ResponseField name="purpose" type="string">
      A description of the Devbox's intended use.
    </ResponseField>

    <ResponseField name="access" type="&#x22;private&#x22; | &#x22;workspace&#x22;">
      The access mode. When omitted, the service chooses the tenant default. For blueprint creation, omitting this property preserves the blueprint's access mode.
    </ResponseField>

    <ResponseField name="start" type="boolean" default="true">
      Whether to start the Devbox and wait for it to become ready during creation.
    </ResponseField>
  </Expandable>

  <Expandable title="direct creation properties" defaultOpen>
    <ResponseField name="os" type="&#x22;linux&#x22; | &#x22;macos&#x22;" default="linux">
      The operating system. macOS Devboxes use a Namespace-managed Apple Silicon base image and cannot set `image` or `imageName`.
    </ResponseField>

    <ResponseField name="image" type="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`.
    </ResponseField>

    <ResponseField name="imageName" type="string">
      A built-in or registered image name, such as `"builtin:agents"`. Cannot be combined with `image`, `os: "macos"`, or `blueprint`.
    </ResponseField>

    <ResponseField name="size" type="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"`.
    </ResponseField>

    <ResponseField name="volumeSizeGB" type="number">
      The volume size in GB. The value must be a non-negative safe integer.
    </ResponseField>

    <ResponseField name="repository" type="string">
      A repository to check out in the Devbox.
    </ResponseField>

    <ResponseField name="environment" type="Record<string, string>">
      Environment variables added to the Devbox.
    </ResponseField>

    <ResponseField name="ephemeral" type="boolean | { stoppedRetentionMs?: number }">
      Enables automatic expiration. The object form configures how long the stopped Devbox is retained.
    </ResponseField>

    <ResponseField name="privileged" type="boolean">
      Whether the Devbox runs in privileged mode.
    </ResponseField>

    <ResponseField name="features" type="string[]">
      Feature names to enable.
    </ResponseField>

    <ResponseField name="networkPolicy" type="NetworkPolicy">
      Restricts outbound network access.

      <Expandable title="properties" defaultOpen>
        <ResponseField name="allowedDomains" type="string[]" required>
          Domains allowed by the policy.
        </ResponseField>

        <ResponseField name="advisory" type="boolean" default="false">
          Whether violations are advisory instead of enforced.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>

  <Expandable title="blueprint creation properties" defaultOpen>
    <ResponseField name="blueprint" type="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.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="options" type="OperationOptions">
  Cancellation and timeout options. See [Shared operation options](#shared-operation-options).
</ResponseField>

#### 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

```typescript {1-4} theme={null}
const mac = await client.devboxes.create({
  name: "sdk-mac",
  os: "macos",
  size: "m",
});
```

#### Create a stopped Devbox from a blueprint

```typescript {1-4} theme={null}
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

```typescript theme={null}
const devbox = await client.devboxes.get("sdk-example");
```

### API reference

```typescript theme={null}
get(ref: string, options?: OperationOptions): Promise<Devbox>
```

#### Arguments and options

<ResponseField name="ref" type="string" required>
  The Devbox ID or name.
</ResponseField>

<ResponseField name="options" type="OperationOptions">
  Cancellation and timeout options. See [Shared operation options](#shared-operation-options).
</ResponseField>

#### 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

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

### API reference

```typescript theme={null}
list(options?: ListDevboxesOptions): Promise<Page<Devbox>>
```

#### Arguments and options

<ResponseField name="options" type="ListDevboxesOptions">
  Pagination, filtering, cancellation, and timeout options.

  <Expandable title="properties" defaultOpen>
    <ResponseField name="cursor" type="string">
      The opaque `nextCursor` from the previous page.
    </ResponseField>

    <ResponseField name="limit" type="number">
      The maximum number of entries requested. The value must be a non-negative safe integer.
    </ResponseField>

    <ResponseField name="orderBy" type="&#x22;created&#x22; | &#x22;last-used&#x22;">
      The field used to order results.
    </ResponseField>

    <ResponseField name="ephemeral" type="boolean">
      When set, return only ephemeral or only non-ephemeral Devboxes.
    </ResponseField>

    <ResponseField name="signal" type="AbortSignal">
      Cancels the request when aborted.
    </ResponseField>

    <ResponseField name="timeoutMs" type="number">
      The request timeout in milliseconds.
    </ResponseField>
  </Expandable>
</ResponseField>

#### 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

```typescript {1-2} theme={null}
for await (const devbox of client.devboxes.iterate({ ephemeral: false })) {
  console.log(devbox.name);
}
```

### API reference

```typescript theme={null}
iterate(options?: Omit<ListDevboxesOptions, "cursor">): AsyncIterableIterator<Devbox>
```

#### Arguments and options

<ResponseField name="options" type="Omit<ListDevboxesOptions, &#x22;cursor&#x22;>">
  The `limit`, `orderBy`, `ephemeral`, `signal`, and `timeoutMs` options from `list()`. Pagination cursors are managed internally.
</ResponseField>

#### 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.

<Tabs>
  <Tab title="By ID or name">
    ### Example

    ```typescript theme={null}
    const devbox = await client.devboxes.start("sdk-example");
    ```

    ### API reference

    ```typescript theme={null}
    start(ref: string, options?: OperationOptions): Promise<Devbox>
    ```

    #### Arguments and options

    <ResponseField name="ref" type="string" required>
      The Devbox ID or name.
    </ResponseField>

    <ResponseField name="options" type="OperationOptions">
      Cancellation and timeout options. See [Shared operation options](#shared-operation-options).
    </ResponseField>

    #### Return value

    Returns a ready `Devbox` object with refreshed information and `info.state` set to `"running"`.
  </Tab>

  <Tab title="Devbox Object">
    ### Example

    ```typescript {2} theme={null}
    const devbox = await client.devboxes.get("sdk-example");
    await devbox.start();
    ```

    ### API reference

    ```typescript theme={null}
    start(options?: OperationOptions): Promise<this>
    ```

    #### Arguments and options

    <ResponseField name="options" type="OperationOptions">
      Cancellation and timeout options. See [Shared operation options](#shared-operation-options).
    </ResponseField>

    #### Return value

    Updates and returns the same `Devbox` object, with refreshed information and `info.state` set to `"running"`.
  </Tab>
</Tabs>

***

## `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.

<Tabs>
  <Tab title="By ID or name">
    ### Example

    ```typescript theme={null}
    const devbox = await client.devboxes.stop("sdk-example");
    ```

    ### API reference

    ```typescript theme={null}
    stop(ref: string, options?: OperationOptions): Promise<Devbox>
    ```

    #### Arguments and options

    <ResponseField name="ref" type="string" required>
      The Devbox ID or name.
    </ResponseField>

    <ResponseField name="options" type="OperationOptions">
      Cancellation and timeout options. See [Shared operation options](#shared-operation-options).
    </ResponseField>

    #### Return value

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

    <Warning>
      Running a command or using another connection-backed API on this object starts the Devbox again automatically.
    </Warning>
  </Tab>

  <Tab title="Devbox Object">
    ### Example

    ```typescript {2} theme={null}
    const devbox = await client.devboxes.get("sdk-example");
    await devbox.stop();
    ```

    ### API reference

    ```typescript theme={null}
    stop(options?: OperationOptions): Promise<this>
    ```

    #### Arguments and options

    <ResponseField name="options" type="OperationOptions">
      Cancellation and timeout options. See [Shared operation options](#shared-operation-options).
    </ResponseField>

    #### Return value

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

    <Warning>
      Running a command or using another connection-backed API on this object starts the Devbox again automatically.
    </Warning>
  </Tab>
</Tabs>

***

## `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.

<Tabs>
  <Tab title="By ID or name">
    ### Example

    ```typescript theme={null}
    await client.devboxes.delete("sdk-example");
    ```

    ### API reference

    ```typescript theme={null}
    delete(ref: string, options?: OperationOptions): Promise<void>
    ```

    #### Arguments and options

    <ResponseField name="ref" type="string" required>
      The Devbox ID or name.
    </ResponseField>

    <ResponseField name="options" type="OperationOptions">
      Cancellation and timeout options. See [Shared operation options](#shared-operation-options).
    </ResponseField>

    #### Return value

    Returns no value. The promise resolves after the Devbox has been deleted.
  </Tab>

  <Tab title="Devbox Object">
    ### Example

    ```typescript {2} theme={null}
    const devbox = await client.devboxes.get("sdk-example");
    await devbox.delete();
    ```

    ### API reference

    ```typescript theme={null}
    delete(options?: OperationOptions): Promise<void>
    ```

    #### Arguments and options

    <ResponseField name="options" type="OperationOptions">
      Cancellation and timeout options. See [Shared operation options](#shared-operation-options).
    </ResponseField>

    #### Return value

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

    <Warning>
      The object is not marked as deleted. Do not call any of its properties or methods after `delete()` resolves.
    </Warning>
  </Tab>
</Tabs>

***

## `devbox.refresh()`

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

### Example

```typescript {2} theme={null}
const devbox = await client.devboxes.get("sdk-example");
await devbox.refresh();
```

### API reference

```typescript theme={null}
refresh(options?: OperationOptions): Promise<this>
```

#### Arguments and options

<ResponseField name="options" type="OperationOptions">
  Cancellation and timeout options. See [Shared operation options](#shared-operation-options).
</ResponseField>

#### 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

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

### API reference

```typescript theme={null}
update(input: UpdateDevboxInput, options?: OperationOptions): Promise<this>
```

#### Arguments and options

<ResponseField name="input" type="UpdateDevboxInput" required>
  The settings to update.

  <Expandable title="properties" defaultOpen>
    <ResponseField name="size" type="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.
    </ResponseField>

    <ResponseField name="volumeSizeGB" type="number">
      The volume size in GB. The value must be a non-negative safe integer.
    </ResponseField>

    <ResponseField name="busyTimeoutMs" type="number">
      The minimum duration in milliseconds for which the Devbox remains busy.
    </ResponseField>

    <ResponseField name="privileged" type="boolean">
      Whether the Devbox runs in privileged mode.
    </ResponseField>

    <ResponseField name="networkPolicy" type="NetworkPolicy">
      The outbound network policy, with `allowedDomains` and optional `advisory` properties as described under `create()`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="options" type="OperationOptions">
  Cancellation and timeout options. See [Shared operation options](#shared-operation-options).
</ResponseField>

#### 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.

```typescript theme={null}
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`.

<ResponseField name="options" type="OperationOptions">
  Controls cancellation and timeout behavior.

  <Expandable title="properties" defaultOpen>
    <ResponseField name="signal" type="AbortSignal">
      Cancels the operation when the signal is aborted.
    </ResponseField>

    <ResponseField name="timeoutMs" type="number">
      The operation timeout in milliseconds.
    </ResponseField>
  </Expandable>
</ResponseField>

## Related documentation

<Columns cols={3}>
  <Card title="Run commands" icon="terminal" href="/docs/reference/typescript-sdk/commands">
    Execute structured commands and shell scripts.
  </Card>

  <Card title="Work with files" icon="file" href="/docs/reference/typescript-sdk/files">
    Transfer and manipulate Devbox files.
  </Card>

  <Card title="Use blueprints" icon="layers" href="/docs/reference/typescript-sdk/blueprints">
    Define reusable Devbox configurations.
  </Card>
</Columns>