restorable docs
Connect

Auth key setup

How a freshly-installed agent binds to your org. The one-time exchange that turns an unauthenticated install into an authenticated identity the orchestrator trusts.

What an auth key is

An eight-character code the dashboard generates when you click Agents → Add machine. Format XXXX-XXXX, uppercase letters and digits with visually ambiguous pairs like 0/O and 1/I excluded.

Properties:

  • Valid for fifteen minutes from issue.
  • Single-use. Once exchanged, it is consumed.
  • Issued by the specific org you were logged into. You cannot claim an agent into a different org.
  • Not a secret with any durable value. Leaking an expired code is harmless; leaking a live one within the fifteen-minute window lets an attacker register an agent on your org. Paste it once and move on.

Running up

sudo -u restorable RESTORABLE_HOME=/var/lib/restorable \
  restorable init \
  --orchestrator https://app.restorable.app \
  --auth-key=rsk_auth_…

Run this as the restorable system user so every file init writes lands with the right ownership from the start. The installer created that user; this command is the first real thing it does. RESTORABLE_HOME is the install root the agent reads + writes from; the systemd unit sets it for you, so any subsequent invocation that goes through the unit doesn't need the prefix.

What up does, step by step

  1. Creates the install root if missing (/var/lib/restorable/ with mode 0700). Idempotent; re-running after a partial failure picks up where it left off.
  2. Generates the signing key (Ed25519) and age encryption key if they do not exist. Writes them to /var/lib/restorable/keys/signing.key, /var/lib/restorable/keys/signing.pub, and /var/lib/restorable/keys/age.key, all mode 0600. If the keys already exist (re-running setup after a partial network failure), reuses them.
  3. Sends the auth key and the public signing key to POST /api/bootstrap/attach. The orchestrator verifies the code, mints an agent_id and api_token, and returns them along with the org_id.
  4. Writes the bearer token to /var/lib/restorable/keys/api_token, mode 0600, owned restorable:restorable.
  5. Writes /var/lib/restorable/config.yaml in managed mode, containing the agent_id, org_id, orchestrator URL, and example source + check blocks.
  6. Prints a Next-steps footer pointing at setting the DB env var and starting the service.

What up does not do

init does not start the service. init does not register a source. init does not take a backup. Those are deliberate separations so that each step in the flow is reversible without rolling back a prior step.

Re-running up

init is idempotent along a narrow axis: if the partial state shows an api_token already on disk and the config has a real agent.id, re-running does not hit the orchestrator, it just re-renders the config. Safe to re-run after fixing a typo in --orchestrator.

Re-running with a fresh auth key for a new agent registration requires --force-reattach (or moving the install root aside): 

sudo mv /var/lib/restorable /var/lib/restorable.bak
sudo install -d -o restorable -g restorable -m 0700 /var/lib/restorable
sudo -u restorable RESTORABLE_HOME=/var/lib/restorable \
  restorable init \
  --orchestrator https://app.restorable.app \
  --auth-key=rsk_auth_…

The old install root holds keys for an agent that still exists orchestrator-side. If you are replacing it, retire the old agent record from the dashboard first.

What the dashboard shows after a successful setup

The Agents screen the code was issued on replaces the "Waiting for first heartbeat" placeholder with the agent's name and a green dot within a minute. The agent's public signing key is recorded on that entry; the dashboard does not show the key itself, but it is available in the agent detail view for export to auditors.

Troubleshooting

Error: auth key expired

Fifteen minutes since issue. Generate a fresh code from the dashboard and re-run setup. Nothing to clean up on the agent side; setup only writes state after a successful exchange.

Error: auth key already used

Either setup already succeeded once for this code (check /var/lib/restorable/keys/api_token exists) or somebody else ran it. Generate a fresh code; if the token already exists on disk, read the setup output. It prints the agent_id it is reusing.

Error: connection refused or TLS failure

The agent host cannot reach the orchestrator URL. Check outbound HTTPS to app.restorable.app:443. Firewall or proxy configuration goes here.

The wrong --orchestrator URL

Setup validates the URL is reachable; a typo shows up as a connection error. No state has been written yet; fix the URL and re-run.

Next

The agent is registered but not running. Continue with the quickstart from step 5, or jump directly to Add a Postgres source.