`box start`

Run the box’s engine and/or console locally.

box start [name] <engine-port> <console-port> [db-name] [options]

Synopsis

box start launches the box’s stack — the engine (backend API) and the console (admin dashboard) — on the ports you specify. You can run the full stack, just the engine, or just the console.

Under the hood the command invokes a CLI-owned start-box.sh launcher and sets up the child process environment described below.

Positional arguments

The command accepts positional arguments in this order:

[name] <engine-port> <console-port> [db-name]

Position	Description
`name`	Box name. Falls back to the `name` in `box.json`, then to the license `customerId`.
`engine-port`	Port for the engine (backend API).
`console-port`	Port for the console (admin dashboard).
`db-name`	Optional database name.

Use - as a placeholder for a side you do not want to start. For example, box start acme-bank - 3010 starts only the console.

Options

Option	Description
`--engine <port>`	Run the engine only on the given port.
`--console <port>`	Run the console only on the given port.
`--name <name>`	Explicit box name (overrides the positional/`box.json`/license fallback).
`--db <name>`	Database name.
`--tunnel`	Expose the engine publicly through an ngrok tunnel and print the public URL.

Behavior

Full stack: provide both engine-port and console-port (positionally or via flags) to start both sides.
Engine only: use --engine <port> (or pass - for the console port).
Console only: use --console <port> (or pass - for the engine port).
The console is served on <name>.localhost.
--tunnel runs ngrok against the engine and prints a public URL you can pass to box deploy --backend-url.

Child process environment

box start sets the following environment variables for the launched stack:

Variable	Value
`WEB_REGISTRY_URL`	`<controlPlane>/templates/registry`
`TRUSTED_REGISTRY_HOST`	Host of the trusted registry.
`CONTROL_PLANE_URL`	The resolved control plane URL.
`POTTER_LICENSE_KEY`	The box’s license key.
`BOX_WEB_URL`	Resolved web control URL (see `resolveWebControlUrl`).
`BOX_STOREFRONT_DOMAIN`	The storefront base host, when configured.

See configuration → environment variables for how BOX_WEB_URL and BOX_STOREFRONT_DOMAIN are derived.

Examples

# Full stack: engine on 4000, console on 3010
box start acme-bank 4000 3010
 
# Engine only
box start --engine 4000
 
# Console only (positional placeholder form)
box start acme-bank - 3010
 
# Full stack with a public tunnel for the engine
box start acme-bank 4000 3010 --tunnel

The public URL printed by --tunnel is what you hand to box deploy --backend-url so the shared storefront render can reach your local engine.

box start