The credential model behind broker onboarding — the register-only join key vs the per-machine install credential, how fleets bind, single-use vs reusable keys, where credentials live, and the security properties. Read this to plan a fleet rollout.

Onboarding a Broker is the step-by-step how-to. This page is the how-it-works — the model you need to plan a rollout across a company: how many keys to mint, when to make one reusable, which fleet a key enrolls into, where each broker's credential lives (for a security review), and what actually happens if a join URL leaks.

Two credentials, two jobs

The single most important thing to understand: a broker uses two different credentials at two different moments. Conflating them is the source of most confusion.

	Join key	Install credential
Prefix	`mc_…`	`mci_v1_…`
Who holds it	you mint it; you paste/share it	the broker (one per machine)
When it's used	once, at register	every call after register
What it can do	register only	full data-plane (tenant-scoped)
Carries	the target tenant + (optional) fleet	the machine's identity
Where it lives	a join URL you copy	the broker's keychain (see below)

The join key is what rides in the install one-liner (MEMCLAW_JOIN_URL='…/join/mc_…'). It is register-only: the cloud accepts it only at POST /installs/register and rejects it (403) on every data-plane endpoint (search, memories, MCP, dashboard). It carries the destination — a tenant, and optionally a fleet.
The install credential is minted by the cloud at register, unique to that machine, and becomes the broker's steady-state credential. The daemon sends it as the X-API-Key header on every subsequent call — claim, heartbeat, the fleet-policy SSE stream, command acknowledgements, and audit-log uploads.

A join key never grants data access

The join key is a bootstrap artifact, not a data credential. Even if the join URL leaks (a pasted chat message, browser history, a CI log), the worst case is that someone enrolls a rogue broker into your fleet — which shows up in the Broker Fleet dashboard, is revocable, and is bound to the enrolling machine's fingerprint. There is no path from a leaked join key to your memories. This is a deliberate least-privilege design (ADR-0001); it's what makes a reusable key safe to drop into an MDM script or a shared channel.

What actually happens during onboarding

Mint (org-admin, in the dashboard)

Broker Fleet → Onboard a broker → pick the home tenant and fleet, choose Single-use or not, and copy the install command (or the join URL). The mc_ key is created with those bindings baked in.

Register (once, on the target machine)

install.sh downloads the binary and runs memclaw setup --join, which sends the join key one time to POST /installs/register, along with the machine's install_uuid and a machine fingerprint. The join key is never sent again.

Exchange for a per-machine credential

The cloud validates the join key and returns an install credential (mci_v1_<hmac>), derived from this machine's install_uuid. The broker stores it in its keychain. If the key was single-use, it is revoked now, in the same transaction — a second machine presenting it gets a terminal 403.

Join the fleet

The cloud binds the install to the join key's fleet and seeds a default policy if that fleet is brand-new. The broker opens its policy SSE stream and receives the current fleet policy live.

Wire + run

Detected agents are wired to route through the broker; the daemon starts. From here on, every cloud call authenticates with the install credential — the join key is done.

Fleets: one key → one fleet

A join key is pinned to a single fleet at mint time. The broker cannot override it — there is no --fleet flag, and the register request carries no fleet field; the fleet is resolved entirely from the key's server-side binding and reported back to the broker.

To enroll brokers into several fleets, mint one join key per fleet. The same key can't be repointed at a different fleet.
A key can also be fleetless (leave Fleet blank) — the broker registers to the tenant without joining a fleet.
Fleet names are free-form labels — there is no fleet registry to create first. A name that's never been used is materialized (with a default policy) on the first register that references it.

A mistyped fleet name creates a new fleet — silently

Because the fleet is a free-text label with no validation, a typo at mint time mints into a brand-new, one-broker fleet rather than erroring (unlike the tenant, which is validated against your org). When minting, copy the exact name of an existing fleet — or deliberately choose a new one. Double-check the Fleet field before you hand the key out.

Single-use vs reusable — planning a rollout

The Single-use toggle (on by default) is the one decision that shapes a rollout:

Single-use — the key self-revokes after the first successful register. Use it for a one-off host or a high-sensitivity onboarding where the key should work exactly once.
Reusable (untick Single-use) — the same key/URL enrolls any number of machines into its fleet. Use it for a fleet rollout.

Situation	Mint a key that is…
Rolling out to a team / fleet (MDM or IT push)	reusable, one per fleet
A single machine, or a sensitive host	single-use
Automated / repeated onboarding (CI, nightly e2e)	reusable

Reusability affects only the bootstrap step. Every machine still receives its own install credential (next section) — a reusable key is not a shared steady-state secret. Revoke a key any time from API Credentials, or revoke an already-enrolled broker from Broker Fleet → Brokers.

Where the credential lives (for security review)

Each broker's install credential is stored only on that machine, in its keychain — never in an agent's config file, and never shown again after register.

Default: the OS keychain — macOS Keychain, Linux Secret Service, or Windows Credential Manager.
Headless hosts (a CI runner, a VM over SSH, a container with no desktop session): set MEMCLAW_KEYCHAIN=file and the credential is written to a 0600 JSON file at <MEMCLAW_HOME>/identity/keychain.json. install.sh selects this automatically when it detects no session keychain.
Cloud side stores only a SHA-256 hash of the credential — the raw token never leaves the machine.
Per-broker, not shared. The credential is HMAC-derived from the machine's own install_uuid, so two brokers onboarded with the same reusable key still hold distinct credentials. Revoking one broker never affects another.

Prerequisites & who can do what

A tenant must exist first. The join key is minted against a home tenant that already belongs to your org (the mint form only lists your org's tenants).
A fleet does not need to exist first — see above.
Minting a join key is an org-admin action. Running the installer on the target machine needs only a shell and the copied command — no MemClaw account on that machine.

FAQ

Do I need a tenant and a fleet before onboarding? A tenant, yes (it's the key's home tenant). A fleet, no — name any fleet at mint and it's created on first register.

Can I onboard many brokers with one command? Yes — mint the key reusable (Single-use off). Single-use keys work for exactly one machine.

Can one key enroll brokers into different fleets? No. A key is pinned to one fleet. Mint a separate key per fleet.

After onboarding, what does a broker authenticate with? Its own per-machine install credential (mci_v1_…) in the X-API-Key header — not the join key. The join key is used only once, at register.

Do all my brokers share a key? No. Each machine gets a unique install credential, even when they were onboarded with the same reusable join key.

Where is the credential kept, and can I audit it? In the broker's keychain (OS keychain, or a 0600 file under MEMCLAW_HOME with MEMCLAW_KEYCHAIN=file). The cloud keeps only a hash; the raw token stays on the machine.

A join URL leaked — what's the exposure? It's register-only, so the worst case is a rogue broker enrolling into the fleet — visible in the dashboard, fingerprint-bound, and revocable. No access to memories. Revoke the key in API Credentials and revoke any unexpected broker in Broker Fleet → Brokers.

How do I remove a broker? Revoke it from Broker Fleet → Brokers (hard-revokes its credential and closes its fleet membership), or run memclaw leave-fleet on the host to unbind it.

How Onboarding Works