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

# Use blueprints

> Create and manage reusable Devbox configurations with the TypeScript SDK.

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

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

```typescript theme={null}
create(name: string, definition: BlueprintDefinition, options?: OperationOptions): Promise<Blueprint>
```

#### Arguments and options

<ResponseField name="name" type="string" required>
  The blueprint name.
</ResponseField>

<ResponseField name="definition" type="BlueprintDefinition" required>
  The complete configuration. See [Blueprint definitions](#blueprint-definitions).
</ResponseField>

<ResponseField name="options" type="OperationOptions">
  <Expandable title="properties" defaultOpen>
    <ResponseField name="signal" type="AbortSignal">Cancels the operation when aborted.</ResponseField>
    <ResponseField name="timeoutMs" type="number">The operation timeout in milliseconds.</ResponseField>
  </Expandable>
</ResponseField>

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`](#blueprint-fields).

***

## `blueprints.get()`

Fetch a blueprint by name.

### Example

```typescript theme={null}
const blueprint = await client.blueprints.get("node-development");
```

### API reference

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

#### Arguments and options

<ResponseField name="name" type="string" required>The blueprint name.</ResponseField>
<ResponseField name="options" type="OperationOptions">Optional cancellation signal and timeout.</ResponseField>

#### Return value

Returns the matching [`Blueprint`](#blueprint-fields).

***

## `blueprints.list()`

List one page of blueprints.

### Example

```typescript {1-3} theme={null}
const page = await client.blueprints.list({
  limit: 25,
  orderBy: "updated",
});
```

### API reference

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

#### Arguments and options

<ResponseField name="options" type="ListBlueprintsOptions">
  <Expandable title="properties" defaultOpen>
    <ResponseField name="cursor" type="string">An opaque cursor returned by the previous page.</ResponseField>
    <ResponseField name="limit" type="number">The maximum entries to return. Must be a non-negative safe integer.</ResponseField>
    <ResponseField name="orderBy" type="&#x22;created&#x22; | &#x22;updated&#x22;">The timestamp used to order results.</ResponseField>
    <ResponseField name="signal" type="AbortSignal">Cancels the operation when aborted.</ResponseField>
    <ResponseField name="timeoutMs" type="number">The operation timeout in milliseconds.</ResponseField>
  </Expandable>
</ResponseField>

#### Return value

Returns a [`Page<Blueprint>`](#page-fields).

***

## `blueprints.iterate()`

Iterate through all blueprints, fetching additional pages automatically.

### Example

```typescript {1-2} theme={null}
for await (const blueprint of client.blueprints.iterate({ orderBy: "created" })) {
  console.log(blueprint.name);
}
```

### API reference

```typescript theme={null}
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`](#blueprint-fields) objects.

***

## `blueprints.update()`

Replace the complete definition of an existing blueprint.

### Example

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

```typescript theme={null}
update(name: string, definition: BlueprintDefinition, options?: OperationOptions): Promise<Blueprint>
```

#### Arguments and options

<ResponseField name="name" type="string" required>The blueprint name.</ResponseField>
<ResponseField name="definition" type="BlueprintDefinition" required>The complete replacement definition.</ResponseField>
<ResponseField name="options" type="OperationOptions">Optional cancellation signal and timeout.</ResponseField>

The same defaults and validation as `create()` apply.

<Warning>
  `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.
</Warning>

#### Return value

Returns the updated [`Blueprint`](#blueprint-fields).

***

## `blueprints.delete()`

Delete a blueprint by name.

### Example

```typescript theme={null}
await client.blueprints.delete("node-development");
```

### API reference

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

#### Arguments and options

<ResponseField name="name" type="string" required>The blueprint name.</ResponseField>
<ResponseField name="options" type="OperationOptions">Optional cancellation signal and timeout.</ResponseField>

#### Return value

The promise resolves after the blueprint has been deleted.

## Blueprint definitions

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

<ResponseField name="image" type="string" required>An image name or a full image reference. Strings containing `/`, `@`, or `:` are treated as full references.</ResponseField>
<ResponseField name="size" type="MachineSize">One of `"s"`, `"m"`, `"l"`, or `"xl"`.</ResponseField>
<ResponseField name="site" type="string">The site where Devboxes are created. Defaults to `"iad"`.</ResponseField>
<ResponseField name="description" type="string">A description shown with the blueprint.</ResponseField>
<ResponseField name="access" type="&#x22;private&#x22; | &#x22;workspace&#x22;">Who can use the blueprint. Defaults to `"private"`.</ResponseField>
<ResponseField name="environment" type="Record<string, string>">Environment variables added to Devboxes.</ResponseField>
<ResponseField name="volumeSizeGB" type="number">Persistent volume size in GB. Must be a non-negative safe integer.</ResponseField>
<ResponseField name="ephemeral" type="boolean | { stoppedRetentionMs?: number }">Enables ephemeral behavior. The object form sets retention after stopping.</ResponseField>
<ResponseField name="features" type="string[]">Devbox feature names to enable.</ResponseField>

<ResponseField name="networkPolicy" type="NetworkPolicy">
  Egress policy for the Devbox.

  <Expandable title="properties" defaultOpen>
    <ResponseField name="allowedDomains" type="string[]" required>Domains the Devbox may access.</ResponseField>
    <ResponseField name="advisory" type="boolean">Reports violations without enforcement. Defaults to `false`.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="busyTimeoutMs" type="number">Minimum time the Devbox remains busy.</ResponseField>

## Blueprint fields

<ResponseField name="id" type="string" required>The immutable blueprint ID.</ResponseField>
<ResponseField name="name" type="string" required>The blueprint name.</ResponseField>
<ResponseField name="version" type="bigint" required>The blueprint version.</ResponseField>
<ResponseField name="createdAt" type="Date">When the blueprint was created.</ResponseField>
<ResponseField name="updatedAt" type="Date">When the blueprint was last updated.</ResponseField>
<ResponseField name="definition" type="BlueprintDefinition" required>The stored definition.</ResponseField>

## Page fields

<ResponseField name="items" type="Blueprint[]" required>The blueprints in this page.</ResponseField>
<ResponseField name="nextCursor" type="string">An opaque cursor for the next page. Its absence means there are no more results.</ResponseField>

## Related documentation

See [Create and manage Devboxes](/docs/reference/typescript-sdk/devboxes) to create a Devbox from a blueprint and [Manage images](/docs/reference/typescript-sdk/images) to register images used by blueprints.