pair

ownllm pair ownllm_pair_<32-hex>

Pairing exchanges a single-use, 7-day-TTL pairing key (issued by the site at signup or regenerated by an admin) for a long-lived agent token. The agent token, the tunnel credentials, and the tenant slug all land in the OS keychain — never in a plain-text file.

Flags

--no-service skips the OS service registration. By default, successful pairing also runs ownllm service install so the agent restarts on boot.

ownllm pair ownllm_pair_abc... --no-service

Use --no-service when:

• You're testing pairing in a VM or container that won't outlive the session.
• You manage your own service supervisor (Kubernetes, Nomad, custom systemd unit).
• You'll run ownllm run in the foreground (debug mode).

What happens during pairing

1. The CLI hashes the host machine ID (hostname + arch + a random salt) into a stable identifier.
2. It posts the pairing key + machine ID + agent version + host specs (VRAM, RAM, CPU cores) to POST /api/v1/agents/pair.
3. The site validates the key, marks it consumed, creates a Cloudflare Tunnel via the Cloudflare API, and returns the agent token + tunnel credentials + the list of recipes the admin pre-selected at signup.
4. The CLI writes the secrets to the keychain, the public tenant slug to ~/.config/ownllm/config.toml, and (unless --no-service) registers the OS service.
5. Heartbeats start firing every 30 seconds.

Re-pairing

A machine can be paired to exactly one tenant at a time. To switch tenants, run ownllm unpair first. To rotate credentials inside the same tenant, an admin can regenerate the pairing key on the site and run pair again.

Errors

Troubleshooting

If pairing seems to hang, exit with Ctrl+C and run ownllm doctor — it walks each step and prints PASS / WARN / FAIL.