Install and enroll a runner

The runner is a signed binary that executes your agents’ work — cloning, editing, running tests, opening pull requests — on a Mac you control. See Where things run for what that split buys you; this page is the mechanics of getting one running.

Before you start

An Apple Silicon Mac

Running macOS 13 or later. Intel is not supported.

Someone able to stay logged in

The runner needs a login session — see The login session below before you pick which Mac.

An OpenRouter account

Model spend for the actual work is billed to you directly, on a key that never leaves this machine.

An enrollment token

From Runners in your workspace sidebar → Enroll a runner. Owner or admin only, single-use, and expires in fifteen minutes.

The runner installs as a LaunchAgent, not a LaunchDaemon — it runs only while someone is logged in. This is deliberate: the Keychain holding your OpenRouter key, and your coding tool’s own login, both live in a user’s session, not in a boot-time daemon with none.

Situation	What happens
Someone logged in	Runner online
User logs out	Runner stops; cases park rather than fail
Reboot, auto-login on, no FileVault	Runner comes back on its own
Reboot with FileVault	Runner stays down until a human unlocks the Mac

The recommended setup is a dedicated macOS user with auto-login, on a machine that is not rebooted unattended. If your policy requires FileVault, budget for someone unlocking the Mac after every reboot — nothing is lost while it is down, cases simply wait. See Known gaps for the honest version of this trade-off.

Set it up

Desktop app (recommended)
Command line

One app: sign in, and it enrolls this Mac, installs the runner, and checks your coding tools for you. No command line needed.

brew install --cask metapouch/tap/agentick-desktop

Download the latest .dmg from
https://github.com/MetaPouch/agentick-desktop-releases/releases/latest,
open it, and drag Agentick to Applications.

Open Agentick and sign in with your workspace account.
On Set up this Mac, click Install next to the runner. It mints this Mac’s enrollment token with your own session — nothing is copied out of the dashboard — enrolls, installs the runner, and starts it.
The rows below fill in as the runner’s own doctor checks them: a coding tool signed in, an OpenRouter key, optional per-step user isolation. Continue needs the runner and a signed-in coding tool; everything else is optional and says what it is for.
Check it works waits for the runner to show online, then opens the monitor.

The app is signed with our Developer ID and notarized by Apple, so Gatekeeper opens it with no warning — verify it yourself with codesign --verify --strict /Applications/Agentick.app. It bundles the same signed runner binary the command-line path installs; the app is a guided wrapper around it, not a different thing running underneath.

Two install paths. Both give you the same signed, notarized binary — they differ in who is installing and what they are allowed to do.

curl -fsSL https://workspace.agentick.xyz/install.sh | sh

brew install metapouch/tap/agentick-runner

The curl path installs to ~/.local/bin, needs no administrator, and verifies the download’s SHA-256 against the checksum published with the release before it writes anything. Homebrew installs unprivileged too — it does not set up per-step user isolation; run agentick-runner provision-users afterward, as an administrator, if you want that.

Both paths install unsigned-looking to Gatekeeper’s eyes for an unrelated reason: macOS only quarantines a file downloaded by a browser, and neither curl nor brew triggers that. The binary itself is signed with our Developer ID and notarized by Apple either way — verify it yourself with codesign --verify --strict $(which agentick-runner).

Enroll

agentick-runner doctor --url https://api.workspace.agentick.xyz
agentick-runner enroll --url https://api.workspace.agentick.xyz --token agrt_...
pbpaste | agentick-runner set-key      # your OpenRouter key
agentick-runner install-agent --url https://api.workspace.agentick.xyz

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.agentick.runner.plist

Run doctor first. On a restrictive network it tells you which hop failed — DNS, proxy, TLS, or reaching us at all — rather than leaving you with a bare connection error.The enrollment command is also shown to you, filled in with your actual token, on the Runners page the moment you issue it — copy it from there rather than retyping it.The key is piped in on stdin, never passed as an argument: a key on a command line ends up in your shell history and is visible to every other process on the machine via ps.install-agent writes the LaunchAgent file; it does not start it. The launchctl bootstrap line is what actually launches it and keeps it running across logins and crashes.

Confirming it worked

The runner appears on the Runners page as online within a few seconds. If it does not, and you used the command line:

tail -f ~/.agentick/runner/logs/runner.err.log
agentick-runner doctor --url https://api.workspace.agentick.xyz

The desktop app’s monitor shows the same doctor output without a terminal.

Next: give it something to work with

Enrolling gets the machine online; an agent still needs a coding tool signed in on it. From the agent’s page in the dashboard, its readiness panel checks this runner directly — which tools are installed, which are logged in, which repositories it can actually clone — and tells you the exact command to run for whatever is missing. The desktop app’s setup page checks the same things in place.

Getting a newer version

Self-updating is designed into both the runner binary and the desktop app — the runner can check your workspace for a newer release, drain in-flight work first, verify the new binary’s signature twice, and swap it in atomically with automatic rollback if the new one fails to start; the desktop app ships with electron-updater for the same reason. Neither is switched on yet. Until they are, get the newest version the same way you installed it:

Desktop app
Command line

brew upgrade --cask agentick-desktop

Download the latest .dmg from
https://github.com/MetaPouch/agentick-desktop-releases/releases/latest
and drag it over the old copy in Applications.

Quit and reopen the app afterward either way.

curl -fsSL https://workspace.agentick.xyz/install.sh | sh   # or: brew upgrade agentick-runner

Restart it afterward so it picks up the new binary:

launchctl kickstart -k gui/$(id -u)/com.agentick.runner

We will say here, plainly, once fleet-wide automatic updates are live, rather than let you discover their absence from a stale version.

Uninstall

The desktop app is a guided wrapper around the same runner the command line installs, so removing either path removes the underlying runner the same way:

launchctl bootout gui/$(id -u)/com.agentick.runner
rm ~/Library/LaunchAgents/com.agentick.runner.plist
rm -rf ~/.agentick/runner
security delete-generic-password -s com.agentick.runner

If you installed the desktop app, also quit it and drag Agentick from Applications to the Trash — that removes the app itself, not the runner underneath it, which the commands above cover. Also revoke the runner from the Runners page — deleting the binary stops it running, but revoking is what stops its credential from working at all.

Setup

Trust

Install and enroll a runner

Before you start

An Apple Silicon Mac

Someone able to stay logged in

An OpenRouter account

An enrollment token

Set it up

Enroll

Confirming it worked

Next: give it something to work with

Getting a newer version

Uninstall

​Before you start

An Apple Silicon Mac

Someone able to stay logged in

An OpenRouter account

An enrollment token

​The login session

​Set it up

​Enroll

​Confirming it worked

​Next: give it something to work with

​Getting a newer version

​Uninstall

Before you start

The login session

Set it up

Enroll

Confirming it worked

Next: give it something to work with

Getting a newer version

Uninstall