Pairing

The first time you launch Atlas, the pairing wizard opens automatically. After successful pairing, the wizard never reappears unless you unpair the machine.

Get a pairing key

In your OwnLLM admin space:

Go to Admin → Agents.
Click Generate pairing key.
Copy the key (ownllm_pair_<32-hex>). It expires in 7 days and is single-use.

Paste it into Atlas

In the wizard:

Paste the key into the input. Atlas validates the format client-side before submitting.
Click Connect. The wizard:
- Hashes the host machine ID.
- Posts the key + machine ID + host specs (VRAM, RAM, CPU cores, GPU type, OS) to POST /api/v1/agents/pair.
- Receives the agent token + Cloudflare Tunnel credentials + the list of recipes the admin pre-selected at signup.
- Writes the secrets to the OS keychain (Keychain on macOS, Credential Manager on Windows, Secret Service on Linux).
Atlas registers itself as a service so it restarts on boot, then starts Ollama and cloudflared as supervised subprocesses.
The wizard closes and the dashboard takes over.

What you'll see during pairing

The wizard shows a four-step progress indicator:

[●] Validate key            ✓
[●] Provision tunnel        ✓
[●] Install runtimes        downloading ollama 0.6.4 …
[ ] Pull recommended models   queued

The Install runtimes step downloads Ollama and cloudflared if they aren't already present (~150–200 MB total). On a fresh install this takes 30–60 seconds on a fast connection.

The Pull recommended models step is optional and can be skipped — you can install models later from the Models page.

Errors

Message	Meaning
`Invalid pairing key`	Format check failed (length, prefix).
`Pairing key expired`	Older than 7 days — generate a new one.
`Pairing key already used`	Single-use; generate a new one.
`Network error`	Atlas can't reach `ownllm.app`. Check egress / TLS.
`Machine already paired`	A previous Atlas (or CLI) install paired this host. Run Unpair first.

If the wizard hangs on Provision tunnel, the most common cause is egress filtering: cloudflared needs outbound TCP 7844 (or HTTPS 443 fallback). On a corporate network, ask IT to open one of those.

Unpairing

Settings → Account → Unpair this machine disconnects the host:

Stops the daemon and cloudflared.
Calls POST /api/v1/agents/unpair so the site marks the agent offline immediately.
Wipes the keychain entries.

The Cloudflare Tunnel is deleted on the OwnLLM side; the next pairing provisions a fresh one.

Re-pairing

A machine can be paired to one tenant at a time. To switch tenants, unpair first, then run the pairing wizard again with a key from the new tenant.

Headless

Atlas is GUI-only. To pair a headless host, install the CLI and run ownllm pair <key> instead.