Nodes

A node is one of your servers running brig-agent. You bring the machines; Brig schedules workloads onto them. There are two ways to add a node — bootstrap an existing server over SSH, or have Brig provision a brand-new cloud VM — plus labels to steer placement.

List nodes

brig nodes      # id, hostname, CPU, memory, health, workload count, last heartbeat
brig status     # fleet-wide summary, including cordoned / dead nodes

Add an existing server

If you already have a VPS, bootstrap it over SSH:

brig node add [email protected]

Brig mints a one-shot join token, fetches the install script from the control plane, SSHes in, and runs it under sudo. The script installs Docker if needed, drops in brig-agent, and registers the node — Brig then waits for the agent to call home and prints the new node id. You can add several at once; they install in parallel.

Flag	Default	Meaning
-i, --identity	ssh-agent, then ~/.ssh/id_ed25519/id_rsa	SSH private key.
-p, --port	22	SSH port.
--label	—	Friendly label for the node (single host).
--ttl	900	Join-token lifetime in seconds (max 900).
--sudo-password	—	Sudo password, if the SSH user needs one.
--concurrency	5	Max parallel installs across multiple hosts.
--insecure-host-key	false	Skip SSH host-key verification (first-touch only; not recommended).
--print	false	Don’t SSH — just print the one-liner to paste manually (air-gapped / jump-host).

--print gives you the same command the dashboard shows under Nodes → Add node:

curl -fsSL https://cp.brig.run/install/agent.sh | sudo bash -s -- --token 'brig_join_xxx'

Provision a fresh cloud VM

To create a new machine and join it in one step:

brig node provision --provider hetzner --size cx22 --region fsn1

Brig mints a join token, renders a cloud-init payload that runs the install script on first boot, creates the instance, waits for the agent to register, and prints the node id. On failure it cleans up the VM and revokes the token (unless --keep-on-failure).

Supported providers: hetzner, ec2, digitalocean, azure, gcp, linode. Credentials come from ~/.brig/clouds.toml or BRIG_CLOUD_<PROVIDER>_<KEY> environment variables.

Flag	Default	Meaning
--provider	required	One of the providers above.
--size	—	Exact provider size id (e.g. cx22, t3.medium).
--vcpus + --memory-gib	—	Or specify minimums and let Brig pick the cheapest match.
--arch	—	amd64 or arm64 filter for spec-based picks.
--region / --zone	provider default	Where to place the VM.
--image	provider’s Ubuntu 24.04	OS image.
--label / --name	—	Node label / cloud-console VM name.
--ttl	1800	Join-token lifetime (cloud-init needs a few minutes).
--join-timeout	10m	How long to wait for the agent to register.
--keep-on-failure	false	Leave the VM + token for debugging on failure.
--list-regions / --list-sizes	—	Print what’s available for --provider and exit.
--dry-run	false	Print the cloud-init payload (token redacted) and exit.

Either give an exact --size, or a --vcpus/--memory-gib spec and let Brig choose. Probe a provider before committing:

brig node provision --provider hetzner --list-sizes --region fsn1

Hardware suggestions

• 1 vCPU / 1 GiB RAM is enough to run the agent plus a couple of small workloads.
• Linux with systemd. We test against Ubuntu 22.04, 24.04, and Debian 12.

Labels {#labels}

Labels are arbitrary tags on a node that workloads match against with placement.requires_labels. Setting labels is PUT semantics — pass the complete set you want, not just additions:

brig node labels node-7                 # print current labels
brig node labels node-7 us-east ssd     # replace the label set with exactly these two
brig node labels node-7                 # pass none again to clear

Then a workload can demand them:

[placement]
requires_labels = ["us-east", "ssd"]

See Placement for how the scheduler uses them.