> ## Documentation Index > Fetch the complete documentation index at: https://namespace.so/docs/llms.txt > Use this file to discover all available pages before exploring further. # Devbox spec file > Field reference for the JSON, YAML, or TOML specification consumed by devbox create --from. A spec file declares a Devbox configuration in one place. Pass it to [`devbox create`](/docs/reference/devbox-cli/create) or [`devbox acquire`](/docs/reference/devbox-cli/acquire) with `--from`: ```bash theme={null} 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`: ```bash theme={null} 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](#environment-variables)). | | `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](#integrations)). | | `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](#network-policy)). | | `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](#repository)). | | `sessions` | List of sessions to create automatically ([see below](#sessions)). | | `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. ```yaml theme={null} 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](/docs/reference/cli/vault-list)). | ```yaml theme={null} env: - name: APP_ENV value: production - name: GITHUB_TOKEN from_secret_id: sec_8fumgjd5jk ``` See [Managing Secrets](/docs/architecture/storage/secrets#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: ```yaml theme={null} 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. | ```yaml theme={null} 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](/docs/devbox/creating#github-cli-authentication). | | `tailscale.spec` | Name of a workspace-level [Tailscale integration spec](/docs/integrations/tailscale). Use `nsc integrations tailscale list` to see available specs. | ## Example ```yaml devbox.yaml theme={null} 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 ``` ## Related topics Every flag accepted alongside `--from`. Machine sizes, images, repositories, and workspace defaults. What sessions do once the Devbox starts.