---
title: Self-Hosting
summary: Run HeartBeatAgents on your own infrastructure via Docker instead of a desktop install.
date: 2026-09-03
---

# Self-Hosting

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

HeartBeatAgents' local-first design (see [Security](/en/docs/guides/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](/en/docs/getting-started/installation) and [System Requirements](/en/docs/getting-started/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](/en/docs/guides/admin-settings).
- **Always-on standing orders**: a server-hosted instance stays up for scheduled/cron-triggered [Standing Orders](/en/docs/features/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](/en/docs/features/backup-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.

## Related

- [Security](/en/docs/guides/security): the isolation guarantees that hold regardless of where you deploy
- [Advanced Configuration](/en/docs/guides/advanced-configuration): tuning behavior once your instance is up