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 page in the dashboard.

Create from Blueprint

Create a Devbox that inherits everything the blueprint defines.

CLI
TS SDK
Dashboard

devbox create --blueprint my-blueprint

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

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.

On the Blueprints page, click the ... icon next to a blueprint, select Create Devbox, give it a name, and press Create Devbox.

Managing Blueprints

The Devbox CLI cannot create or manage blueprints. Use the dashboard or the TypeScript SDK, then create Devboxes from them with devbox create --blueprint.

Create a Blueprint

TS SDK
Dashboard

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

const blueprint = await client.blueprints.create("my-blueprint", {
  image: "builtin:agents",
  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:

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

See Use blueprints for every field.

Navigate to the Devbox Blueprints page, and press the New Blueprint button.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 for more configuration options.When you are done, press Create Blueprint.

List Blueprints

TS SDK
Dashboard

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

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:

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

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

Update a Blueprint

TS SDK
Dashboard

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

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.

Delete a Blueprint

TS SDK
Dashboard

await client.blueprints.delete("my-blueprint");

On the 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
Dashboard

await client.blueprints.create("my-blueprint", {
  image: "builtin:agents",
  ephemeral: true,
});

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

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

Idle timeout

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

TS SDK
Dashboard

busyTimeoutMs is the idle timeout, expressed in milliseconds:

await client.blueprints.create("my-blueprint", {
  image: "builtin:agents",
  busyTimeoutMs: 60 * 60_000,
});

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

TS SDK
Dashboard

await client.blueprints.create("my-blueprint", {
  image: "builtin:agents",
  environment: { NODE_ENV: "development" },
});

environment takes plain values only. To reference a vault secret, define the blueprint in the dashboard, or use env with from_secret_id in a spec file.

See Managing Secrets on how to list, add, update, and remove your secrets.

Egress filtering

Egress filtering 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
Dashboard

await client.blueprints.create("my-blueprint", {
  image: "builtin:agents",
  networkPolicy: {
    allowedDomains: ["*.github.com", "api.openai.com"],
  },
});

Set advisory: true to report violations without enforcing them.

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: once when a Devbox is first created, and again in a terminal session every time one starts. Both 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:

Add as many sessions as you need. Each one is independent, with its own name and command, so a blueprint can bring up a dev server, a test watcher, and a spare shell side by side.

See Sessions for how to attach to a session once the Devbox is running. A blueprint definition in the TypeScript SDK has no init script or sessions field.

Products

Platform

Administration

Create from Blueprint

Managing Blueprints

Create a Blueprint

List Blueprints

Update a Blueprint

Delete a Blueprint

Additional configuration

Ephemeral

Repository

Idle timeout

Tailscale

Environment variables

Egress filtering

Initialization

Init script

Sessions

​Create from Blueprint

​Managing Blueprints

​Create a Blueprint

​List Blueprints

​Update a Blueprint

​Delete a Blueprint

​Additional configuration

​Ephemeral

​Repository

​Idle timeout

​Tailscale

​Environment variables

​Egress filtering

​Initialization

​Init script

​Sessions

Create from Blueprint

Managing Blueprints

Create a Blueprint

List Blueprints

Update a Blueprint

Delete a Blueprint

Additional configuration

Ephemeral

Repository

Idle timeout

Tailscale

Environment variables

Egress filtering

Initialization

Init script

Sessions