# Devbox Blueprints

A blueprint defines the core configuration for a Devbox environment. It captures the operating system, base image, machine size, access mode, and optional settings like repositories, environment variables, and network policy, so you can create consistent Devboxes from a single reusable definition.

Your workspace's blueprints live on the [Blueprints](https://cloud.namespace.so/workspace/devboxes/blueprints) page in the dashboard.

## Create from Blueprint

Create a Devbox that inherits everything the blueprint defines.

**CLI**

```bash theme={null}
devbox create --blueprint my-blueprint
```

`--blueprint` uses the latest version of the named blueprint, and cannot be combined with `--from` or `--platform`.

**TS SDK**

```typescript theme={null}
const devbox = await client.devboxes.create({
  name: "my-devbox",
  blueprint: "my-blueprint",
});
```

Creating from a blueprint cannot set `image`, `size`, `repository`, or the other direct-creation fields. Omit `site` and `access` to preserve the blueprint's own values.

**Dashboard**

On the [Blueprints page](https://cloud.namespace.so/workspace/devboxes/blueprints), click the `...` icon next to a blueprint, select **Create Devbox**, give it a name, and press **Create Devbox**.

## Managing Blueprints

### Create a Blueprint

**TS SDK**

`blueprints.create()` takes a name and a complete definition:

```typescript theme={null}
const blueprint = await client.blueprints.create("my-blueprint", {
  image: "builtin:default",
  size: "m",
});
```

`image` is required, and every other field is optional.

A fuller definition can set environment variables, who may use the blueprint, whether its Devboxes are ephemeral, and which domains they may reach:

```typescript theme={null}
await client.blueprints.create("my-blueprint", {
  image: "builtin:default",
  size: "m",
  access: "workspace",
  environment: { NODE_ENV: "development" },
  ephemeral: true,
  networkPolicy: {
    allowedDomains: ["*.github.com", "api.openai.com"],
  },
});
```

See [Use blueprints](/content/docs/reference/typescript-sdk/devbox/blueprints.md#blueprint-definitions/index.html) for every field.

**Dashboard**

Navigate to the [Devbox Blueprints](https://cloud.namespace.so/workspace/devboxes/blueprints) page, and press the **New Blueprint** button.

[Guide: Create a Devbox Blueprint](https://app.guideflow.com/embed/xrge06gc1p)

Configure the following:

* `Name` - the name of your blueprint
* `Operating system` - pick between Linux or macOS
* `Base image` - for macOS, this lets you choose the version of macOS and Xcode
* `Machine size` - to select vCPU and RAM for the Devbox

See [Additional configuration](#additional-configuration) for more configuration options.

When you are done, press **Create Blueprint**.

### List Blueprints

**TS SDK**

`blueprints.list()` returns one page at a time:

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

page.items.forEach((blueprint) => console.log(blueprint.name));
```

Pass the returned `nextCursor` as the next call's `cursor`, or use `blueprints.iterate()` to walk every page automatically.

Fetch a single blueprint by name to read its full definition:

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

console.log(blueprint.version, blueprint.definition.size);
```

**Dashboard**

The [Devbox Blueprints](https://cloud.namespace.so/workspace/devboxes/blueprints) page lists every blueprint in your workspace, with its operating system, any integrations it enables, and when it was last updated.

### Update a Blueprint

**TS SDK**

`blueprints.update()` replaces the entire definition, so spread the current one and override only what changes. Anything you omit is cleared:

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

await client.blueprints.update("my-blueprint", {
  ...current.definition,
  size: "l",
});
```

Each update produces a new blueprint version. Devboxes created afterwards use the latest version, and existing Devboxes are unaffected.

**Dashboard**

Open a blueprint from the [Blueprints](https://cloud.namespace.so/workspace/devboxes/blueprints) page, change its settings, and press **Update Blueprint**.

### Delete a Blueprint

**TS SDK**

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

**Dashboard**

On the [Blueprints](https://cloud.namespace.so/workspace/devboxes/blueprints) page, click the `...` icon next to a blueprint and select **Delete**.

Deleting a blueprint does not affect Devboxes already created from it.

## Additional configuration

When creating or updating blueprints, you can configure additional settings.

### Ephemeral

Devboxes can be created as ephemeral, tying their instance and storage to a single run. When an ephemeral Devbox stops, both its instance and storage are automatically deleted. On restart, it starts fresh.

Ephemeral Devboxes suit short-lived tasks or experimentation where you don't need to retain data across restarts.

**TS SDK**

```typescript theme={null}
await client.blueprints.create("my-blueprint", {
  image: "builtin:default",
  ephemeral: true,
});
```

Pass an object instead of `true` to control how long the stopped Devbox is retained.

**Dashboard**

Turn on **Ephemeral** on the new or edit blueprint page.

### Repository

Devboxes can be configured to automatically clone a GitHub repository when they are created.

**Dashboard**

To list your GitHub repositories, you need to enable the GitHub integration. From the new/edit blueprint page, expand the **Repository** dropdown, and select **Connect an organization**, and follow the instructions.

A blueprint definition in the TypeScript SDK has no repository field. Set `repository` when you [create the Devbox](/content/docs/devbox/lifecycle.md#create-a-devbox/index.html) instead.

### Idle timeout

Devboxes will go to sleep after a period of inactivity, which is configured with **Auto-stop timeout on idle**.

**TS SDK**

`busyTimeoutMs` is the idle timeout, expressed in milliseconds:

```typescript theme={null}
await client.blueprints.create("my-blueprint", {
  image: "builtin:default",
  busyTimeoutMs: 60 * 60_000,
});
```

**Dashboard**

Pick one of the presets, or **Custom** to enter your own duration.

A sleeping Devbox does not consume compute, so you are not paying for time the Devbox spends idle. When it wakes, its filesystem is intact, so work continues from where it left off.

The exception is an ephemeral Devbox, which deletes its storage when it stops. If a Devbox needs to survive an idle period, avoid pairing a short idle timeout with the ephemeral setting.

### Tailscale

Devboxes support Tailscale out of the box.

With Tailscale, a Devbox can reach private resources on your network that are not exposed to the internet, such as internal package registries, databases, staging services, or a self-hosted Git server. This lets you build and test against your internal dependencies without opening those services publicly.

Combined with egress filtering, you can keep the Devbox's outbound access limited to your tailnet and a short list of allowed domains, so it only reaches what a task actually needs.

See the [Tailscale Integrations](/content/docs/integrations/tailscale.md#configure-tailscale/index.html) for instructions on how to configure it in your workspace.

### Environment variables

You can populate your Devbox's environment variables by providing:

* Environment Variables - values are provided in plain text
* Secrets - loads secret values from the [Namespace vault](https://cloud.namespace.so/workspace/vars)

**TS SDK**

```typescript theme={null}
await client.blueprints.create("my-blueprint", {
  image: "builtin:default",
  environment: { NODE_ENV: "development" },
});
```

**Dashboard**

Under **Environment**, press **+ Add variable** for a plain value, or **+ Add secret** to reference a vault secret.

See [Managing Secrets](/content/docs/architecture/storage/secrets.md#managing-secrets/index.html) on how to list, add, update, and remove your secrets.

### Egress filtering

[Egress filtering](/content/docs/security/egress-policy.md) restricts the outbound network access of a workload to a list of allowed domains. This is useful when a Devbox should only reach the source hosts, package registries, model APIs, or other services that a task actually needs. Everything else is guaranteed to be blocked.

**TS SDK**

```typescript theme={null}
await client.blueprints.create("my-blueprint", {
  image: "builtin:default",
  networkPolicy: {
    allowedDomains: ["*.github.com", "api.openai.com"],
  },
});
```

Set `advisory: true` to report violations without enforcing them.

**Dashboard**

Under **Network**, set **Egress policy** and list the **Allowed domains**. Prefix a domain with `*.` to include its subdomains. Domains required to reach Namespace infrastructure are always included.

## Initialization

A blueprint can run commands as its Devboxes come up: an init script once when a Devbox is first created, terminal sessions every time one starts, and services that the Devbox keeps running and restarts if they fail. All three are configured on the new or edit blueprint page.

### Init script

The init script runs once, when a Devbox created from the blueprint is first initialized. Use it for setup that only needs to happen on a fresh Devbox, such as installing dependencies.

**Dashboard**

Expand **Update script**, then enter the commands to run:

### Sessions

A session starts a tmux session every time a Devbox created from the blueprint starts, and runs the command you give it. Use one for a process you want to come back to, such as a dev server.

**Dashboard**

Press **+ Add session**, give the session a name and a command, then press **Add**:

### Services

A [service](/content/docs/devbox/services.md) is a command that the Devbox supervises: it starts the command on every boot, restarts it if it fails, and retains its logs. Use one for a process that should keep running without a terminal, such as a dev server or a file watcher.

**TS SDK**

A blueprint definition in the TypeScript SDK has no services field. Create services on a running Devbox with [`devbox.services.create()`](/content/docs/devbox/services#create/index.html) instead.

**Dashboard**

Under **Services**, press **+ Add service**, give the service a name and a command:

Blueprint services start on boot and restart on failure. A Devbox receives the blueprint's services when it first starts, and from then on they are ordinary services that you can stop, start, or delete. Editing the blueprint later does not change the services of existing Devboxes.

## Workspace Defaults

Workspace admins can set default values applied to all newly created Devboxes. Navigate to the [Defaults page](https://cloud.namespace.so/workspace/devboxes/defaults) in the dashboard to configure:

* **Image**: default base image, which also determines the operating system (Linux or macOS)
* **Instance size**: default CPU and memory allocation
* **Volume size**: default persistent volume size for new Devboxes
* **Git repository**: default repository to clone
* **Access mode**: private (just you) or workspace-wide (shared with all members)
* **Auto-stop timeout on idle**: how long Devboxes stay running when idle

**Network**

* **Egress policy**: default outbound network access restrictions

**Integrations**

* **Bazel**: enable [Bazel integration](/content/docs/integrations/bazel.md) to share Bazel cache across Devboxes
* **Tailscale**: default [Tailscale integration spec](/content/docs/integrations/tailscale.md) to connect Devboxes to your tailnet

When a workspace policy is active, policy-enforced values take precedence and are shown as locked in the UI.