blueprint.md

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

devbox create --blueprint my-blueprint

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

TS SDK

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

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:

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 for every field.

Dashboard

Navigate to the Devbox Blueprints page, and press the New Blueprint button.

Guide: Create a Devbox Blueprint

Configure the following:

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

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

Dashboard

The Devbox 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:

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 page, change its settings, and press Update Blueprint.

Delete a Blueprint

TS SDK

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

Dashboard

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

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

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 for instructions on how to configure it in your workspace.

Environment variables

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

TS SDK

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

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 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() 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 in the dashboard to configure:

Network

Integrations

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