Operations basics

Run these commands on the hub machine, unless a section says otherwise.

Check health

drover-server status      # what runs, and where
drover-server doctor      # checks, with suggested fixes

Two endpoints need no credential. Use them for monitors:

Endpoint	Meaning
GET /healthz	The process is up.
GET /readyz	The hub is ready. Detail needs a credential.

If a session does not start on a host, run the diagnosis. It changes nothing. Add --json for structured output:

drover-server setup-check --host HOST --harness HARNESS --project PROJECT

Services

The installer runs the hub and the local host daemon as user services.

Platform	Units
macOS	launchd agents com.drover.server and com.drover.harnessd in ~/Library/LaunchAgents
Linux	systemd user units drover-server.service and drover-harnessd.service

To restart a service, use the tools of the platform. On Linux:

systemctl --user restart drover-server.service
systemctl --user status drover-harnessd.service

A hub restart does not stop your agents. The host daemons own the agent processes. Pairing codes that you did not use become invalid.

Hosts

drover-server hosts list
drover-server hosts retire <host-id>
drover-server hosts unretire <host-id>

Retire a host that you no longer use, then revoke its credential. The hub sends no requests to a retired host.

Credentials

drover-server pair                       # a code for a new phone
drover-server pair-host --name <name>    # a join command for a new host
drover-server credentials list
drover-server credentials revoke <credential-id>

If you lose a device, revoke its credential.

Managed PostgreSQL

If you installed with --control-store managed, a helper controls the PostgreSQL 17 container:

~/.drover/bin/drover-managed-postgres status
~/.drover/bin/drover-managed-postgres stop
~/.drover/bin/drover-managed-postgres start
~/.drover/bin/drover-managed-postgres backup /absolute/path/outside/drover/backup.dump

backup writes a PostgreSQL custom-format dump and verifies it. Keep the dump off the live volume. A volume is not a backup.

If you use your own PostgreSQL, you operate it. Give Drover a dedicated database and a dedicated role that is not a superuser.

Backups

A complete backup has these parts:

1. The control store. A PostgreSQL dump.
2. The lake, if you selected DuckLake. The catalog database and each data file that it references.
3. ~/.drover/. Configuration, credential hashes and the service environment file.

Encrypt your backups. Store them away from the hub.

Upgrades

Read the changelog before you upgrade.

drover-server update --check     # is a newer release available?
drover-server update             # install it
drover-server rollback           # go back to the previous release

Releases install side by side in ~/.drover/runtime/. To stay on one release, set pinned_version. An upgrade does not migrate a DuckDB control store to PostgreSQL.

The analytics lake

Most single-machine setups can skip this section. If you select DuckLake:

• It requires the PostgreSQL control store, a catalog database, a data root and a pinned verification proof.
• Nothing enables it automatically.
• If verification fails, analytical reads return unavailable. They do not fall back to older history.

Read the runbooks first: serving, exporter and cutover.

Housekeeping

• The hub keeps processed copies of incoming events for seven days. Set [paths] processed_retention_days to change this.
• The hub does not remove session history, context or credentials automatically.
• GET /harness/lifecycle reports idle sessions and stale worktrees. Remove worktrees yourself.

Uninstall

Run scripts/uninstall.sh from the repository. It removes the services and the drover-server link. It keeps a managed PostgreSQL container, its data and your ~/.drover/ directory.

Get help

1. Run drover-server status and drover-server doctor.
2. Open an issue with the Drover version, the platform, the expected result and the actual result.

Do not include credentials, pairing codes, private addresses, logs or session content. See the support notes.