box deploy

Register the box’s public domains with the control plane’s storefront resolver.

box deploy [options]

Synopsis

box deploy reads a box.yml deploy manifest and registers its domains with the control plane so the shared storefront render knows which backend owns each public host. It prints per-domain routing and DNS instructions and writes a dns.txt file.

The box must be authenticated (see box auth) and must have a backend URL — either from the --backend-url flag or from box.yml.

Options

Flag values override the corresponding fields in box.yml. Trailing slashes are trimmed from all URL values.

--verify and --remove are mutually exclusive with each other and with registration — each runs its own path and skips the default registration flow.

Behavior

Registration (default)

• Sends POST /boxes/deploy to the control plane with Authorization: Bearer <licenseKey> and a payload of { name, backendUrl, frontendUrl?, dashboardUrl?, domains }.
• Prints per-domain routing and the DNS records you must create.
• Writes a dns.txt file (and a legacy nameserver.txt) with the DNS instructions.

Persisted flags

After a successful registration, the flags you explicitly passed are written back into your config so later deploys don’t need them again:

• --backend-url → backendUrl in box.yml.
• --frontend-url → frontendUrl in box.yml, plus the derived host is added to the box.yml domains list (if not already present) and written to storefrontDomain in box.json.

Only flags you actually passed are persisted — omitting a flag never erases an existing box.yml value. The YAML document model is used to update box.yml, so your comments and formatting are preserved. The CLI prints which fields it updated (for example, box.yml updated (backendUrl, frontendUrl)).

Consolidated DNS records

When several hosts share the same DNS target (for example, acme-bank.example and *.acme-bank.example pointing at one CNAME value), the records are grouped by type + value + ttl and printed once with every name that points at them, instead of repeating the same target per host. The same consolidation is applied to the dns.txt file and to the offered nameservers.

Verification (--verify)

• Skips registration.
• Calls GET /boxes/deploy/status?name=<name> with the bearer license key.
• Reports the linked status of each domain (linked plus an optional detail).

Removal (--remove)

• Skips registration.
• Sends DELETE /boxes/deploy?name=<name> to the control plane with Authorization: Bearer <licenseKey>.
• The control plane detaches each registered host from the platform provider and clears its resolver mapping, so those hosts stop routing to this box. The response is { removed?: string[] } — the list of deregistered hosts.
• Prints each deregistered host, then a summary (Removed — N domain(s) no longer route to this box.).
• If no domains were registered, it warns No domains were registered for this box; nothing to remove. and exits.

Examples

# Register domains, taking the backend URL from the flag
box deploy --backend-url https://api.acme-bank.example
 
# Override frontend and dashboard origins too
box deploy \
  --backend-url https://api.acme-bank.example \
  --frontend-url https://shop.acme-bank.example \
  --dashboard-url https://admin.acme-bank.example
 
# Verify DNS / linkage after records propagate
box deploy --verify
 
# Tear down routing: deregister this box's domains from the resolver
box deploy --remove

Related configuration

The domains and default URLs come from 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

See also

• box.yml schema.
• Concepts → DNS & routing.
• Control plane endpoints.