`box config`

View or set this box’s service URLs and deploy defaults, persisted to box.json.

box config [options]

Synopsis

With no flags, box config prints the box’s current configuration — each service URL resolved from box.json (or an environment override), plus the deploy pipe. With one or more flags it writes the given values to box.json and prints the updated configuration.

These URLs describe where the box’s own services live (engine, console, back office, host) and the storefront base host used to build tenant links. They feed the console’s NEXT_PUBLIC_* variables and are the single source of truth that box deploy reads when generating artifacts and registering domains.

Options

Option	Description
`--engine-url <url>`	Public URL of the box engine (backend/API). Drives `BOX_ENGINE_URL`.
`--console-url <url>`	Public URL of the box console (merchant dashboard). Drives `BOX_CONSOLE_URL`.
`--back-office <url>`	Public URL of the box back office (the `/admin` platform console). Drives `BOX_BACK_OFFICE_URL`.
`--admin-office <url>`	Alias for `--back-office`. Passing both is an error.
`--host-url <url>`	Public host URL of the box. Drives `BOX_HOST_URL`.
`--storefront-domain <host>`	Per-bank storefront base host (e.g. `shop.acme.com`); tenants resolve as `<slug>.<host>`. Drives `NEXT_PUBLIC_STOREFRONT_DOMAIN`.
`--deploy-pipe <targets>`	Which artifacts `box deploy` generates by default — a comma/space list of `dockerfile`, `compose`, `github`, `terraform`, or `all`.

Behavior

View (no flags)

Prints each resolved service URL and the deploy pipe. A value shown with a (from BOX_…) note means an environment variable is currently overriding box.json. Unset values are shown as <unset>, and an unset deploy pipe shows the default set (dockerfile, compose, github) marked (default).

Set (one or more flags)

URL flags (--engine-url, --console-url, --back-office / --admin-office, --host-url) are validated as absolute http(s) URLs, canonicalized (trailing slashes trimmed), and written to box.json. Passing an empty value clears that field.
--storefront-domain takes a bare host, not a URL. Any scheme and trailing slashes are stripped and the host is lowercased. An empty value clears it.
--deploy-pipe persists the requested target set (validated against dockerfile, compose, github, terraform, or all). An empty value resets it to the default set.

After writing, the command prints the updated configuration.

--storefront-domain only drives NEXT_PUBLIC_STOREFRONT_DOMAIN for link building. Registering the domain with the control plane’s storefront resolver is the separate box deploy --register-domains path.

The engine URL you set here is reused elsewhere: box deploy --register-domains defaults its backend origin from box.json’s engineUrl (when box.yml has no backendUrl and --backend-url isn’t passed), so the box’s own console and the storefront resolver stay pointed at the same engine.

Examples

# Show the current configuration
box config
 
# Set the engine, console, back office, and host URLs
box config \
  --engine-url https://api.acme-bank.example \
  --console-url https://app.acme-bank.example \
  --back-office https://admin.acme-bank.example \
  --host-url https://acme-bank.example
 
# Set the per-bank storefront base host (tenants resolve as <slug>.shop.acme-bank.example)
box config --storefront-domain shop.acme-bank.example
 
# Choose which artifacts `box deploy` generates by default
box config --deploy-pipe dockerfile,compose,terraform
 
# Clear a value (empty string) / reset the deploy pipe to the default set
box config --console-url '' --deploy-pipe ''

The values are persisted to box.json:

box.json

{
  "engineUrl": "https://api.acme-bank.example",
  "consoleUrl": "https://app.acme-bank.example",
  "backOfficeUrl": "https://admin.acme-bank.example",
  "hostUrl": "https://acme-bank.example",
  "storefrontDomain": "shop.acme-bank.example",
  "deployPipe": ["dockerfile", "compose", "terraform"]
}

Every URL can also be overridden at runtime by the matching environment variable (BOX_ENGINE_URL, BOX_CONSOLE_URL, BOX_BACK_OFFICE_URL, BOX_HOST_URL, BOX_STOREFRONT_DOMAIN) — see Configuration → Environment variables.

box config