All docs
The agent
Agent configuration
The agent needs no configuration to work. The installer writes one file, /etc/infrapilot/config, and the agent reads everything from it. This page lists every value it understands, what the default is, and what to run after you change one.
The config file
The installer writes /etc/infrapilot/config (root-only, mode 0600, because it holds the secret key) and a systemd unit called infrapilot-agent that loads it as an environment file. A fresh install looks like this:
OPSERVO_API_URL=https://api.getopservo.com
OPSERVO_AGENT_ID=<assigned at registration>
OPSERVO_SECRET_KEY=<assigned at registration>
OPSERVO_BUFFER_PATH=/var/lib/infrapilot/agent-buffer.db
OPSERVO_ENABLE_PROBES=false
OPSERVO_ENABLE_SHELL=false
OPSERVO_MACHINE_ID=<instance id or machine-id>Re-running the installer keeps the agent ID and secret key and keeps OPSERVO_ENABLE_PROBES=true and OPSERVO_ENABLE_SHELL=true if you had set them. Set OPSERVO_FORCE=1 on the install command to register the server as a new one instead.
Every setting
Each value can be set in the config file or passed as a flag when you run the binary by hand. Legacy INFRAPILOT_* names are still read as a fallback, so an old install keeps working.
| Setting | Flag | Default | What it does |
|---|---|---|---|
OPSERVO_API_URL | --api-url | https://api.getopservo.com | Where heartbeats go. Must be https:// unless it is localhost. |
OPSERVO_AGENT_ID | --agent-id | empty | This server’s identity. Empty means the agent registers itself on start. |
OPSERVO_SECRET_KEY | — | empty | Signs every heartbeat (HMAC-SHA256). Assigned at registration. Keep it in the config file: the old --secret-key flag still works but shows the key to every user in ps, and the agent warns when it is used. |
OPSERVO_BUFFER_PATH | --buffer-path | /var/lib/infrapilot/agent-buffer.db (installer) | Local SQLite file for log cursors and the offline heartbeat queue. |
OPSERVO_AUTO_UPDATE | --auto-update | true | Set false to stop the hourly self-update. See Auto-update and signing. |
OPSERVO_ENABLE_ACTIONS | --enable-actions | true | Whether the agent polls for dashboard commands at all. Commands only run on servers you switch on in the dashboard; set false as a local kill-switch. See Remote actions. |
OPSERVO_ENABLE_SHELL | --enable-shell | false | Allow the live terminal on this server. It also has to be switched on in the dashboard. Set it over SSH: Opservo blocks remote commands that edit this file. OPSERVO_ENABLE_ACTIONS=false blocks it too. |
OPSERVO_ENABLE_PROBES | --enable-probes | false | Opt in to running TCP uptime checks from this server. See Agent-based uptime probes. |
OPSERVO_MACHINE_ID | — | written by the installer | The identity recorded at install time, used to detect a cloned image. See Auto Scaling groups. |
OPSERVO_ENROLL_KEY | — | empty | A reusable fleet_ key. Only written when you install with one; lets a clone register itself as a new server. |
OPSERVO_CONFIG_PATH | — | /etc/infrapilot/config | Where the agent rewrites its identity after a clone re-registers. Rarely needed. |
| — | --interval | 60s | Heartbeat interval. Not exposed in the config file. |
| — | --dev | off | Verbose logging and no self-update. TLS verification is skipped only when the API URL is localhost; against any other API it stays on. For local development only. |
The flags --update-interval (1 h) and --action-interval (5 s) also exist for the self-update check and the command poll. You should not need to change them.
OPSERVO_CLUSTER_NAME is read by the separate Kubernetes agent, not the Linux agent. See Kubernetes clusters.
Heartbeats and the offline buffer
The agent collects everything and sends one signed heartbeat every 60 seconds over outbound HTTPS. It opens no ports and never waits for the dashboard to connect in.
If the API cannot be reached, the agent keeps running. Each failed heartbeat is stored in the SQLite buffer at OPSERVO_BUFFER_PATH, up to the 15 most recent. When the connection returns, the agent sends the current heartbeat first and then replays the buffered ones oldest-first, so the last few minutes before an outage are not lost. If the buffer file itself cannot be opened, the agent still runs; it only loses log de-duplication across restarts.
Optional files for database monitoring
The agent never reads your application’s .env or any other credentials on disk. When it needs a database login, it uses a file you create for it:
- •
/etc/infrapilot/mysql.cnf— a MySQL[client]option file with a read-only monitoring user. Without it the agent tries local socket authentication only. - •
/etc/infrapilot/pg.conf— a single libpq connection URI for PostgreSQL, for example a read-only role on a private RDS instance reachable from this server. Without it the agent monitors only a local server (as thepostgresOS user) and Postgres containers.
Logs, restart, status
sudo systemctl status infrapilot-agent
sudo journalctl -u infrapilot-agent -f
sudo journalctl -u infrapilot-agent -n 50After changing any value in /etc/infrapilot/config, restart the service. The change takes effect on the next heartbeat.
sudo systemctl restart infrapilot-agentLast updated 2026-10-14. Found a mistake? Email hello@getopservo.com.