Remote Agents

A remote agent backs up and restores databases that Databasement cannot reach directly — without opening any inbound port to them.

Instead of Databasement connecting in to your database (as an SSH tunnel does), you run a small agent next to the database that connects out to Databasement. The database stays completely private; only outbound HTTPS is ever needed.

Egress, not ingress

The SSH tunnel needs inbound access (Databasement reaches into the network). An agent needs only outbound HTTPS. That makes it the right fit for hardened, firewalled, or multi-tenant environments where opening inbound ports is forbidden.

How it works

The agent is the same Databasement image running in agent mode (agent:run). It polls the server over HTTPS, claims any job assigned to it, runs the dump (or the restore) on its own network, moves the snapshot straight between the database and your storage volume, and reports back. It never receives an inbound connection and never touches the server's database.

1. Poll — the agent sends a heartbeat and asks the server for work.
2. Claim — the server hands back a job describing the database, the schedule, and the destination volume.
3. Run — the agent dumps the database (it reaches it on the local network) and uploads the snapshot to the volume.
4. Report — the agent acknowledges the result (filename, size, checksum, logs) so the snapshot shows up in the UI like any other.

When to use an agent

• The database lives in a network where no inbound port can be opened (compliance, firewall, customer-managed VPC).
• You back up databases in many isolated networks and want one Databasement server orchestrating them all over HTTPS.
• An SSH tunnel isn't possible because there's no SSH host to reach.

If you can reach the database directly or over SSH, prefer that — it's simpler. The agent's unique value is the outbound-only connectivity.

Setup

1. Create an agent: go to Agents → Add Agent. The token is shown once on creation, together with ready-to-paste deployment snippets for your server.

2. Run the agent next to your database. Whatever the deployment, it needs only two environment variables:

   DATABASEMENT_URL=https://databasement.example.com
   DATABASEMENT_AGENT_TOKEN=<paste-token>

   When DATABASEMENT_URL is set, the container runs in agent mode: it only executes agent:run and needs no app key, database or volume of its own.

   Docker Compose

   docker-compose.yml

   services:
     databasement-agent:
       image: davidcrty/databasement:1
       restart: unless-stopped
       environment:
         DATABASEMENT_URL: 'https://databasement.example.com'
         DATABASEMENT_AGENT_TOKEN: '<paste-token>'

   docker compose up -d

   Helm / Kubernetes

   The Helm chart runs one Deployment per enabled entry under agents. With app.enabled=false the release contains only the agents (no web app, worker, PVC, Service or Ingress), so it can live in its own namespace or cluster:

   helm repo add databasement https://david-crty.github.io/databasement
   helm repo update
   helm install databasement-agent databasement/databasement \
     --set app.enabled=false \
     --set agents.main.enabled=true \
     --set agents.main.url='https://databasement.example.com' \
     --set agents.main.token.value='<paste-token>'

   Several agents can share a release, each with its own token. To keep tokens out of your values, store them in Secrets and reference them instead:

   kubectl create secret generic databasement-agents \
     --from-literal=main='<paste-token>' \
     --from-literal=eu='<paste-other-token>'

   values.yaml

   app:
     enabled: false
   
   agents:
     main:
       enabled: true
       url: https://databasement.example.com
       token:
         fromSecret:
           secretName: databasement-agents
           secretKey: main
     eu:
       enabled: true
       url: https://databasement.example.com
       token:
         fromSecret:
           secretName: databasement-agents
           secretKey: eu

   Keep app.enabled at its default to run agents in the same release as the server.

   Docker

   docker run -d --restart unless-stopped \
     --name databasement-agent \
     -e DATABASEMENT_URL='https://databasement.example.com' \
     -e DATABASEMENT_AGENT_TOKEN='<paste-token>' \
     davidcrty/databasement:1

   Pin the agent to your server's minor version (for example davidcrty/databasement:1.9, or --version with Helm) so it stays compatible: see the version note below.

3. Assign the agent to a database server by setting its Agent field. From then on, that server's backups, and any restore that targets it, run through the agent.

The Agents page shows each agent's connection status, so you can confirm it's polling, and the version it runs. An agent counts as up to date when its major and minor version match the server's, whatever the patch. An agent on an older minor is flagged, and so is one too old to report its version at all; the Agents menu entry then shows a warning listing them. Agents built from an untagged image (such as edge) show their commit instead and are not compared.

Server and agents are compatible within the same minor version: a patch release never requires updating your agents, but after upgrading the server to a new minor, update your agents too.

Constraints

• No local volume — the agent uploads from its own network, so it must use a reachable destination (S3-compatible or SFTP/FTP), not the server's local storage.
• Restores read from a reachable volume — a restore onto an agent-backed server downloads the snapshot on the agent's network, so the snapshot must have a copy on a volume the agent can reach. Copies on the server's local storage are not offered as a source.
• A lost agent delays the retry — an agent reports every 30 seconds while a dump runs, and a backup whose agent goes silent for 10 minutes (a restart or a network outage included) is started again from scratch. Agents up to 1.8.4 cannot report during a dump, so their backups are retried only once the full backup job timeout has passed.
• Cancelling stops the agent at its next report: every 30 seconds while a command runs, or at its next step. Agents up to 1.8.4 do not stop: they run the whole job and only see it was cancelled when they report the result.
• Restores are never retried — a restore drops and recreates the target database, so a restore interrupted by a lost agent is reported as failed rather than run again. It is given the full backup job timeout to finish, and fails if no agent claims it within that time.

Restoring through an agent

Restoring onto an agent-backed server works like any other restore: pick the server as the target from the UI, the API, the MCP server, or a scheduled restore. Instead of running on Databasement's queue, the restore is handed to the server's agent, which downloads the snapshot, restores it, and streams its logs back to the restore's job.

This makes agent-backed servers usable for recurring production-to-staging refreshes, where staging sits in a network Databasement cannot reach.

Update your agents

Agents only pick up restore jobs once they run a version that supports them. An older agent keeps running backups but leaves restores pending until they time out, so update the agent image before restoring onto its servers.