SafeGrd

View saved version →

---
name: backup-before-risky-change
description: Take a locked SafeGrd backup of a database and prove it restores before a migration, a schema change, a bulk delete, a reset or any command that can lose data. Use when the user is about to change a production or staging database, or asks whether they have a recent backup that restores.
---

# Back up, and prove it restores, before a risky change

A backup that has not been restored is a guess. Before the change, get a snapshot taken
after the last write that matters, locked so nothing can delete it, and a Fire Drill that
restored it. Do not run the risky command until that is done, or until the user says to go
ahead without it.

## 1. Find the surface

1. Call `list_organizations`, then `list_surfaces`. A surface is one database, file tree
   or mailbox. Match the user's database by `name`, `database_name` and `surface_type`.
2. If more than one matches, ask which one. Two databases of the same engine are common
   (production and staging, or MySQL and MariaDB).

## 2. Read where it stands

- `get_surface`: `last_backup_at`, `last_verified_at`, `last_heartbeat`, `schedule`.
- `list_snapshots` with `limit: 1`: the newest snapshot, its `status`, and
  `worm_retention_until` (locked until). A snapshot with `worm_mode` `NONE` is not locked.
- `list_drills` with `limit: 1`: the newest Fire Drill, its `status` and the snapshot it
  restored.

Tell the user what you found in a few lines before you ask for anything.

## 3. Take a fresh backup

Choose the first that applies:

- **The SafeGrd CLI is on this machine and the surface is in its config** (`safegrd daemon
  status` lists its id): run `safegrd guard --surface <id> -- <the risky command>`. It
  backs up, checks the snapshot is locked, and only then runs the command. A refusal exits
  3 and says why.
  Use `safegrd backup --surface <id>` instead when the user wants the backup now and the
  change later.
- **Otherwise:** call `request_backup` with the surface's `node_id`, and read the answer:
  - Accepted: the host's daemon runs it at its next check-in, or SafeGrd queues it for a
    surface SafeGrd backs up. Call `list_snapshots` with `limit: 1` about once a minute
    until a snapshot newer than the request appears. A request is not a backup.
  - `HTTP 409`, no daemon on the host: nothing will pick the request up. Ask the user to
    run `safegrd backup --surface <id>` on that host, then continue from step 4.
  - `HTTP 429`: a backup was taken less than an hour ago. Each one is locked and stored
    until it expires, so requests are at most hourly. Tell the user when it was taken, and
    ask whether anything written since then matters.

## 4. Prove it restores

Call `request_drill` with the same `node_id`, then `list_drills` with `limit: 1` about once
a minute until a drill of the new snapshot appears.

- `passed`: report the assertions it checked (tables and rows restored, digests).
- `failed`: stop. Report the failing assertion and tell the user not to proceed.
- `HTTP 429`: the plan's drill cadence is used up until the time the answer gives. Report
  the newest passed drill and which snapshot it restored, and say the new snapshot is not
  yet proven.

## 5. Report

One fact per line: the surface, the snapshot id, when it was taken, locked until when, and
the drill result. Then say whether it is safe to proceed. Anything written after the
snapshot is not in it, so the user should pause writes or accept losing them.

View saved version →

---
name: check-backups
description: Report on SafeGrd backups across an organization, covering surfaces whose backups are late, drills that failed, surfaces never proven to restore, and hosted storage use. Use when the user asks whether their backups are working, for a backup status, or what needs attention.
---

# Check SafeGrd backups

1. Call `list_organizations`. For each organization the user cares about, call
   `get_drill_stats` (pass rate, failed drills, surfaces never proven) and `get_storage_usage`
   (hosted storage used against the quota).
2. Call `list_surfaces`. Pass `next_cursor` back as `cursor` until it is absent, so no
   surface is missed.
3. For each surface, compare `last_backup_at` with its `schedule` and `last_heartbeat`, and
   read its drill and alert state. Call `list_drills` with `limit: 1` for any surface whose
   last drill failed.

Report only what needs attention, worst first:

- a failed drill, with the assertion that failed
- a surface with no backup for longer than its schedule, or a host that stopped checking in
- a surface never drilled, meaning its backups have never been restored
- hosted storage above 80% of its quota

Then one line for the rest ("12 other surfaces backed up and drilled on schedule").

For each problem, name the next step. If it needs the host, give the command to run there
(`safegrd doctor`, `safegrd backup --surface <id>`). If a drill would
answer the question, offer `request_drill`.

View saved version →

---
name: setup-safegrd
description: Set up SafeGrd for a database, from nothing to a verified backup. Covers signing in, installing the SafeGrd CLI on a host, enrolling the host, the first backup and its restore test, and the local MCP server. Use when the user wants to start protecting a database with SafeGrd. Also adds the experimental guard hook, which takes a locked backup before an agent runs a destructive command, but only when the user asks for it.
---

# Set up SafeGrd

You can take the user from nothing to a backup that has been restored and checked, on the
host you are running on. Five things are the user's own, and you ask for them instead of
doing them: installing the CLI, signing in, choosing how the encryption key is managed,
paying, and adding a database that SafeGrd backs up from its own machines. Everything else you run yourself.

Two steps leave something running or configured after this session: the daemon's service
(step 5) and the local MCP server in `~/.codex/config.toml`. Before each one, tell the user what
it writes and where, and go ahead only when they say yes. `safegrd daemon uninstall` removes
the service; the MCP server is one entry to delete.

## The remote server

This plugin connects to `https://safegrd.dev/mcp` by signing the user in: Codex opens
SafeGrd's sign-in page, the user approves for one organization, and the sign-in is listed
under Tokens in the console. If a SafeGrd tool answers `401`, the sign-in was revoked or
expired: ask the user to connect the plugin again. Never ask them for a token in the chat.

## 1. Find out what there is

Call `list_organizations` and `list_surfaces`. If the database the user means is already a
surface with a recent backup and a passed drill, say so and stop: there is nothing to set
up. If the host you are on has the CLI (`safegrd doctor` runs), skip to step 4.

A database with no host of its own (Supabase, Neon, Railway, Render) is backed up from
SafeGrd's machines. Point the user to **Back up on SafeGrd** under Surfaces in the console,
which takes the connection string on SafeGrd's page, never in the chat. Then watch for its
first backup with `list_snapshots` and continue from step 6.

## 2. Install the CLI

Installing the CLI is the user's step: you do not download or run an installer. Check
for it with `safegrd version`. If it is not found, ask the user to install it on this host
following https://safegrd.dev/docs/install (Homebrew: `brew install safegrd/tap/safegrd`)
and tell you when it is done. Then check again. If it is installed in `~/.local/bin` and
not found, add `~/.local/bin` to `PATH` for the rest of the session.

## 3. Sign in and enroll the host

Signing in is the user's step. Two ways, and you drive both:

- **A token the user already made** (in `SAFEGRD_TOKEN`, from Tokens in the console):
  `safegrd enroll --token env:SAFEGRD_TOKEN`. Nothing to approve.
- **The browser:** run `safegrd login --no-browser`. It prints a link and a code. Give both to
  the user, tell them to open the link on any device and check that the page shows the same
  code, and wait for the command to finish. Then `safegrd enroll`.

Before `enroll`, ask how the encryption key should be managed. Do not choose for them, and do not
describe either as the weaker choice:

- **SafeGrd-managed key** (the default): SafeGrd keeps the key sealed and releases it only
  to the organization's enrolled hosts, so they can restore even after losing a host.
- **Customer-managed key** (`--key-custody local`): only they can decrypt these backups.
  They keep a copy of the key file somewhere safe.

`enroll` generates the key pair, registers the host and prints its node id. With
`--project <id or slug>` it goes into that project; without, the organization's default.

## 4. Add the database and where backups go

`safegrd init --database-url env:DATABASE_URL` writes the config with the database as its
first surface. Read the URL from the app's environment or `.env`, never type it into the
c

Preview of the first 4,000 characters. Read full instructions →