HeartBeatAgents

Self-Hosting

View as Markdown

Run HeartBeatAgents on your own infrastructure via Docker instead of a desktop install.

HeartBeatAgents' local-first design (see Security) extends naturally to running it on your own server instead of a desktop machine: the same containerized isolation model applies either way.

Requirements

Self-hosting uses the same Docker-based deployment path as the desktop installers (see Installation and System Requirements): a Docker image, available for both x64 and arm64 Linux hosts.

Verifying what you run

Docker images are signed with cosign via GitHub OIDC, so you can verify provenance before deploying: important once HeartBeatAgents is running unattended on infrastructure you're responsible for. Every download also ships a SHA-256 checksum for the same reason.

Why self-host

  • Data residency: nothing about a self-hosted deployment sends data anywhere HeartBeatAgents itself doesn't already keep it: your machine (or your server) is "the data center."
  • Team-scale access control: a self-hosted instance behind your own network boundary lets you layer your existing infrastructure access controls on top of HeartBeatAgents' own per-agent API keys and, for a team, roles and single sign-on.
  • Always-on standing orders: a server-hosted instance stays up for scheduled/cron-triggered Standing Orders the way a laptop that sleeps overnight cannot.

Exposing it externally

If you need to reach a self-hosted instance from outside your own network, for an incoming webhook, an OAuth callback, or external API access, use a Cloudflare Tunnel rather than opening inbound ports directly: no port forwarding, no firewall changes, free.

  1. In Cloudflare, go to Zero Trust → Networking → Tunnels and create a tunnel, naming it and selecting Docker as the environment.
  2. Copy the tunnel token from the install command Cloudflare gives you: the long string after --token.
  3. Paste that token into Settings → General on your instance and start the tunnel; wait for it to report connected.
  4. Back in Cloudflare, add a Public Hostname for the tunnel: set your subdomain and domain, and point its service URL at this install.
  5. Enter the full public URL you just configured back into Settings → General to finish.

From that point on, your instance is reachable at that URL for anything that needs to reach in.

Backing it up

A self-hosted instance is the one copy of everything unless you configure otherwise. See Backups and Recovery for snapshots, off-site replication to your own bucket, and why a Recovery Kit, not just replication, is what lets a backup be restored on different hardware.