Appearance
Claim a machine
Claiming pairs a computer that runs the LivePane agent with your personal workspace. After claim, a machine link appears there and can host live terminal panes.
You need the agent installed first.
Who can confirm a claim: only you (the account / workspace owner). The claim API and Machines UI do not offer claim to anyone else.
One claim per host
Claim this computer once into your personal workspace. That creates one link and one token. Local tmux / cmux sessions are adopted automatically.
Someone else sees a session only when you share that session (email or link). Recipients find it under Shared with me on their dashboard — they do not claim this host.
--name is only for a second API server (for example production and staging). One API URL → one named servers[] entry. Re-claiming the same name overwrites that entry’s token.
After the workspace cut, leftover named entries for a deleted team workspace still sit in ~/.livepane/agent.json. Heartbeats for those tokens return 401. Delete the leftover entries; keep the personal (usually default) entry plus any other API hosts. See docs/billing.md.
Web claim flow
1. Open Machines and start the claim modal
Sign in and go to Machines. Click Link a machine (empty list) or Link another machine (when machines already exist). That opens a modal with the claim steps — claim never auto-opens on first visit; the button is always the entry.
2. Start claim on the computer
On the machine (SSH or local terminal), run the claim command with your LivePane API URL:
bash
livepane claim --server https://YOUR_SERVERThe modal shows a copyable command with the correct server URL for your environment. The agent prints a short claim code and waits for owner confirmation.
Leave that process running until claim finishes.
3. Confirm the code in the modal
In the claim modal:
- Paste the claim code from the agent.
- Click Confirm claim.
- On success the modal closes, the claim code is cleared, and the machines list refreshes so the new machine appears.
If your plan is at the machine limit, the app will say so before claim can complete — free a machine or upgrade, then try again.
4. Keep the agent online
Claim writes config to ~/.livepane/agent.json. The machine only stays online while the agent loop is running:
bash
livepane run
# or
livepane install-serviceHot-reload (preferred when run is already up): while livepane run (or the LaunchAgent / service that runs it) is active, claim and hand-edits to agent.json are watched and converged live — stacks for new/updated credentials start without a process restart. Same-credential reloads are no-ops. You only need to start the agent if nothing is running yet.
When restart still helps: if no run is up, start it (livepane run or install-service). If the binary is stale (pre-hot-reload build), upgrade then restart the service so the new process has the watcher. Residual: a rare hung stack may need a process restart; that is recovery, not the normal claim path.
Re-claim / credential change: converging a changed token for an existing entry restarts that stack. Live terminal streams on that entry may briefly interrupt (reconnect) during the stack swap — expected, not a claim failure.
Single-instance config lock: only one livepane run may hold a given config path. A second start prints another run already holds the config lock, sleeps ~3s (LaunchAgent backoff), and exits 75. Do not treat exit 75 as “claim failed” — an existing run is already serving that config.
Online means a recent heartbeat for that link (the web app treats a machine as offline after about 90 seconds without a heartbeat).
Supervisor logs (macOS after current install-service): ~/Library/Logs/livepane/agent.err.log (and agent.out.log). Read them with livepane log (default full dump; --lines N last N; --watch follow; --lines N --watch last N then follow). Linux uses the user systemd journal; Windows is unsupported. Without log paths, launchd discards stderr to /dev/null. Filter stack lines with server=<name>.
The web app reminds you to run the agent after a successful claim. Offline links cannot create new live panes until the agent heartbeats that token again.
What success looks like
| Step | You should see |
|---|---|
| Agent claim started | Claim code printed in the terminal |
| Web confirm | Machine row appears in Machines |
| Agent running | Machine status online (recent heartbeat) |
| Ready to work | You can create a session / pane on that machine |
Troubleshooting (product level)
| Symptom | What to try |
|---|---|
| Code rejected / expired | Run livepane claim again for a fresh code; confirm promptly |
| Forbidden / no claim form | Sign in as the account that owns this workspace |
| Machine stays offline after claim | (1) Is livepane run / service up for this host? (2) Second start exit 75 / “config lock” → another run already holds the lock — use that process; do not pile on. (3) Check stack start logs (server=<name>, err log) for the claimed entry. (4) Stale binary without hot-reload → upgrade + restart service. (5) Heartbeat 401 on a leftover named entry → delete that servers[] row (revoked token from a deleted team workspace). |
| Brief stream drop right after re-claim | Expected while the control stack restarts for new credentials; should reconnect once heartbeat resumes. |
| Offline but old sessions still listed | Stale discovery UI; agent not heartbeating this link — reconnect or re-claim here. Offline link bulk-marks live discovered panes gone (Unavailable) without durable exclude. |
| Agent ONLINE but session missing on host | Session-alive ping (UR-082): server asks agent session_alive for host+local_key. Definitive no → pane gone immediately. Timeout/list failure fail-open (does not invent gone). Surfaces: pane.session_alive / POST /api/panes/{pane}/session-alive on list refresh, open, idle. |
| Header Stream off while agent is ONLINE | Client WebSocket (Reverb) — not the agent. Browser/PWA: bake prod VITE_REVERB_* at SPA deploy (Forge). Pure iOS: REVERB_* in packages/ios xcconfig. Independent of agent_online. |
| Stream off and agent offline | Fix this workspace’s agent heartbeat first (livepane run / re-claim); if Stream stays off after ONLINE, then client/Reverb |
| “Could not refresh · showing last known” | Cached terminal snapshot — not live. Need Stream on and agent online for fresh capture |
| Claim blocked by limit | Remove an unused machine or upgrade plan capacity |
| Wrong server URL | Use the command copied from the web app for your environment |