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.

box.json

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

{
  "name": "acme-bank",
  "org": "acme-bank",
  "controlPlaneUrl": "https://control.example.com",
  "webControlUrl": "https://beta.withpotter.site",
  "storefrontDomain": "shop.acme-bank.example",
  "engineUrl": "https://api.acme-bank.example",
  "consoleUrl": "https://app.acme-bank.example",
  "backOfficeUrl": "https://admin.acme-bank.example",
  "hostUrl": "https://acme-bank.example",
  "deployPipe": ["dockerfile", "compose", "github"],
  "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"
  }
}

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.

backendUrl: https://api.acme-bank.example
frontendUrl: https://shop.acme-bank.example
dashboardUrl: https://admin.acme-bank.example
contactEmail: ops@acme-bank.example
payment:
  provider: olivepay
console:
  defaultTheme: light
domains:
  - host: acme-bank.example
    primary: true
  - host: '*.acme-bank.example'
    wildcard: true

DeployDomain

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.

{
  "name": "Box Dashboard",
  "logo": "assets/logo.svg",
  "favicon": "assets/mark.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" }
    }
  }
}

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.

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

.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

The four service-URL variables are set with box config and override the corresponding box.json fields at runtime.

Control plane URL resolution

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

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

.gitignore generated by box create

box create writes a .gitignore that excludes:

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

See also

• Command reference.
• Concepts.