Machines & the agentrqd Daemon

Read This Before You Enrol a Machine

Enrolling Is a Grant

Enrolling a machine lets anyone who can authenticate as that AgentRQ account run commands on it as the user who started the daemon. Compromise of the account is compromise of every enrolled machine.

That is the whole trust model in one sentence, and it is not a caveat. An agent started on your machine can read every file you can read, write every file you can write, reach every network your machine can reach, and use every credential sitting in your home directory — because it is you, as far as the operating system is concerned.

So

— Enrol machines you would be comfortable giving that account a shell on.
— Protect the AgentRQ account accordingly. Your machines are only as safe as it is.
— Do not enrol a machine that holds something the account's owner should not have.

The daemon refuses to run as root or Administrator, which limits the damage an agent can do to what you can do. That is a meaningful limit and it is not isolation.

Installing It

agentrqd is one static binary. Put it on your PATH, enrol it, run it. The steps below are for the platform this page thinks you are reading on — pick another if you are setting up a different machine, which is the usual case.

The Script — Linux

Install the daemon

curl -fsSL https://agentrq.com/install-agentrqd.sh | sh

It works out which archive this machine needs, verifies it against the SHA-256 checksums published with the release, and installs to ~/.local/bin. Running it again updates in place. It installs and nothing more: it does not enrol the machine, start anything, install a service, or run as root.

The Checksum Is Not Optional

There is no flag to skip it — a download the script cannot vouch for is never unpacked, let alone installed. That is the part worth having: installing by hand, below, verifies nothing at all unless you do it yourself.

If you would rather read it first, which is a fair thing to want on the machine you are about to grant command access to:

Fetch, read, run

curl -fsSL https://agentrq.com/install-agentrqd.sh -o install-agentrqd.sh
less install-agentrqd.sh
sh install-agentrqd.sh

Same install, and it is about 300 lines of POSIX sh. To pass flags through the one-liner, put them after -s --:

Pinning a release

curl -fsSL https://agentrq.com/install-agentrqd.sh | sh -s -- --version 0.7.0

--version pins a release, --dir installs somewhere else, --force reinstalls, and --help lists them.

Or by Hand — Linux

Releases are on the releases page — pick the archive for the machine you are installing on, not the one you are reading this on.

Linux

tar xzf agentrqd_*_linux_*.tar.gz
install -m 0755 agentrqd ~/.local/bin/

Do Not Run the Daemon as Root

The daemon refuses to run as root, because an agent it starts would inherit those powers. Nothing in a Linux install needs sudo. If an install guide anywhere tells you to work around that refusal, it is removing the only thing keeping an agent to what you can already do yourself.

Nothing here verifies what you downloaded. If you install by hand, check it against checksums.txt on the release page yourself:

Verify a manual download

sha256sum -c checksums.txt --ignore-missing

That is the one thing the script does that a manual install usually skips, and the reason it is worth preferring.

The Script — macOS

Install the daemon

curl -fsSL https://agentrq.com/install-agentrqd.sh | sh

It works out which archive this machine needs, verifies it against the SHA-256 checksums published with the release, and installs to /usr/local/bin. Running it again updates in place. It installs and nothing more: it does not enrol the machine, start anything, install a service, or run as root.

The Checksum Is Not Optional

There is no flag to skip it — a download the script cannot vouch for is never unpacked, let alone installed. That is the part worth having: installing by hand, below, verifies nothing at all unless you do it yourself.

If you would rather read it first, which is a fair thing to want on the machine you are about to grant command access to:

Fetch, read, run

curl -fsSL https://agentrq.com/install-agentrqd.sh -o install-agentrqd.sh
less install-agentrqd.sh
sh install-agentrqd.sh

Same install, and it is about 300 lines of POSIX sh. To pass flags through the one-liner, put them after -s --:

Pinning a release

curl -fsSL https://agentrq.com/install-agentrqd.sh | sh -s -- --version 0.7.0

--version pins a release, --dir installs somewhere else, --force reinstalls, and --help lists them.

Or by Hand — macOS

Releases are on the releases page — pick the archive for the machine you are installing on, not the one you are reading this on.

macOS

tar xzf agentrqd_*_darwin_*.tar.gz
sudo install -m 0755 agentrqd /usr/local/bin/

That sudo Copies a File, and Nothing More

It puts the binary into /usr/local/bin. The daemon itself refuses to run as root, because an agent it starts would inherit those powers. If an install guide anywhere tells you to work around that refusal, it is removing the only thing keeping an agent to what you can already do yourself.

Nothing here verifies what you downloaded. If you install by hand, check it against checksums.txt on the release page yourself:

Verify a manual download

sha256sum -c checksums.txt --ignore-missing

That is the one thing the script does that a manual install usually skips, and the reason it is worth preferring.

By Hand — Windows

There Is No Install Script on Windows

The installer is POSIX sh, which Windows does not have, so Windows has one step more than the other two platforms and verifies the download itself rather than having the script do it.

Take agentrqd_*_windows_*.zip from the releases page — the archive for the machine you are installing on, not the one you are reading this on — and, in PowerShell:

Windows (PowerShell)

Expand-Archive agentrqd_*_windows_*.zip -DestinationPath .
Move-Item agentrqd.exe "$env:LOCALAPPDATA\Programs\agentrqd.exe"

Windows has no user directory that is already on PATH, so add the one you installed into. It takes effect in new shells:

Put it on PATH

[Environment]::SetEnvironmentVariable("Path",
  "$env:Path;$env:LOCALAPPDATA\Programs", "User")

Nothing here verifies what you downloaded, so check the archive against checksums.txt on the release page before you unpack it. Compare the hash this prints with the line for your archive:

Verify the download

Get-FileHash agentrqd_*_windows_*.zip -Algorithm SHA256

Do Not Install or Run It as Administrator

The daemon refuses to start as Administrator, because an agent it runs would have those powers too. Install it into your own profile, as above, and run it as yourself.

Enrol It

In the control panel: Machines → Add machine gives you a short code, and shows these same steps. On the machine itself:

On the machine

agentrqd enroll --server https://your-agentrq-server --code ABCD-EFGH

There is no remote enrolment. Somebody has to be at the machine, which is what makes the code safe to display.

Run It

Start the daemon

agentrqd serve

To keep it running after you log out, use the service files. The installer saves them beside the daemon's own config — ~/.config/agentrqd on Linux, ~/Library/Application Support/agentrqd on macOS — and a manual install leaves them in the archive you unpacked.

Linux — systemd User Unit

Copy agentrqd.service into ~/.config/systemd/user/, then systemctl --user daemon-reload && systemctl --user enable --now agentrqd. Add sudo loginctl enable-linger "$USER" so it survives logout.

macOS — LaunchAgent

Copy com.agentrq.agentrqd.plist into ~/Library/LaunchAgents/, then launchctl load -w ~/Library/LaunchAgents/com.agentrq.agentrqd.plist.

Both are user-level — a systemd user unit and a LaunchAgent, not a system service and not a LaunchDaemon — for the reason above. Under either, the daemon exits and lets the service manager restart it when it updates itself; run by hand, it re-executes. Both work.

No Service File Ships for Windows

The release carries a systemd user unit and a macOS LaunchAgent, and nothing equivalent for Windows. Run agentrqd serve in a terminal you leave open; when it updates itself it re-executes in place rather than waiting for a service manager to restart it.

A Profile Is a Credential Boundary, Not an Execution Boundary

One machine can be enrolled with several AgentRQ accounts. Each is a "profile", with its own token and its own machine identity, and the panel shows them separately.

They Are Not Isolated From Each Other

All of them run as the same operating-system user, on the same filesystem, in the same home directory. Account A's agent can read the files account B's agent is working on. It can read account B's tokens if they are on disk. Nothing in the daemon prevents that, and nothing in the daemon could: they are the same user.

This is worth saying plainly because the desktop app's profiles do isolate — separate cookie jars, separate sessions — and it would be reasonable to assume these work the same way. They do not.

If You Need Real Isolation

Two accounts needing real isolation means two machines, or two operating system user accounts with their own home directories and their own copies of the daemon. Anything else is a convention, not a boundary.

What It Can Do, Exactly

The daemon runs exactly two programs, and nothing else: claude-code and acp-gateway.

It will not run a shell, and it will not run a command the server sends it. The control panel asks for a kind — one of those two names — and the daemon decides what that means from its own configuration. A backend that has been taken over cannot ask this machine to run /bin/sh, because there is no message that says "run this".

What it can do, once one of those two is running, is send it keystrokes. That is the feature. An agent at a terminal can do whatever you could do at that terminal.

Turning It Off

Revoke locally

agentrqd disable --profile <id>

This deletes that profile's token from the machine. It works without the server's cooperation and takes effect immediately: the machine can no longer authenticate, so no future connection succeeds, whatever the server thinks. It is the thing to reach for if you believe the account has been compromised.

Also remove the machine in the control panel, which revokes it server-side and closes any connection it currently holds. The two are independent on purpose — either one alone is enough to stop that machine working, and you do not need access to the panel to do the local one.

Stopping Is Not Revoking

Stopping the daemon (systemctl --user stop agentrqd, or closing the terminal it runs in) stops new work but leaves the credential on disk.

Seeing What Is Happening on Your Own Machine

Ask the machine itself

agentrqd status

It reports what is running right now: each agent, the folder it is working in, which profile asked for it, and — the part that matters most — whether anybody is attached to its terminal at this moment.

That question is answerable from the machine, by the person sitting at it, without asking the account that might be doing the watching. A machine whose owner cannot find out what is driving it is not a machine anyone should enrol.

The daemon also writes a log line when a viewer attaches to a terminal on this machine and when they leave. Under systemd: journalctl --user -u agentrqd -f.

The Audit Trail, and What Is Deliberately Not in It

Recorded on the server

An agent being started, and by whom
An agent being killed
A browser attaching to a terminal, and detaching
An update being approved, and to which version

Not recorded anywhere

Keystrokes — not on the server, not on the machine
Terminal output, which is relayed and forgotten

What somebody types into a terminal is passwords, tokens, and the contents of files; recording it would build the most sensitive log in the system to answer a question nobody asked. That an attach happened, and when, is the fact worth keeping.

Updates

The daemon checks for new releases and tells the control panel when there is one. It never updates itself on its own initiative. Somebody has to approve it, because approving means: stop every agent running on this machine, replace the daemon, and start them again.

Restored Means the Intent, Not the State

Those agents come back as new terminals. Same agent, same folder, same settings — and no scrollback, no in-flight work, nothing half-typed. The panel marks them as restored so it is clear why the terminal is empty, and there is no version of this that could mean otherwise.

Before anything is replaced, the daemon:

1 checks the release manifest's signature against a key built into it,
2 checks the downloaded file against the checksum in that manifest,
3 runs the new binary and confirms it works on this machine,
4 writes down what was running, then stops it.

A build with no release key refuses to update itself and says so; update it by hand. If an update turns out to be bad, agentrqd rollback puts the previous binary back — it is kept for exactly that reason.

Where Things Are

What	Where
Config	`~/.config/agentrqd/config.json` (`%AppData%\agentrqd` on Windows)
Tokens	one `0600` file per profile in `.../agentrqd/tokens/`
Local status	`.../agentrqd/status.json`, what `agentrqd status` reads

The config file is not a credential and can safely be copied, backed up or pasted into a bug report. The tokens directory is.

Commands

agentrqd

agentrqd enroll --server <url> --code <code> [--profile <id>]
agentrqd serve  [--profile <id>] [--verbose]
agentrqd status
agentrqd disable --profile <id>
agentrqd rollback
agentrqd version

Running Agents on Your Own Machines