Box CLIQuickstart

Quickstart

This walkthrough takes you from nothing to a running box with public domains registered. It assumes the CLI is already installed (see the overview).

⚠️

You need a license key from Potter before you start. The key entitles your box to a specific tier and set of @withpotter/* packages.

Create the project

box create acme-bank
cd acme-bank

box create scaffolds a new project from the bundled template and writes a box.json manifest plus a .gitignore. The box name must match ^[a-z][a-z0-9-]*$ (lowercase letters, digits, and dashes; must start with a letter), and the target directory must be empty.

If your control plane is not the default, point the box at it now:

box create acme-bank --control-plane https://control.example.com

The control-plane URL can also come from the BOX_CONTROL_PLANE environment variable. See resolution order.

Authenticate the license

box auth --org acme-bank --key <license-key>

This activates the license against the control plane and then:

  • logs in to the entitled package registry and writes .npmrc,
  • records the license metadata in box.json,
  • stores secrets in .box/credentials.json (mode 0600),
  • composes the entitled engine packages and projects the console’s page groups.

.box/ and .npmrc are git-ignored by the generated .gitignore — never commit them. See credentials.

Install the engine

box install

Installs the entitled engine packages and their dependencies through the registry you just authenticated against.

Run the stack locally

box start acme-bank 4000 3010

The positional arguments are [name] <engine-port> <console-port> [db-name]. This starts the engine on port 4000 and the console on port 3010. The console is served on acme-bank.localhost.

To run only one side, pass - as a placeholder for the side you want to skip, or use the explicit flags:

box start --engine 4000     # engine only
box start --console 3010    # console only

To expose the engine publicly through an ngrok tunnel (useful for connecting the shared storefront render to a local backend):

box start acme-bank 4000 3010 --tunnel

The printed public URL can be passed to box deploy --backend-url.

Register public domains

Create a box.yml describing the domains your box should answer for, then register them with the control plane:

box deploy --backend-url https://api.acme-bank.example

box deploy posts your domains to the control plane resolver, prints per-domain routing and DNS instructions, and writes a dns.txt file. Once your DNS records are live, verify them:

box deploy --verify

Where to go next

Overviewbox create