o10r

Install

Install the agent in standalone mode.

The agent runs as a single bundled binary plus a colocated MCP server. Drop it in a devcontainer, on a NAS, or wrap it in a systemd unit.

Prerequisites

You don't need a registration token to download the agent — it's a public binary. The token comes in during the pairing step below, so you can grab the binary first and decide which hub to register it against later.

1. Download

Paste this into the devcontainer or host. The bootstrap script downloads the latest linux tarball, verifies its sha256, and extracts it to ~/.o10r/agent/ by default.

bash
curl -fsSL https://o10r.edwardsalter.me.uk/hub/install.sh | sh

Override the install destination with O10R_INSTALL_DIR=/opt/o10r/agent if you want a system-wide install. The download itself is anonymous; nothing sensitive is exchanged at this step.

2. Pair with the hub

Mint a registration token at https://o10r.edwardsalter.me.uk/hub/agents/new (sign in to the hub first), then run the agent's interactive --register flow. It stores hub URL, token, and your preferred agent name in <dataDir>/settings.json:

bash
~/.o10r/agent/o10r-agent --register

The prompts walk you through hub URL, registration token (paste from the hub UI), and an optional friendly name. For scripted / non-interactive setups, pass everything as flags:

bash
~/.o10r/agent/o10r-agent --register \
  --hub-url https://o10r.edwardsalter.me.uk/hub \
  --hub-token <paste-token> \
  --agent-name "devcontainer-$(hostname)" \
  --workspace-roots /workspaces \
  --permission-mode acceptEdits

Pass --hub-token - to read the token from stdin so it never appears in ps or shell history. --force overwrites an existing registration without prompting.

3. Start the agent

bash
~/.o10r/agent/o10r-agent

On first launch the agent generates a stable identity at <dataDir>/agent-id, reads the credentials from settings.json, and dials out to /ws/agent on the hub. You should see it appear in the hub's agents dashboard within a few seconds. To override at start without re-registering, set HUB_URL / AGENT_TOKEN / AGENT_NAME in the environment — env always wins over persisted settings.

Configuration

After --register the agent has everything it needs in settings.json. Environment variables let you override values at start time without re-registering — useful for containers that pull config from a secret store.

Hub overrides

Runtime

Running as a systemd unit

For a host you want o10r on permanently, drop a unit at /etc/systemd/system/o10r-agent.service:

/etc/systemd/system/o10r-agent.serviceini
[Unit]
Description=o10r agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=o10r
Group=o10r
Environment=DATA_DIR=/var/lib/o10r-agent
# Hub credentials are persisted in $DATA_DIR/settings.json (set up once via
# 'o10r-agent --register' as the o10r user). Override here with HUB_URL /
# AGENT_TOKEN if you'd rather inject them via EnvironmentFile= from a
# secrets manager — env always wins over persisted settings.
ExecStart=/opt/o10r/agent/o10r-agent
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

The systemd service runs the bundle directly — the supervisor wrapper isn't necessary because systemd is doing the same job. If an update is staged, the agent exits with code 75 and systemd respawns; the new binary picks up the staged tarball on next start.

Upgrading

The agent checks the hub every 6 hours and stages new versions automatically. Restarts happen when sessions drain. To upgrade right now without opening the hub UI:

bash
o10r-agent upgrade              # check + stage + signal restart on idle
o10r-agent upgrade --check      # report status only (exit 2 if available)
o10r-agent upgrade --force      # stage + restart immediately (kills sessions)

From the hub UI: https://o10r.edwardsalter.me.uk/hub/admin/agents lists every connected agent with its version and an Update button. Bundled desktop installs appear too, but their button is disabled — the desktop auto-updater owns those.

Uninstalling

bash
# stop the agent (or 'systemctl stop o10r-agent' if running as a service)
pkill -f o10r-agent

# remove the install
rm -rf ~/.o10r/agent

# optional: drop the data dir too (sessions, settings, registration)
rm -rf ~/.o10r/data

Troubleshooting

"No HUB_URL/AGENT_TOKEN, no --port/--token, and --standalone not set"

The agent has nothing to do. Either pass the env vars above, run with --register first, or pass --standalone to keep it alive waiting for a future hub connection.

Agent shows offline in the hub but the process is running

Check that HUB_URL matches what you have in the hub config — the agent only accepts release tarballs from the same origin it's registered against, so a mismatch surfaces as quietly-not-working. Check the agent's stderr for WebSocket connection errors.

Updates not appearing

Confirm the hub has tarballs in its O10R_RELEASES_DIR — see the self-host page for the full layout. The releases watcher scans every 60 seconds; kill -HUP <hub-pid> forces an immediate rescan.