Install the daemon

The OpenRemedy daemon (openremedy-agent) runs on each Linux server you want monitored. It heartbeats, reports evidence, and executes platform-signed health checks. This page walks through installation, registration, and day-two operations.

Supported on Debian / Ubuntu for now (.deb package). RPM-based distributions are on the roadmap; in the meantime you can run the binary directly under any init system you prefer.

1 · Get a registration token

Every daemon needs a token to identify the server it runs on.

1. In the dashboard, open Servers.
2. Click Add server, fill in hostname, IP, role, and labels, then save.
3. Open the new server's detail page, switch to the Agent tab, and click Generate token. Copy the token — it is shown only once.

Tokens are server-scoped and tenant-scoped. Treat them like an SSH key.

2 · Download and install the package

Download the latest .deb from the platform:

curl -fsSLo openremedy-agent.deb \
  https://your-platform.example.com/downloads/openremedy-agent_latest_amd64.deb

For a pinned version:

curl -fsSLo openremedy-agent.deb \
  https://your-platform.example.com/downloads/openremedy-agent_0.2.0_amd64.deb

Install:

sudo dpkg -i openremedy-agent.deb

The post-install script:

• Creates a system user openremedy-agent.
• Installs the systemd unit at /lib/systemd/system/openremedy-agent.service.
• Drops a starter config at /etc/openremedy-agent/config.json.example.
• Configures limited passwordless sudo for remediation actions (service management, package management, log access — see /etc/sudoers.d/openremedy-agent).
• Creates an SSH directory at /var/lib/openremedy-agent/.ssh/ for remote Ansible execution.

Architectures: amd64 and arm64 builds are published. Pick the filename matching your CPU — dpkg --print-architecture will tell you.

3 · Configure the daemon

Copy the example config and fill in the platform URL and token:

sudo cp /etc/openremedy-agent/config.json.example \
        /etc/openremedy-agent/config.json
sudo nano /etc/openremedy-agent/config.json

Minimal config:

{
  "platform_url": "https://your-platform.example.com",
  "token": "orem_srv_PASTE_YOUR_REGISTRATION_TOKEN_HERE",
  "log_level": "info",
  "heartbeat_interval_seconds": 30,
  "report_interval_seconds": 60
}

The config file is owned by openremedy-agent:openremedy-agent with mode 0600 — keep it that way. The daemon refuses to start with a world-readable token file.

Bootstrap with one command

The packaged CLI can write a starter config for you:

sudo openremedy-agent --init \
  --platform-url https://your-platform.example.com \
  --token orem_srv_YOUR_TOKEN

4 · Start the daemon

sudo systemctl enable --now openremedy-agent
sudo systemctl status openremedy-agent

The daemon will register with the platform, fetch its initial monitor configuration, and begin heartbeating. Within ~15 seconds you should see the server's status dot pulse green on the Servers page.

Logs:

journalctl -u openremedy-agent -f

5 · (Optional) Allow remote remediation over SSH

If you want OpenRemedy to run remediation playbooks against this server, add the platform's SSH public key to the daemon's authorized_keys:

echo "ssh-ed25519 AAAA... openremedy@platform" \
  | sudo tee -a /var/lib/openremedy-agent/.ssh/authorized_keys
sudo chown openremedy-agent: /var/lib/openremedy-agent/.ssh/authorized_keys
sudo chmod 600 /var/lib/openremedy-agent/.ssh/authorized_keys

The platform's public key is shown in the dashboard under Settings → Servers → SSH key. The same key is reused across every server in the tenant.

Without this step, the daemon still reports evidence and runs locally-scheduled checks — but the platform cannot push remediation actions through SSH.

6 · Verify

Back on the dashboard, the server's Agent tab should now show:

• Status: online.
• Last heartbeat: a few seconds ago, ticking.
• Agent version: matches the .deb you installed.

The daemon's local logs confirm everything is happy:

[openremedy-agent] v0.2.0 starting...
[openremedy-agent] platform: https://your-platform.example.com
[openremedy-agent] config: /etc/openremedy-agent/config.json
[openremedy-agent] already registered: server_id=...
[openremedy-agent] loaded initial tasks: 5 monitors
[openremedy-agent] running (heartbeat: 15s, report: 15s)

Upgrade

To install a newer release, repeat step 2 with the new version. The post-install script preserves your config.json and existing token. The systemd service restarts automatically.

curl -fsSLo openremedy-agent.deb \
  https://your-platform.example.com/downloads/openremedy-agent_0.3.0_amd64.deb
sudo dpkg -i openremedy-agent.deb
sudo systemctl restart openremedy-agent

Worth upgrading promptly when a release ships security fixes. Older daemon binaries silently ignore newer protections (e.g. the HMAC-signed monitor command verification introduced in v0.2.0) and remain at their previous risk level until updated.

Uninstall

sudo systemctl stop openremedy-agent
sudo apt-get remove openremedy-agent     # keeps /etc/openremedy-agent/
sudo apt-get purge openremedy-agent      # also removes config + state

After uninstall, mark the server as deactivated in the dashboard (or delete it) so the platform stops scheduling checks for it.

Troubleshooting

Run without the .deb (manual)

The daemon is a single static Go binary. If you do not want to use the package:

sudo curl -fsSLo /usr/local/bin/openremedy-agent \
  https://your-platform.example.com/downloads/openremedy-agent-0.2.0-linux-amd64
sudo chmod +x /usr/local/bin/openremedy-agent
sudo useradd --system --create-home --home-dir /var/lib/openremedy-agent openremedy-agent
sudo mkdir -p /etc/openremedy-agent
sudo openremedy-agent --init \
  --platform-url https://your-platform.example.com \
  --token orem_srv_YOUR_TOKEN

Then write your own systemd unit, supervisord rule, or runit script that runs /usr/local/bin/openremedy-agent --config /etc/openremedy-agent/config.json as user openremedy-agent.