Installation

The one-liner

curl -fsSL https://agentarivm.com/install.sh | sh

This is the recommended path on both macOS and Linux. It detects the platform and architecture, downloads the matching tarball, verifies it, and installs the agentarivm command. It is idempotent — safe to re-run for upgrades — and it never overwrites an existing configuration.

Manual installation

Grab the tarball for your platform from the download page:

https://dl.agentarivm.com/releases/latest/agentarivm-<platform>-<arch>.tar.gz

where <platform> is darwin or linux and <arch> is arm64 or x64. Each tarball has a .sha256 checksum file next to it; verify before unpacking:

curl -fsSLO https://dl.agentarivm.com/releases/latest/agentarivm-linux-x64.tar.gz
curl -fsSLO https://dl.agentarivm.com/releases/latest/agentarivm-linux-x64.tar.gz.sha256
sha256sum -c agentarivm-linux-x64.tar.gz.sha256   # shasum -a 256 -c on macOS
tar -xzf agentarivm-linux-x64.tar.gz

Put the agentarivm command somewhere on your PATH, then run agentarivm init to write a starter configuration and agentarivm doctor to check the machine. init comes first: every other command validates the configuration at boot, so until that file exists there is nothing to run.

Prerequisites the installer does not install

The manager orchestrates tools you must set up yourself, because each involves an account or a credential:

• gh — authenticate with gh auth login as the account the manager should act as. Everything the manager does on GitHub happens under this identity. Pin it in the config (github.expectedAccount) so a wrong login is refused at boot rather than silently doing everything under the wrong name.

• Claude Code — the agents need a subscription credential. Generate one with claude setup-token and install it with agentarivm agent-token install (it reads the token from stdin only, never from an argument, so it never lands in shell history):

  claude setup-token
  pbpaste | agentarivm agent-token install

  It refuses an sk-ant-api… API key on purpose: an API key bills pay-as-you-go credits and outranks the subscription token in Claude Code’s precedence, so installing one is worse than installing nothing. The manager runs one claude process per task and talks to it over pipes. agentarivm init writes agent.claudeExecutable as an absolute path resolved from your own PATH; keep it absolute, because a daemon’s PATH will not find a bare name.

Running as a service

A manager that only runs while a terminal is open is not a manager. agentarivm service generates and loads the right unit for the platform:

agentarivm service install     # write the service definition and (re)load it
agentarivm service status      # loaded? running? what was the last exit?
agentarivm service uninstall   # unload it and remove the definition

service install --dry-run prints the definition and touches nothing.

macOS: launchd

service install writes a LaunchAgent at ~/Library/LaunchAgents/com.agentarivm.manager.plist and loads it. The job is KeepAlive — launchd restarts the manager if it crashes — and RunAtLoad, so it starts when the user logs in.

Two macOS realities worth knowing up front:

• A LaunchAgent needs its user logged in. After a reboot with FileVault on, nothing runs until the disk is unlocked and the user logs in. For a machine that reboots rarely, this is fine; the alternatives (a LaunchDaemon, or disabling FileVault) trade away either simplicity or disk encryption.
• launchd gives jobs a minimal PATH. This is the single most common deployment failure — see Troubleshooting.

Linux: systemd user units

On Linux, service install manages a systemd user unit — the manager runs as your user, not as root, matching the security model. The usual commands apply:

systemctl --user status agentarivm
journalctl --user -u agentarivm

By default, systemd user units only run while that user has a session. On a headless box where nobody logs in, enable lingering once:

sudo loginctl enable-linger <user>

With lingering on, the user’s units start at boot and keep running with no login — which is exactly what an always-on manager wants.

Upgrading

Re-run the installer. It replaces the binary, leaves your configuration alone, and service install reloads the service against the new version. Run agentarivm doctor afterwards; it is cheap and it catches drift.