Configuration files

The Box CLI reads and writes a small set of files in each box project. This page documents every one of them, plus the environment variables that influence the CLI’s behavior.

File	Committable?	Purpose
`box.json`	✅ yes (no secrets)	Box manifest: name, control plane, license metadata.
`box.yml`	✅ yes	Deploy manifest: public URLs and domains.
`brand.json`	✅ yes	Console branding/theme declaration.
`.box/credentials.json`	❌ never	Secrets: license key and npm token (mode `0600`).
`.npmrc`	❌ never	Registry auth written by `box auth`.
`dns.txt` / `nameserver.txt`	optional	DNS instructions written by `box deploy`.

`box.json`

The box manifest — committable and free of secrets. Written by box create and extended by box auth.

box.json

{
  "name": "acme-bank",
  "org": "acme-bank",
  "controlPlaneUrl": "https://control.example.com",
  "webControlUrl": "https://beta.withpotter.site",
  "storefrontDomain": "shop.acme-bank.example",
  "license": {
    "customerId": "cus_xxxxxxxx",
    "tier": "growth",
    "registryUrl": "https://registry.example.com",
    "packages": ["@withpotter/engine-core", "@withpotter/pages-catalog"],
    "activatedAt": "2026-06-22T00:00:00.000Z"
  }
}

Field	Type	Description
`name`	string	The box name.
`org`	string?	Organization name.
`controlPlaneUrl`	string?	Control plane API URL for this box.
`webControlUrl`	string?	Web control URL (drives `NEXT_PUBLIC_WEB_URL`).
`storefrontDomain`	string?	Per-bank storefront base host.
`license`	object?	License metadata written by `box auth` (no secrets).
`license.customerId`	string	The box’s customer ID.
`license.tier`	string	The entitlement tier.
`license.registryUrl`	string	The entitled package registry URL.
`license.packages`	string[]	The entitled package names.
`license.activatedAt`	string	ISO timestamp of activation.

The license block is metadata only — it contains no secrets and is safe to commit. Secrets live in .box/credentials.json.

`box.yml`

The deploy manifest consumed by box deploy. It declares the box’s public URLs and the domains to register with the control plane resolver. It contains no secrets.

box.yml

backendUrl: https://api.acme-bank.example
frontendUrl: https://shop.acme-bank.example
dashboardUrl: https://admin.acme-bank.example
domains:
  - host: acme-bank.example
    primary: true
  - host: '*.acme-bank.example'
    wildcard: true

Field	Type	Description
`backendUrl`	string?	Public backend (engine) URL. Required by `box deploy` if not passed as a flag.
`frontendUrl`	string?	Public frontend URL.
`dashboardUrl`	string?	Public console/dashboard origin.
`domains`	`DeployDomain[]`	Required. At least one domain.

After a successful box deploy, any URL you pass explicitly is persisted back here: --backend-url → backendUrl, and --frontend-url → frontendUrl plus a matching entry in domains (and storefrontDomain in box.json). Comments and formatting in box.yml are preserved. Subsequent deploys can then omit those flags.

`DeployDomain`

Field	Type	Description
`host`	string	Required. The domain host. Normalized to lowercase; must be unique within `domains`.
`primary`	boolean?	Marks the primary domain. At most one domain may be primary.
`wildcard`	boolean?	Marks the domain as a wildcard (e.g. `*.acme-bank.example`).

⚠️

Hosts are normalized to lowercase and must be unique. The manifest may declare at most one primary domain.

`brand.json`

The committable, secret-free branding declaration for the box’s console. box brand reads it and generates the console theme — a CSS-variable override file, the copied logo, and NEXT_PUBLIC_BOX_* env vars. box create ships a default one.

brand.json

{
  "name": "Box Dashboard",
  "logo": "assets/logo.svg",
  "theme": {
    "colors": {
      "brand": "#2563eb",
      "accent": "#111827",
      "background": "#ffffff",
      "surface": "#f5f5f5",
      "text": "#111827",
      "link": "#2563eb",
      "success": "#16a34a"
    },
    "button": { "radius": "0.5rem" },
    "css": {},
    "dark": {
      "colors": { "brand": "#3b82f6", "accent": "#f3f4f6" }
    }
  }
}

Field	Type	Description
`name`	string?	Console display name → `NEXT_PUBLIC_BOX_NAME`.
`logo`	string?	Logo path relative to the box root → `NEXT_PUBLIC_BOX_LOGO`.
`theme.colors`	object?	Friendly color aliases mapped to design-system CSS variables.
`theme.button.radius`	string?	Button/card corner radius → `--radius`.
`theme.css`	object?	Raw `--token: value` overrides (keys must start with `--`).
`theme.dark`	object?	Dark-mode overrides (same shape), emitted under `.dark`.

See the box brand reference for the full color alias table and validation rules.

`.box/credentials.json`

The box’s secrets — written by box auth with file mode 0600 and git-ignored. Never commit this file.

.box/credentials.json

{
  "licenseKey": "pk_live_xxxxxxxx",
  "npmToken": "npm_xxxxxxxx"
}

Field	Type	Description
`licenseKey`	string?	The box’s license key.
`npmToken`	string?	The registry auth token.

`.npmrc`

Written by box auth to authenticate package installs against the entitled registry. Git-ignored. Never commit it.

`dns.txt` / `nameserver.txt`

box deploy writes dns.txt with the DNS records you must create for your registered domains. A legacy nameserver.txt is also written for backward compatibility. Both are git-ignored by the generated .gitignore.

Environment variables

Variable	Default	Description
`BOX_CONTROL_PLANE`	(none)	Control plane API URL. Never baked into the CLI — supply it via this env var, the `--control-plane` flag, or `box.json`.
`BOX_CONTROL_WEB_URL`	`https://beta.withpotter.site`	Web control URL; drives `NEXT_PUBLIC_WEB_URL`.
`BOX_STOREFRONT_DOMAIN`	(none)	Per-bank storefront base host; drives `NEXT_PUBLIC_STOREFRONT_DOMAIN`.

Control plane URL resolution

When a command needs the control plane URL, it is resolved in this order:

An explicit --control-plane flag (where the command accepts one).
The BOX_CONTROL_PLANE environment variable.
The controlPlaneUrl field in box.json.

`.gitignore` generated by `box create`

box create writes a .gitignore that excludes:

.gitignore

node_modules/
dist/
.box/
.npmrc
.env
.env.local
nameserver.txt
dns.txt