Install on macOS

The qorin-agent is a single static Go binary. Installing it is two steps: drop the binary on the machine, then connect it to your Qorin account and keep it running as a background service.

Requirements

• macOS 12 or newer (Apple Silicon or Intel — both binaries are shipped).
• A CLI coding agent already installed and authenticated — at least one of: claude, codex, cursor-agent, gemini, opencode. Qorin doesn't install them for you; you log into your chosen CLI yourself.
• Admin (sudo). There is no per-user setup: ADR-022 removed it, because a daemon that dies when you log out is a Qorin presence the machine's owner cannot see or stop. Both the installer and qorin-agent service install require root.

1. One command

curl -fsSL https://dl.qorin.dev/install.sh | sudo sh

That is the whole install. The script:

1. downloads the right architecture, verifies it against the SHA-256 manifest at dl.qorin.dev/SHA256SUMS, and puts it in /usr/local/bin;
2. signs this machine in to your Qorin account in your browser;
3. installs the system LaunchDaemon — starts at boot, survives logout, serves every OS user on the Mac — and checks that it is actually running before it says so.

It prints what it is about to do before the first privileged action; QORIN_DRY_RUN=1 prints the plan and stops.

The daemon setuids to the requesting Qorin user before spawning any CLI, so each user keeps their own dotfiles, credentials, and history. That is the right default: you can reach your Mac from the web app and your phone whether or not you are sitting in front of it.

Binary	/usr/local/bin/qorin-agent
Service	/Library/LaunchDaemons/dev.qorin.agent.plist
Runs as	root — it drops to each person's own UNIX user for their work
Needs sudo	yes — the installer re-runs itself under sudo if you forget
Why not ~/.local/bin	the daemon runs as root, and on macOS a home directory can sit on an encrypted volume that isn't mounted at boot — a real cause of "the service won't start after a reboot"

Root is required, and there is no lesser mode

There used to be a per-user install that ran without admin rights. It is gone (ADR-022): a per-user agent is a Qorin presence the machine's owner never authorised, and a machine you cannot see you cannot control. One machine now runs exactly one agent, owned by whoever controls the machine.

If you already have a per-user agent, the root install removes it for you.

Just trying it out

qorin-agent serve runs the agent in the foreground and stops when you close the terminal. It is a run mode for debugging and container images, not an install mode — nothing survives a reboot.

From the dashboard: the same command, with your token

Agents → Connect an agent in the dashboard (web, phone or the Mac app) shows the same command carrying a one-shot token:

curl -fsSL https://dl.qorin.dev/install.sh | sudo sh -s -- --token <token>

Same script, same three steps — except step 2 needs no browser: the token registers the machine with the organisation you were signed in to when you copied it. Tokens last 15 minutes and work once.

Already installed the binary some other way?

Then only the connect-and-run half is missing — one command too:

sudo qorin-agent install             # sign in in the browser, then the daemon
sudo qorin-agent enroll <token>      # or: with a token from the dashboard

Both refuse to run on a machine that is already connected — it belongs to an organisation, and moving it would cut its workspaces off from their owners. To add yourself to a connected Mac, run qorin-agent login as your own user (no sudo); to move it, sudo qorin-agent logout first.

One more step if your code lives in Desktop, Documents or Downloads

macOS keeps those three folders — plus iCloud Drive and external volumes — behind a privacy layer called TCC, and it grants access by asking you in a window. The Qorin agent starts at boot, before anyone logs in, so macOS can never put that window on a screen: it just refuses, silently, forever.

If your projects live somewhere you made yourself (~/Projects, ~/dev, /opt…), skip this — you will never meet it.

Otherwise, grant the permission once, to the binary:

1. System Settings → Privacy & Security → Full Disk Access → +
2. The picker hides /usr/local, so press ⌘⇧G and type /usr/local/bin/qorin-agent
3. Turn its switch on, then restart the service:

sudo qorin-agent restart

qorin-agent doctor tests this for you and says exactly what is blocked. Full explanation, and what it looks like when it bites: Folders are empty or refused on macOS.

It is not your UNIX account

The folder is yours and the permission bits say yes. Changing your mapped user, or asking an administrator, changes nothing — neither is the layer saying no.

Verify

In the dashboard at app.qorin.dev, the Agent hosts section in the sidebar should show your Mac with a green "online" pill within ~10 seconds. If it doesn't, run qorin-agent doctor or see troubleshooting › Agent shows offline.

Update

When the dashboard shows an update is available, click Update on the host — or update from the Mac:

qorin-agent upgrade

Uninstall

Remove this machine from your account (stops the service, revokes the token, deletes state):

qorin-agent uninstall

For a complete removal that also deletes the binary, data dir, and logs (use sudo if you installed the system daemon):

sudo qorin-agent uninstall --purge

Next: Add your first host →