> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentick.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# Install and enroll a runner
> Put the runner on hardware you own, and connect it to your workspace.
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](/trust/where-things-run) for what that split buys you; this
page is the mechanics of getting one running.
## Before you start
Running macOS 13 or later. Intel is not supported.
The runner needs a login session — see [The login session](#the-login-session)
below before you pick which Mac.
Model spend for the actual work is billed to you directly, on a key that
never leaves this machine.
From **Runners** in your workspace sidebar → **Enroll a runner**. Owner or
admin only, single-use, and expires in fifteen minutes.
## The login session
**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](/trust/known-gaps#a-locked-laptop-is-a-stopped-agent)
for the honest version of this trade-off.
## Set it up
One app: sign in, and it enrolls this Mac, installs the runner, and checks
your coding tools for you. No command line needed.
```sh Homebrew theme={null}
brew install --cask metapouch/tap/agentick-desktop
```
```text Manual download theme={null}
Download the latest .dmg from
https://github.com/MetaPouch/agentick-desktop-releases/releases/latest,
open it, and drag Agentick to Applications.
```
1. Open Agentick and sign in with your workspace account.
2. 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.
3. 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.
4. **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.
```sh curl theme={null}
curl -fsSL https://workspace.agentick.xyz/install.sh | sh
```
```sh Homebrew theme={null}
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
```sh theme={null}
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:
```sh theme={null}
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:
```sh Homebrew theme={null}
brew upgrade --cask agentick-desktop
```
```text Manual download theme={null}
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.
```sh theme={null}
curl -fsSL https://workspace.agentick.xyz/install.sh | sh # or: brew upgrade agentick-runner
```
Restart it afterward so it picks up the new binary:
```sh theme={null}
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:
```sh theme={null}
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.