How Onboarding Works

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.

• 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.

What actually happens during onboarding

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.

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.

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.

Which agent a broker's writes belong to (the ownership boundary)

A broker writes memories on behalf of the agents it fronts, and each write names the agent id it should be attributed to. Because one install can name any agent id, the cloud enforces an ownership boundary: an install may only attribute a memory to an agent it owns. This keeps two brokers in the same tenant — for example, two machines onboarded from the same reusable key — from writing under each other's agent identities.

• First touch owns. The first install to write as a given agent id becomes its owner — the cloud stamps that install's identity onto the agent. No setup; it happens on the first write.
• A foreign name is redirected, never blocked. If a different install later names that agent, its write is transparently re-attributed to that install's own fallback identity, broker:<install_uuid>, instead of the owned agent. The write still succeeds — it just lands under the caller's own identity, never the owner's.
• Same-install writes pass through unchanged. An install writing as its own agent always keeps that name.

The boundary holds on every write surface a broker can reach — single and bulk memory writes, document ingest, and short-term-memory promotion — so no endpoint bypasses it.

This is defense-in-depth. A normal broker only ever writes as its own agents, so the redirect is a backstop rather than a path anyone hits in day-to-day operation — it's there so a compromised or misconfigured broker cannot forge attribution onto an agent another install owns.

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.

Can one broker write memories as another broker's agent? No. The first install to write as an agent id owns it; a different install naming that agent has its write redirected to its own broker:<install_uuid> identity — it cannot attribute a memory to an agent another install owns. This holds on every write surface (memories, bulk, ingest, STM promote). See the ownership boundary.

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.