Add your first host

An agent host is any machine running the qorin-agent. You can have one (your laptop) or many (laptop + workstation + shared VPS); each shows up in the dashboard sidebar with a colored dot for its current status.

This page assumes you've already followed Install on macOS or Install on Linux and run qorin-agent login once.

Status pill

In the sidebar, each host carries one of three pills:

• 🟢 online — the agent is connected and heartbeating; you can spawn workspaces on it.
• 🟡 enrolling — the host just registered but hasn't completed the handshake. Usually clears within a few seconds; if it sticks, see troubleshooting.
• ⚫ offline — last heartbeat was more than 90 seconds ago. The daemon is probably down (systemctl status qorin-agent, launchctl print system/dev.qorin.agent) or the machine is asleep.

Rename a host

The agent reports its system hostname when it enrolls (e.g. Mac.local, ip-10-0-0-42). Click the host row to give it a human-readable nickname like "office Mac" or "EU build box". Only shown in your dashboard; the daemon doesn't know about it.

Doctor check

The agent ships a self-check command:

sudo qorin-agent doctor

It reports:

• Whether the daemon is running, when it last heartbeat'd
• Which CLI agents are installed and reachable from the daemon's PATH (claude, codex, cursor-agent, gemini, opencode)
• Whether git and tmux are installed and at supported versions

Run it after every install + after any change to your PATH or shell profile.

Multi-host wisdom

A few things we learned the hard way:

• One host per role: laptop (main dev), workstation (heavy rebuilds), CI box (overnight runs). Each gets its own qorin-agent install. Workspaces are pinned to the host they spawned on — moving a workspace between hosts is a Phase 3+ feature.
• VPN / Tailscale: if your hosts are on a private network the agent still connects out to api.qorin.dev over HTTPS. No inbound ports needed on the host.
• Hot-laptop sleep: when your laptop sleeps the agent disconnects cleanly; on wake it reconnects and reconciles workspace state. Workspaces alive in tmux survive sleep — they keep the PTY going, Qorin re-attaches when the WS comes back up.

Next: Start your first workspace →