Configuration

config.yaml is the only configuration input, and it has exactly two required keys.

api_url: https://api.saved.sh
token: "<shown once when the worker was provisioned>"

Everything else, the hub address, the namespace, the task queue, is fetched from the API at startup with that same token. None of it is a value you could know in advance, so none of it is asked for.

Where the file lives

The worker reads config.yaml relative to its working directory. There is no flag and no path argument.

Every top-level key can also be supplied as an environment variable of the same name in upper case: API_URL, TOKEN, DEBUG, LOCAL_TEMP_PATH, ENCRYPTION_PUBLIC_KEY, HUB_ADDRESS and so on. When those are set the file is optional, which is how the container image is configured.

Permissions

This file holds your database passwords. Nothing else on the host should be able to read it.

sudo install -d -m 0750 -o saved -g saved /etc/saved
sudo install -m 0600 -o saved -g saved config.yaml /etc/saved/config.yaml

The token never enters our database, and never appears in a log line. It is on your disk and nowhere else, which means the file permissions are the whole of its protection.

Full reference

Only api_url and token are required. Everything else is shown with the value the worker uses when you leave it out.

api_url: https://api.saved.sh
token: "<shown once when the worker was provisioned>"

debug: false                        # verbose logging, to stderr
local_temp_path: /tmp/saved         # staging dir, default <os temp>/saved

# Absolute paths to the dump tools. Only needed when they are not on PATH.
tools:
  pg_dump: /usr/local/bin/pg_dump
  mysqldump: /usr/local/bin/mysqldump
  curl: /usr/bin/curl

# One entry per backup, keyed by the backup id from the dashboard.
backups:
  "<backup-uuid>":
    source_type: postgres
    compression: true               # gzip before upload
    encryption:                     # per backup, not per worker
      public_key: ./keys/prod.asc   # a path, or the armoured key inline
    source:
      database: app
      host: db.internal
      port: 5432
      user: app
      password: "<password>"
      ssl_mode: require

The orchestration endpoint is not configured here. The worker fetches it from the API at startup, along with its namespace and task queue.

Five more keys exist and are overrides you should not normally set, because the worker is told these at startup. They are flat, not nested under a hub: block.

Encryption

Encryption is per backup, not per worker. One machine can hold backups for different systems, and the key that protects one is not the key for another.

public_key takes either the armoured public half inline or a path to a file holding it. A relative path resolves against the config file's own directory, so the config is runnable from anywhere. A path that cannot be read, or a file that holds no armoured key, fails at startup: skipping it would upload the artifact in the clear, which is the one failure you would not notice.

The worker-wide fallback

A top-level encryption_public_key is used by any backup that sets no key of its own. It is a convenience for a worker whose backups all belong to the same system, and the per-backup key always wins where both are set.

encryption_public_key: |
  -----BEGIN PGP PUBLIC KEY BLOCK-----
  ...
  -----END PGP PUBLIC KEY BLOCK-----

Generate one, keep the private half somewhere you will still have it after the incident that makes you need it, and give the worker the public half:

gpg --quick-generate-key "backups@example.com" default default never
gpg --armor --export backups@example.com

We hold only the public key, and only because you put it here. We cannot decrypt your backups, and we cannot recover them if you lose the private key. Encryption happens on this machine, before anything is uploaded. When compression is on, the dump is gzipped first, so the artifact is compressed whether or not it is also encrypted.

Connecting to the hub

The hub is not configured here. At startup the worker calls the API with its token and is told its address, namespace, worker ID and task queue. A worker with a valid api_url and token therefore needs nothing else to connect, and moving the hub does not mean editing every worker's file.

TLS is on by default and is what hub.saved.sh expects. The system trust store is used, so there is no CA file to supply: hub.saved.sh presents a publicly trusted certificate.

External tools

Four of the source types shell out to a tool that has to be on the host. The s3, file, folder and script sources need nothing beyond the binary itself.

The worker resolves all four at startup and logs the result. A missing tool is a warning, not a fatal error: it fails only the runs of the source type that needs it, with a non-retryable MissingTool. That is deliberate, so a host that only does file backups does not need a Postgres client.

The container image ships all four.

Per-backup sources

Every backup this worker serves needs an entry under backups:, keyed by the backup ID from the dashboard or sctl backup list.

backups:
  "018f3c2a-9e11-7c4d-b0a1-2e6f5d3c9a70":
    source_type: postgres
    source:
      database: app
      host: db.internal
      port: 5432

Three failure modes are non-retryable on purpose, because the worker will not guess:

Write the natural YAML type. A port is a number, a flag is a boolean, and a list is a list. The worker parses source: into a struct per source type, so it knows what each field should be. Quoted forms are still accepted, so an older config keeps working.

port: 5432                        # not "5432"
no_owner: true                    # not "true"
exclude_tables: [audit_log, sessions]

exclude, include, args, tables and exclude_tables are lists. A newline-separated block scalar is still read as one entry per line, so configs written before these were lists parse unchanged.

Source types

Local backups support eight source types. script, file and folder are local-only, permanently: they run your commands or read your own disk, neither of which our cloud can or should do.

postgres

Runs pg_dump -Fc (custom format), producing <database>.dump.

"<backup-uuid>":
  source_type: postgres
  source:
    database: app
    host: db.internal
    port: 5432
    user: backup
    password: "<password>"
    ssl_mode: require
    exclude_tables: [audit_log, sessions]
    no_owner: true
    no_privileges: true

The worker always passes --no-password, so pg_dump fails fast with a readable error instead of blocking on an interactive prompt no one will ever answer.

mysql

Runs mysqldump --single-transaction --quick --routines --events --triggers, producing <database>.sql.

Setting both tables and exclude_tables is refused at startup. They express opposite intentions and the worker will not pick one.

--single-transaction takes a consistent snapshot without locking the whole database, which is the difference between a nightly backup you can run in production and one you cannot.

redis

Reads every key with SCAN and DUMP, producing <host>.redis.jsonl. Needs no external tool, and works against managed Redis.

A server that refuses the sync exits zero and writes nothing. The worker treats an empty snapshot as a failure rather than uploading a zero-byte artifact.

s3

Copies a bucket or prefix into one tar, producing <bucket>.tar. Any S3-compatible store works: AWS S3, Cloudflare R2, MinIO, Backblaze B2, Wasabi.

"<backup-uuid>":
  source_type: s3
  source:
    bucket: uploads
    endpoint: minio.internal:9000
    access_key_id: "<key>"
    secret_access_key: "<secret>"
    use_path_style: true

An object rewritten while it is being copied fails the run. The tar header is written from the listing and cannot be corrected afterwards, so the alternative would be a silently truncated file, which is worse than a failure you can see. An empty bucket or prefix fails with EmptySource rather than producing an empty archive.

web

Fetches a URL with curl and stores the response body.

"<backup-uuid>":
  source_type: web
  source:
    url: https://api.internal/export
    headers: |
      Authorization: Bearer <token>
      Accept: application/json

Redirects are followed, but only to http and https, so a redirect to file:// cannot turn a web backup into a filesystem read. HTTP error statuses fail the run. The artifact is named from the response's Content-Disposition, falling back to the last path segment of the final URL.

script

Runs a command you own and stores whatever it writes to the path in $SAVED_OUTPUT.

"<backup-uuid>":
  source_type: script
  source:
    path: /opt/saved/dump-everything.sh
    working_dir: /opt/saved

#!/usr/bin/env bash
set -euo pipefail

pg_dump --format=custom mydb > "$SAVED_OUTPUT"

file

Copies one regular file, keeping its name.

A symlink without follow_symlinks is refused rather than quietly backing up the link text. Directories, sockets, devices and FIFOs are refused with an explanation.

folder

Walks a directory tree into a zip, producing <folder>.zip.

"<backup-uuid>":
  source_type: folder
  source:
    path: /srv/uploads
    exclude: ["*.tmp", "node_modules", ".git"]

A pattern matches against the full relative path, the base name, or any single path segment, so node_modules excludes the directory wherever it appears. Excluding a directory skips the whole subtree. Entries are stored without zip compression, because the encryption step compresses anyway and doing it twice costs CPU for nothing.

When follow_symlinks is set, each resolved target is archived once, so a link cycle cannot produce an infinite archive.

Multiple workers on one host

Each worker needs its own working directory, because each needs its own config.yaml.

/etc/saved/prod/config.yaml     # worker A
/etc/saved/staging/config.yaml  # worker B

Run one process per directory. They can share a local_temp_path, since staging files are uniquely named, but giving each its own makes disk pressure easier to attribute.

What you must not do is run the same config twice. See one process per credential.

Next