Devbox spec file

A spec file declares a Devbox configuration in one place. Pass it to devbox create or devbox acquire with --from:

devbox create --from devbox.yaml

The file extension selects the parser. Supported extensions are .json, .yaml, .yml, and .toml.

Reading from stdin

Pass - as the path to read the spec from stdin. Stdin is parsed as YAML by default. Use --from_format to override it with json, yaml, or toml:

cat devbox.yaml | devbox create --from -

Fields

Field	Description
`access_mode`	Access mode: `private` (just you) or `shared` (workspace-wide).
`auto_stop_idle_timeout`	Idle timeout duration (e.g. `30m`, `1h`).
`env`	Environment variables to set on the Devbox container (see below).
`ephemeral`	When `true`, the Devbox is ephemeral. No data is persisted across its lifecycle.
`image`	Image name or reference to use as the base environment (required).
`integrations`	Integration configuration (see below).
`name`	Exact Devbox name (required, mutually exclusive with `name_prefix`).
`name_prefix`	Prefix for an auto-generated name. A random suffix is appended (required, mutually exclusive with `name`).
`network_policy`	Outbound network policy (see below).
`privileged`	Run in privileged mode. Omit to use the image default.
`repository`	Git repository to clone into the Devbox. Either a URL string, or a block of options (see below).
`sessions`	List of sessions to create automatically (see below).
`site`	Target site. If omitted, the closest site is selected automatically.
`size`	Machine size: `S`, `M`, `L`, or `XL` (required, case-insensitive).
`volume_size_gb`	Persistent volume size in GiB.

Sessions

Each entry in sessions has:

Field	Description
`name`	Session name (required).
`command`	Command to run in the session (required).

Configure one or more session-command pairs to have the Devbox automatically create sessions and run the specified commands on startup.

sessions:
  - name: server
    command: npm run dev
  - name: tests
    command: npm test -- --watch

Environment Variables

Each entry in env has a name and exactly one of value or from_secret_id:

Field	Description
`name`	Variable name (required).
`value`	Literal value. Supports `$NAME` / `${NAME}` expansion from your local environment.
`from_secret_id`	Workspace vault secret ID (see nsc vault list).

env:
  - name: APP_ENV
    value: production
  - name: GITHUB_TOKEN
    from_secret_id: sec_8fumgjd5jk

See Managing Secrets to learn how to create and manage vault secrets.

Repository

The repository block supports:

Field	Description
`disabled`	When `true`, skips the checkout entirely, including any workspace default repository.
`url`	Git repository URL to clone. Equivalent to using the string shorthand.
`ref`	Branch, tag, or commit SHA to check out. Defaults to the repository’s default branch.

Omit repository to fall back to the workspace default. To explicitly create a Devbox with no repository checked out:

repository:
  disabled: true

Network Policy

The network_policy block restricts outbound network access:

Field	Description
`egress_domains`	List of domains the Devbox is allowed to reach. Prefix a domain with `*.` to include all of its subdomains. Namespace infrastructure domains are always allowed.

network_policy:
  egress_domains:
    - "*.github.com"
    - api.openai.com

Integrations

The integrations object supports:

Field	Description
`github.share_auth`	When `true`, authenticates the `gh` CLI and git on the Devbox with your local GitHub token. Equivalent to passing `--setup_github`. See GitHub CLI authentication.
`tailscale.spec`	Name of a workspace-level Tailscale integration spec. Use `nsc integrations tailscale list` to see available specs.

Example

devbox.yaml

name: my-devbox
image: builtin:agents
size: M
access_mode: private
volume_size_gb: 100
auto_stop_idle_timeout: 30m
privileged: false
repository:
  url: github.com/my-org/my-repo
  ref: main
sessions:
  - name: server
    command: npm run dev
  - name: tests
    command: npm test -- --watch
integrations:
  github:
    share_auth: true
  tailscale:
    spec: corp
env:
  - name: APP_ENV
    value: production
  - name: GITHUB_TOKEN
    from_secret_id: my-github-token-id
network_policy:
  egress_domains:
    - "*.github.com"
    - api.openai.com

devbox create

Every flag accepted alongside --from.

Creating Devboxes

Machine sizes, images, repositories, and workspace defaults.

Sessions

What sessions do once the Devbox starts.

Devbox SDK

Automation

CLI

Reading from stdin

Fields

Sessions

Environment Variables

Repository

Network Policy

Integrations

Example

devbox create

Creating Devboxes

Sessions

​Reading from stdin

​Fields

​Sessions

​Environment Variables

​Repository

​Network Policy

​Integrations

​Example

​Related topics

devbox create

Creating Devboxes

Sessions

Reading from stdin

Fields

Sessions

Environment Variables

Repository

Network Policy

Integrations

Example

Related topics