Docs / Install and enroll

Install and enroll

Install SafeGrd on a host that can already reach what you want to back up. It compresses and encrypts each backup there, so only encrypted data leaves the machine.

Setup has two parts. The first runs on the host and generates your keypair. The second is optional: it registers the host with SafeGrd so the console can track it.

Install the binary

# macOS and Linux, amd64 and arm64
curl -fsSL https://safegrd.dev/install.sh | sh
# the host is listed under its hostname; to choose the name:
curl -fsSL https://safegrd.dev/install.sh | SAFEGRD_NODE_NAME=web-01 sh

The installer detects your platform, downloads the matching release and checks it against the release's checksums.txt. It puts safegrd in /usr/local/bin, or in ~/.local/bin when it cannot use sudo. To read the script before you run it, fetch the script itself. It is the same file as install.sh in the CLI repository, and a test fails the build if the two ever differ.

The console's setup wizard (Add surface) prints the same command with the project you picked already filled in. You do not need a flag to put the host in that project.

What it asks in a terminal

In a terminal, the installer offers to connect the host straight away. One command takes you from nothing to an enrolled host:

  1. You log in from a browser. The installer prints a code and a link. Open the link in a browser on any device, check that it shows the same code, and approve. The page shows the address the login came from, so you can tell it is yours. It asks for your password only if you signed in to the console more than 30 minutes ago. On a server you reached over SSH or PuTTY, use the browser on your laptop. The CLI does not try to open one on the server.
  2. The installer enrolls the host: it generates the keypair and registers the host. SafeGrd keeps the private key sealed unless you set SAFEGRD_KEY_CUSTODY=local or chose that for this host in the console's setup (below).

The install ends with the next steps that enroll prints for this host:

Nothing backs up on a schedule until the daemon runs. If the host has nothing to protect yet, enroll first tells you how to name it: click Add surface on the host's row under Hosts, then run safegrd claim. The console's setup shows the same steps.

Without a terminal (CI, cloud-init, a cron job), the installer installs the binary and stops. If you run it again on a host that is already enrolled, it upgrades the binary and changes nothing else. To add surfaces to that host, name them in the console with Add surface on its row under Hosts, then run safegrd claim on the host (details).

The installer keeps each release in /usr/local/lib/safegrd/versions (~/.local/lib/safegrd without sudo) and points /usr/local/bin/safegrd at the one in use. This is how you can update the host from the console and go back to the release it ran before (updates from the console). If you set SAFEGRD_INSTALL_DIR, the binary there is a plain copy. The console cannot update it unless you also set SAFEGRD_LIB_DIR.

Options

Options are environment variables. Put them before the sh after the pipe: curl -fsSL https://safegrd.dev/install.sh | VERSION=v0.0.3 sh. If you put one before curl, it is set for curl and the script never sees it.

VariableEffect
VERSIONRelease tag to install. Default: the latest release.
SAFEGRD_INSTALL_DIRWhere the binary goes.
SAFEGRD_LIB_DIRWith SAFEGRD_INSTALL_DIR: where each release is kept. The binary in SAFEGRD_INSTALL_DIR links to it, and the console can update the host.
SAFEGRD_NO_SETUP=1Install only, without the offer to log in and enroll. Use it on a machine you are restoring to.
SAFEGRD_FORCE_INSTALL=1Download and install even if that release is already installed. Without it, a host that already has the release goes straight to setup.
SAFEGRD_PROJECTProject ID or slug to enroll this host into.
SAFEGRD_NODE_NAMEThe name the console shows for this host. Default: the machine's hostname, without its domain.
SAFEGRD_KEY_CUSTODYlocal keeps this host's key on the host (a customer-managed key). Without it, SafeGrd keeps the key sealed.
SAFEGRD_CLAIMThe claim code the console shows for this host. The host enrolls into that project, with the storage and surfaces you chose there.
SAFEGRD_TOKENA token from Tokens in the console (sg_pat_…). The host enrolls without a terminal or a browser login. Use it for CI, cloud-init or ssh host 'curl … | sh'.

There is no Windows build. The daemon runs on Linux and macOS. On a Windows host, run it in the Docker image.

Other ways to install

# Homebrew, macOS and Linux: the same release archives
brew install safegrd/tap/safegrd
# Go
go install github.com/safegrd/cli/cmd/safegrd@latest
# Docker: the daemon as a sidecar, with its config and key in a volume
docker run --rm -it -v safegrd:/home/safegrd/.safegrd ghcr.io/safegrd/cli enroll

The Docker image includes pg_dump 18, the MariaDB client, the MongoDB tools and a PostgreSQL 18 server. With that server, a drill can restore a database into a throwaway cluster on the volume. The container runs as its own user. To run it beside a database, use compose.yaml. To run it on Kubernetes, use the Helm chart, which copies the config and key from a Secret into an in-memory volume. Where to run it has the steps for each.

If you have no server, the GitHub Action backs up from a scheduled workflow and drills into a database it creates on the runner. Back up Supabase with GitHub Actions walks through it.

If your plan includes it, SafeGrd can also take the backup itself. Open Back up on SafeGrd under Surfaces in the console and give it the connection string, or a bucket's S3 key for Supabase Storage. A machine SafeGrd starts for each backup does the rest (how).

None of these enrolls the host for you. After installing, run safegrd login and then safegrd enroll.

At run time, a database surface needs its engine's client tools on the host. Databases lists them per engine. SQLite, files and mail need nothing else.

The CLI is source-available (Business Source License 1.1). Building it needs only Go: go build ./cmd/safegrd from a clone is the whole build. Release archives and their checksums are on the releases page.

Try it before you sign up

safegrd try postgres://app:secret@db.example.com/app

You need no account for this. try backs up the database, encrypted on your host, to SafeGrd's storage. It also takes a MySQL, MongoDB or SQLite URL, or a directory. Then it restores the backup in memory from storage, prints the tables and rows it read back, and prints a sign-up link. Sign up to keep the backup and see its drill in the console.

The connection string stays on your host, in a file beside the config that only you can read. To keep it in the environment instead, pass it as env:DATABASE_URL.

The trial backup is kept for 24 hours and is not locked. SafeGrd keeps your key sealed and releases it only to this host, so you can restore even after losing the host. For a customer-managed key, pass --key-custody local. You can run safegrd list, verify and restore from the same host straight away.

safegrd signup

Opens the sign-up page with a code to check against the one in the terminal. When you sign up there, the host, its backup and its daily schedule become your new account's organization. You do not need to run anything more on the host. Verify your address from the email to lift the trial's limits. From the next backup on, every backup is locked under your plan. If nobody signs up, the backup and its key are deleted after 24 hours.

safegrd login, then safegrd enroll

The trial is for a new account. If you already have an organization, run these two commands on the host instead. The host enrolls in your organization as a new host, with the same surfaces and the same key, managed the way you chose at try. The trial and its backup stay behind and are deleted at the trial's deadline.

You can run one trial per machine at a time and a few per day, each up to 500 MB.

Two ways to set a host up

Whichever of these you run first generates the Age keypair. The other finds the keypair already there, so the order does not matter.

safegrd login, then safegrd enroll: connected to SafeGrd

safegrd login
safegrd enroll

This is what the installer runs for you. login prints a link and a code that you approve in any browser. enroll then registers this host, so the console can show its snapshots, schedule Fire Drills against them and tell you when the host goes quiet. If this machine has no config yet, enroll runs the local setup first. If no browser can be involved at all, pass a token from Tokens in the console instead: safegrd enroll --token sg_pat_YOUR_TOKEN.

prod-app-01
$ safegrd enroll --token env:SG_TOKEN --claim sgc_7rj6zi5k3ruu5asw
Generated an age X25519 keypair
   Public key:  age1lq70sjlq9u8ymuxvmxqwf20trfjn5qx44578xy3gvu2fqyzsaa9scp2uzm
   Private key: /home/safegrd/.safegrd/keys/daemon.key (mode 0600)
No local setup found, so it was created first.

Enrolling with https://safegrd.dev
Registering a new node with the personal access token.
Claim for project 'Production'.
Enrolled node node-c97be882 as 'prod-app-01'
   Node token:  sg_tok_…51fb (saved to the config file)
   Key:         SG:e53b6c6a:cc58f416
   Custody:     SafeGrd-managed key
                SafeGrd keeps this key sealed and releases it only to your enrolled hosts,
                so you can restore these backups even after losing this host.
                For a customer-managed key next time, enroll with --key-custody=local.
   Project ID:  proj-e1e56658

Surfaces named for this host in the console:
   shop                 postgres: set SHOP_DB on this host (the credential never leaves it)
Saved to /home/safegrd/.safegrd/config.yaml

   Next: check every surface opens from this host. The console shows the result:
     safegrd doctor
   Take the first backups now, and watch them land in the console:
     safegrd daemon run --once
   Then keep the daemon running as a service that starts at boot. Nothing backs up
   on a schedule until it runs:
     sudo safegrd daemon install
A real enrollment with a token and a claim code from Add surface. The host generates its key and SafeGrd keeps it sealed. The surface named in the console is written to the host's config. The test server's address is shown as https://safegrd.dev.

safegrd init: standalone and offline

safegrd init --storage s3 --s3-bucket my-worm-bucket

init runs only the part on the host. It generates the keypair and writes ~/.safegrd/config.yaml. It does not contact a SafeGrd server, though with an S3 bucket it asks the bucket whether Object Lock is on. A host set up this way backs up, restores and verifies on its own. Use it on an air-gapped host, or to try SafeGrd without an account.

The key init generates stays on the host. If you enroll the host later, it keeps a customer-managed key. For a SafeGrd-managed key, enroll without running init first.

A standalone host set up from nothing: safegrd init against a bucket under Object Lock, then the first backup. Recorded with the CLI built from this release, against PostgreSQL 16 and MinIO.

Who holds the private key

You choose how each host's key is managed when the host enrolls, with --key-custody. The choice decides who can decrypt the host's snapshots, and whether you can still restore them after losing the host. SafeGrd keeps the key unless you pass local.

This applies to a key the host generates. A key you supply yourself is never sent anywhere. Each surface in the console shows how its key is managed.

ModeWhat happens
--key-custody safegrd (default) SafeGrd-managed key. SafeGrd keeps your key sealed and releases it only to your organization's enrolled hosts, for restores and drills. If you lose a host, you still have your backups: enroll a new host and restore (the steps).
--key-custody local Customer-managed key. Only you can decrypt these backups. The private key is written to key_path at 0600, and only the public half is registered. Keep a copy of the key file somewhere safe.
Restoring after a host is lost. With a SafeGrd-managed key: install and enroll a new machine into the old project, run safegrd restore and SafeGrd releases the key to it, and the key access record shows the release. With a customer-managed key: install the CLI without enrolling (SAFEGRD_NO_SETUP=1), add your copy of the key file and a bucket read key, and run safegrd restore with a recovery config. Both end with the snapshot restored. The host is lost SafeGrd-managed key Customer-managed key Install and enroll into the old project Install, no enroll SAFEGRD_NO_SETUP=1 safegrd restore SafeGrd releases the key Add your key file and a bucket read key Key access record shows the release safegrd restore --config recovery.yaml The snapshot is restored
The same lost host in each mode. The steps are in the runbooks: SafeGrd-managed key and customer-managed key.

With a customer-managed key, keep a copy of ~/.safegrd/keys/daemon.key.

It is the key that decrypts your snapshots, and it stays with you. Store a copy with your most important credentials before the first backup.

The private key is never written to config.yaml. It lives at key_path. When a restore or a drill needs it, the CLI reads it from there or from SAFEGRD_PRIVATE_KEY. Security and key custody lists what SafeGrd holds and what it does not.

By platform

Each of these pages covers one platform: the hostname, role and URL to connect with, how to restore, and how to check the backup: Supabase, Neon, Amazon RDS, Railway, Render, Fly.io, DigitalOcean, Heroku, a Hetzner VPS and Coolify. For Docker Compose and Kubernetes, see Where to run it.

Where configuration lives

PathWhat it is
~/.safegrd/config.yamlThe host's config: surfaces, storage sink, retention and encryption public key. Keep it at 0600, because it holds connection strings.
~/.safegrd/keys/daemon.keyThe Age private identity, at 0600. With a customer-managed key, it never leaves the host.
~/.safegrd/Daemon state and per-surface locks, unless state_dir says otherwise.

To point a command at a different config file, use the global --config flag. To point it at a different SafeGrd server, use --server-url or SAFEGRD_SERVER_URL. Run safegrd config validate to check a file before the daemon uses it.

Check the host

# permissions, keys, sink reachability, Object Lock, clock skew, surfaces
safegrd doctor

Run safegrd doctor after setup and after every config edit. It checks:

It also opens every configured surface with the credential its backup will use, including a credential SafeGrd holds. On an enrolled host, it sends the results to the console, which shows the host as checked or says what failed. For CI, --json makes the output machine-readable.

The Hosts tab: host prod-app-01 runs uploads and shop-db, with its daemon, last check-in and CLI version. The Hosts tab: host prod-app-01 runs uploads and shop-db, with its daemon, last check-in and CLI version.
The Hosts tab lists each enrolled host with the surfaces it runs, whether a daemon runs them, its last check-in and its CLI version. A host where safegrd doctor ran shows Checked, or what failed.