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.

​

Create a Blueprint

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.

​

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.

​

Repository

Devboxes can be configured to automatically clone a GitHub repository when they are created. 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.

​

Idle timeout

Devboxes will go to sleep after a period of inactivity, which is configured with Idle Timeout. 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

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.