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
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:
- 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.
- 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=localor chose that for this host in the console's setup (below).
The install ends with the next steps that enroll prints for this host:
safegrd doctorchecks that every surface opens.safegrd daemon run --oncetakes the first backup.sudo safegrd daemon installkeeps the daemon running.
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.
| Variable | Effect |
|---|---|
| VERSION | Release tag to install. Default: the latest release. |
| SAFEGRD_INSTALL_DIR | Where the binary goes. |
| SAFEGRD_LIB_DIR | With 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=1 | Install only, without the offer to log in and enroll. Use it on a machine you are restoring to. |
| SAFEGRD_FORCE_INSTALL=1 | Download and install even if that release is already installed. Without it, a host that already has the release goes straight to setup. |
| SAFEGRD_PROJECT | Project ID or slug to enroll this host into. |
| SAFEGRD_NODE_NAME | The name the console shows for this host. Default: the machine's hostname, without its domain. |
| SAFEGRD_KEY_CUSTODY | local keeps this host's key on the host (a customer-managed key). Without it, SafeGrd keeps the key sealed. |
| SAFEGRD_CLAIM | The claim code the console shows for this host. The host enrolls into that project, with the storage and surfaces you chose there. |
| SAFEGRD_TOKEN | A 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
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
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.
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.
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
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.
$ 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
https://safegrd.dev.safegrd init: standalone and offline
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.
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.
| Mode | What 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.
|
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
| Path | What it is |
|---|---|
| ~/.safegrd/config.yaml | The host's config: surfaces, storage sink, retention and encryption public key. Keep it at 0600, because it holds connection strings. |
| ~/.safegrd/keys/daemon.key | The 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
Run safegrd doctor after setup and after every config edit. It checks:
- the config file's permissions
- that the keypair is present and coherent
- that the storage sink answers and has Object Lock turned on
- that SafeGrd's server answers
- that the host clock has not drifted
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.
safegrd doctor ran shows Checked, or what failed.