Agent Relay supports always-on Macs and Linux servers without the desktop app
or a desktop window. The machine appears in an existing Cloud workspace and can
accept Claude Code or Codex spawns. Linux runs the account-aware core as the
agent-relay.service systemd user service. macOS runs the same core as a
per-user LaunchAgent. Setup signs in by device approval in a browser on any
computer, or, for an unattended install, with an enrollment key an
administrator minted; you do not copy a workspace key or forward a port over
SSH.
Choose the right setup path
| Path | What it does |
|---|---|
macOS headless installer + agent-relay-probe setup | Installs the production core for the current user, runs it as com.agentrelay.desktop.core.headless, and signs the Mac into an existing Cloud workspace by device approval or an enrollment key. No desktop app or administrator access is required. |
Linux Agent Relay package + agent-relay-probe relay setup | Signs this machine into an existing Cloud workspace by device approval or an enrollment key and runs the account-aware systemd service. |
npm CLI agent-relay cloud login + cloud enroll | Saves a separate CLI login and fleet enrollment record. A returned node ID does not start a service or prove a live spawn target. |
npm CLI agent-relay init --hosted | Can create a new hosted messaging workspace. It does not select your Desktop workspace just because both use the same account or the name “Default”. |
agent-relay-node serve --headless | Runs the standalone messaging core. It reads CLI workspace configuration and has no Cloud account sign-in plugin; it does not consume the Cloud fleet enrollment as an account login. |
In v18, relay node up and relay fleet status were removed with the local
broker. The older v18.0.0 enrollment output still recommends node up; that
is stale advice, corrected in newer CLI builds.
Do not use it as the next step, repeat enrollment, or create another workspace
to make the existing machine appear.
1. Install the background service
macOS without the app
This supported path is for a Mac that runs agents without Agent Relay.app,
such as a Mac mini in a rack. It supports Apple silicon and Intel Macs and
installs the production Agent Relay build only. A private site's branded or
Cloud-feed build is not supported by this installer yet.
Run the release installer as the macOS user who owns the agents, not as root:
curl -fsSL https://github.com/AgentWorkforce/relay-desktop-releases/releases/latest/download/install-macos.sh | bashTo review and run the source installer directly instead, use the public source checkout:
git clone --depth 1 https://github.com/AgentWorkforce/relay-app.git
cd relay-app
bash macos/install.shThe installer downloads the latest production probe for the Mac's architecture,
checks its published SHA-256 and Developer ID signature, and installs it under
~/.local/lib/agent-relay. It writes
~/Library/LaunchAgents/com.agentrelay.desktop.core.headless.plist, starts it in
the user's gui/<uid> login session, and waits for the new core to answer. An
update that fails its health check rolls back automatically. Settings, sign-in,
and agent registrations are kept outside the install directory.
The published installer also handles lifecycle operations:
curl -fsSL https://github.com/AgentWorkforce/relay-desktop-releases/releases/latest/download/install-macos.sh | bash -s -- --status
curl -fsSL https://github.com/AgentWorkforce/relay-desktop-releases/releases/latest/download/install-macos.sh | bash -s -- --update
curl -fsSL https://github.com/AgentWorkforce/relay-desktop-releases/releases/latest/download/install-macos.sh | bash -s -- --rollback
curl -fsSL https://github.com/AgentWorkforce/relay-desktop-releases/releases/latest/download/install-macos.sh | bash -s -- --uninstallInstall, update, rollback, and uninstall take an installer lock so two lifecycle
operations cannot change the same per-user install at once. --uninstall stops
and removes the core and LaunchAgent but keeps settings, sign-in, and agents.
The installer refuses to run beside the desktop app; uninstall the headless core
before installing Agent Relay.app.
The LaunchAgent needs a real macOS login session. SSH by itself does not create
one, so the installer refuses if gui/<uid> is absent. For an unattended Mac,
turn on automatic login under System Settings → Users & Groups. FileVault
must be off because macOS blocks automatic login while FileVault is on. Without
automatic login, the core does not start after a reboot until that user logs in
at the Mac; SSH alone does not start the LaunchAgent. Keychain-backed sources
also remain unavailable until login unlocks the user's Keychain.
macOS privacy (TCC) and Keychain approval dialogs cannot be answered over SSH or by the headless installer. Grant required Files and Folders or Keychain access from the Mac's GUI before leaving it unattended. A source that still needs an approval remains unavailable until someone can answer at the Mac; other session sources continue to run.
Finish setup with the command printed by the installer. If the installed
LaunchAgent exists but the core is stopped, --start-service can load and start
that existing service; it does not install or update it:
~/.local/lib/agent-relay/current/agent-relay-probe setup --start-serviceApprove the displayed device code in a browser on any computer, or sign in unattended with an enrollment key instead.
Linux
Run as the non-root Linux user who will run Claude Code and Codex. You need
curl, ca-certificates, and sudo access for the package installation and
lingering. On Ubuntu 24.04, use the .deb for your architecture. Download its
published checksum alongside it, and stop if verification fails. The script
uses the latest stable release; its checksum verifies download integrity. If
a release changes between the two downloads, rerun both. To repeat the verified
2026.11.3 release, set relay_release to
https://github.com/AgentWorkforce/relay-desktop-releases/releases/download/v2026.11.3
in place of the latest/download URL below.
case "$(uname -m)" in
x86_64|amd64) relay_arch=x64 ;;
aarch64|arm64) relay_arch=arm64 ;;
*) printf 'Unsupported Linux architecture\n' >&2; exit 2 ;;
esac
relay_tmp=$(mktemp -d)
chmod 700 "$relay_tmp"
relay_release=https://github.com/AgentWorkforce/relay-desktop-releases/releases/latest/download
curl -fL "$relay_release/AgentRelay-Linux-$relay_arch.deb" -o "$relay_tmp/AgentRelay-Linux-$relay_arch.deb" &&
curl -fL "$relay_release/AgentRelay-Linux-$relay_arch.deb.sha256" -o "$relay_tmp/AgentRelay-Linux-$relay_arch.deb.sha256" &&
(cd "$relay_tmp" && sha256sum --check "AgentRelay-Linux-$relay_arch.deb.sha256") &&
sudo apt-get install -y "$relay_tmp/AgentRelay-Linux-$relay_arch.deb"Continue only after a successful install:
sudo loginctl enable-linger "$USER"
systemctl --user daemon-reload
systemctl --user enable agent-relay.service
systemctl --user restart agent-relay.service
systemctl --user is-active agent-relay.service
loginctl show-user "$USER" -p LingerRestarting loads the newly installed build even when an older service was
already active. Expect active and Linger=yes. Lingering keeps the user's service running
after SSH logout and starts it at boot. A user-bus error means the systemd user
session needs fixing; running the service as root would use a different home
and provider credentials.
The .deb installs GTK runtime dependencies even when no window is used.
For a minimal server, the release also offers a separate GTK-free probe archive
and headless installer; the commands here use the Debian-managed package.
2. Sign into the exact existing workspace
Use the Cloud workspace UUID for the existing workspace this machine should
join. Names such as “Default” are not enough to establish that two machines
share a workspace.
An existing npm CLI login can list accessible IDs with
agent-relay cloud workspaces; confirm the intended workspace with its owner.
That command's login is separate from the headless service's login.
Sign in by device approval, as below, or, for an unattended install, with an enrollment key. Device approval is the default.
On macOS, use the per-user helper installed above:
~/.local/lib/agent-relay/current/agent-relay-probe setup --workspace YOUR-CLOUD-WORKSPACE-UUIDLinux stable 2026.11.3 uses the relay setup terminal wizard to sign in
without copying a key:
test -x /usr/lib/agent-relay/agent-relay-probe || {
printf 'Agent Relay helper missing; check the Linux package installation.\n' >&2
exit 1
}
/usr/lib/agent-relay/agent-relay-probe relay setup --workspace YOUR-CLOUD-WORKSPACE-UUIDReplace the placeholder with the intended Cloud workspace UUID. Open the wizard's verification URL on another computer or phone, approve its displayed device code using the account with access to that workspace, then return to the SSH terminal. Keep an existing sign-in only if it is for the intended workspace. Choose providers and session sharing in the wizard; omitted options preserve saved preferences. A fresh connection defaults to Only sessions I choose. Sharing a session uploads it so teammates can read it; choose broader sharing only when you want it.
Newer builds may list setup and call directly in the probe’s --help;
on those builds omit relay from the probe commands in this guide. If neither
form is available, update the Linux package from the download page.
agent-relay-probe is the account-aware package helper. It is different from
agent-relay-node, and from the separately installed npm agent-relay CLI.
The stable 2026.11.3 .deb installs the helper at the path above and the
app launcher as /usr/bin/agent-relay-desktop. Older packages used the CLI’s
agent-relay name for that launcher; use the full probe path to avoid confusion.
Sign in with an enrollment key
For an unattended install, an administrator mints a single-use, per-employee
enrollment key in Agent Relay. Setup exchanges it for a sign-in with no browser
and no device approval. Use a build whose setup --help output lists
--enrollment-key-file. The feature landed after 2026.11.10-beta.1; that beta
and stable 2026.11.9 do not include it. Use device approval on older builds.
Put only the key in a file and pass its path. Prefer this form for an unattended
installer. Pass - to read from standard input only when an existing secret
source needs to supply the key without putting it in a command argument. On
macOS:
~/.local/lib/agent-relay/current/agent-relay-probe setup --non-interactive --json --workspace YOUR-CLOUD-WORKSPACE-UUID --enrollment-key-file /path/to/key --providers detected --sharing selected
~/.local/lib/agent-relay/current/agent-relay-probe setup --non-interactive --json --workspace YOUR-CLOUD-WORKSPACE-UUID --enrollment-key-file - --providers detected --sharing selected < /path/to/keyOn Linux:
/usr/lib/agent-relay/agent-relay-probe setup --non-interactive --json --workspace YOUR-CLOUD-WORKSPACE-UUID --enrollment-key-file /path/to/key --providers detected --sharing selected
/usr/lib/agent-relay/agent-relay-probe setup --non-interactive --json --workspace YOUR-CLOUD-WORKSPACE-UUID --enrollment-key-file - --providers detected --sharing selected < /path/to/keyThe file holds only the key. It must be owned by you with mode 0600
(chmod 600) and must not be a symbolic link. The key never goes on a command
line, in output, or in logs. The core reads the file itself and deletes it once
Agent Relay accepts the key, because a key signs in only once. If Agent Relay
does not accept the key, the file is kept. A file replaced after the core reads
it is also left alone.
With -, setup copies standard input to a private temporary file (mode 0600)
and removes that copy when setup returns normally; it does not remove the
original input source. If setup is interrupted or killed while it waits, an
owner-only agent-relay-enrollment-* temporary file can remain and can still
hold an unspent key. Before retrying, securely inspect and remove such a file
after confirming that no setup process is using it.
Setup waits, within --timeout and with or without --wait, until the key has
signed in and the workspace is connected, or the sign-in fails. Setup reports
one of these enrollment-key outcomes:
| Outcome | Meaning |
|---|---|
enrollment_key_rejected | Agent Relay did not accept the key. The message is the same whether the key was wrong, expired, revoked, or already used; ask the administrator for a new one. |
enrollment_key_busy | Agent Relay stayed busy after a few retries. Rerun setup with the same key. |
enrollment_key_unsupported | The site does not offer enrollment keys. Setup falls back to the device code: it prints the device instructions and exits with status 2 without waiting, even with --wait. Rerun setup with --wait to wait for the approval. |
enrollment_key_unused | The computer is already signed in or another sign-in is under way; the key is ignored. |
Device approval stays the default. A computer whose session expired or was revoked renews it by device approval, and a site that does not offer enrollment keys falls back to device approval. After sign-in the machine keeps its session, so the core and its agents come back on the relay by themselves after a restart.
An agent driving setup through the core's session socket uses
account.sign_in with flow: "enrollment_key"; the POST /setup/sign-in
route does not take enrollment keys.
3. Verify spawning separately from sign-in
Install and authenticate Claude Code and Codex for the same OS user running the service. The service must be able to find their executables; a working interactive shell alone does not prove the background service has the same PATH.
For Relay’s 2026.11.3 integration, Codex also needs its app-server daemon: a
managed daemon package, its standalone install, or an existing control socket.
An older Codex installed only through npm or a version manager such as mise
can lack these and be missing from spawn targets. The diagnostic begins
“Codex here cannot start its app-server daemon”. If that is the cause, use the official Codex standalone installer
for this Linux user. This is Relay’s version-specific discovery requirement;
npm remains a supported general Codex CLI installation method.
Spawning is on by default unless explicitly disabled. Check Accept spawns
from Agent Relay under Settings → Messages → Spawned agents if it was
turned off. Existing settings are preserved. The core setting is
accept_spawns; an agent can inspect it through the probe's settings.get
bridge call rather than requiring a desktop window. Workspace owners/admins
spawning on a teammate's machine also require that machine's teammate-spawn
opt-in (spawn_allow_teammates).
Read the local settings and spawn status without starting a model.
On macOS:
~/.local/lib/agent-relay/current/agent-relay-probe relay call settings.get --json
~/.local/lib/agent-relay/current/agent-relay-probe relay call status.get --jsonOn Linux stable 2026.11.3:
/usr/lib/agent-relay/agent-relay-probe relay call settings.get --json
/usr/lib/agent-relay/agent-relay-probe relay call status.get --jsonFrom an authenticated Agent Relay session in that same workspace, refresh the
available spawn targets. Confirm this server offers claude and/or codex.
The core's spawn status reports state: live, node_name, and harnesses;
error, claim, and plan_limit explain why a machine cannot be offered.
The machine name comes from the running service, and need not match a previous
cloud enroll --name record.
Once the owner authorizes a test agent run, spawn a small task on the explicit server target and confirm its response. Enrollment success, service liveness, and a queued message receipt alone do not establish that a provider can run. Do not start paid model work just to diagnose connectivity without approval.
If the server still does not appear
- Confirm the headless machine and other clients use the same workspace UUID and account.
- On macOS, run the published installer with
--status, inspectlaunchctl print "gui/$(id -u)/com.agentrelay.desktop.core.headless", and check~/Library/Logs/Agent Relay. - On Linux, check
systemctl --user is-active agent-relay.serviceandLinger=yes. - Check provider installation, authentication, and the service's executable PATH.
- Inspect the spawn status for disabled spawning, connection errors, ownership, or device limits before trying another enrollment.
- Report the platform, core or package version, architecture, service state, and redacted spawn status to support. Do not paste credentials or raw logs.
Where is the workspace key for Default?
This Cloud setup does not require finding, exporting, or pasting an ar_ws_…
workspace key. Device approval or an enrollment key authorizes the
account-aware service for the selected workspace. A workspace ID or enrolled
node ID is not a workspace key.
relay init --key is a separate messaging-workspace join path for someone who
already holds that credential; it is not a way to retrieve Desktop's login.
If you require a server running only the npm CLI and standalone node, without the account-aware package or headless core, the v18 enrollment sequence above is not a complete key-free path to an existing Desktop workspace. Report that requirement to support rather than inventing a key-export step.