XNS Relayer

The XNS Relayer is an S3‑compatible storage gateway. You point any S3 client at it and it spreads your data across a decentralized network of independent storage providers using erasure coding — 80 data + 40 parity shards across 120 hosts, so your files survive even when a lot of those hosts don't.

Run it on your own machine, get a local S3 endpoint, and use it like you'd use any S3 bucket.

Port 8888 is the web dashboard, 9000 is the S3 API (plain HTTP), and 9443 is the encrypted S3 endpoint that turns on if you install a TLS certificate. You'll install Docker in the next step — that's the only software you need.

What throughput to expect: on the 2-vCPU reference hardware this build is tested against, a single upload stream (S3 PUT) moves roughly 5–7 MiB/s. The bottleneck is CPU, not your network — machines with more CPU headroom will see higher rates.

Before you install, pick the deployment profile that matches your situation. Each profile shows what every port is for, who needs to reach it, and the consequence if the wrong party reaches it. This takes one minute and saves you from guessing later.

Three decisions before you continue

These are optional. The defaults work for most workstation installs. Choosing "not yet" on any of them is a complete, documented outcome — nothing will prompt you again.

docker exec xns-relayer sh -c 'grep -E "require_encrypted_management|refuse_unencrypted_storage_offbox" /relayer/conf/relayer_configuration.json'
docker exec xns-relayer sh -c 'grep S3GW_REFUSE_UNENCRYPTED_OFFBOX /relayer/conf/xns.env 2>/dev/null || pm2 env 0 | grep S3GW_REFUSE_UNENCRYPTED_OFFBOX'

If you use a self-signed certificate

When you install a self-signed certificate (via Settings → Certificates), here is what happens:

• Your browser will show a certificate warning when you visit the dashboard over HTTPS. This is expected — the certificate was not issued by a public certificate authority, so the browser cannot verify it automatically.
• Why: a self-signed certificate still encrypts the connection, but it does not prove the server's identity to a third party. The browser warns because it cannot distinguish your self-signed certificate from an intercepted connection.
• How to verify: print the certificate's SHA-256 fingerprint from the container and compare it with the one your browser shows in the certificate details dialog:
  Copy

  docker exec xns-relayer openssl x509 -in /relayer/conf/certs/public.crt -noout -fingerprint -sha256

  The Settings → Certificates page also shows the fingerprint. If both match the browser's certificate details, the connection is to your Relayer.
• To replace the certificate later: upload a new certificate (from a public CA such as Let's Encrypt, or from your organization's internal CA) on the Settings → Certificates page. The browser warning disappears once the certificate is issued by a trusted CA. No reinstall is needed.

Verify actual port publication (after install)

After starting the Relayer (Step 5), confirm that Docker actually published the ports you expect:

docker port xns-relayer

On a default install you should see:

8888/tcp -> 0.0.0.0:8888
9000/tcp -> 0.0.0.0:9000
9443/tcp -> 0.0.0.0:9443

Compare the output against whatever you set in .env. If you set BIND_ADDRESS=127.0.0.1:, all three lines should show 127.0.0.1 (for example 8888/tcp -> 127.0.0.1:8888). If the output still shows the old value, remember that editing .env alone does not change port publication — you must recreate the container: docker compose up -d.

Prefer not to copy‑paste commands? If you use Claude, it can do the whole setup for you — check your system, register your account, start the Relayer, and verify storage — just by talking to it. This is the fastest way to get running. The manual steps below still work if you'd rather drive it yourself.

Claude Desktop — add this to your claude_desktop_config.json (Settings → Developer → Edit Config), then fully quit and reopen Claude Desktop:

{
  "mcpServers": {
    "relayer": {
      "command": "npx",
      "args": ["@xns-cloud/relayer-mcp@latest"]
    }
  }
}

Claude Code — one command instead of editing JSON:

claude mcp add --scope user relayer -- npx @xns-cloud/relayer-mcp@latest

Then just tell Claude:

Prefer the terminal? The xns CLI is a single self-contained binary that talks to your Relayer from the command line — handy for scripting and quick checks. It's optional; the dashboard and your S3 client cover everything the CLI does.

Download the build for your platform from the release file server, then make it executable:

Linux (x86-64)

curl -fL https://releases.xns.tech/xns-cli/release/linux-amd64/xns -o xns
chmod +x xns

macOS (Apple Silicon)

curl -fL https://releases.xns.tech/xns-cli/release/darwin-arm64/xns -o xns
chmod +x xns

Step 1 of 2 — Verify the download. Each binary has a SHA-256 checksum beside it. Download it and compare:

curl -fL https://releases.xns.tech/xns-cli/release/linux-amd64/xns.sha256 -o xns.sha256
sha256sum -c xns.sha256

Then confirm it runs:

./xns version

The Relayer runs inside Docker. If you've never used Docker, no problem — you install it once and never think about it again. Pick your operating system:

Verify it worked

Open a terminal (PowerShell on Windows, Terminal on Mac/Linux) and run:

docker --version

This is a public build — there is nothing to log into. Skip straight to the next step.

This folder holds your one config file. Create it and move into it:

mkdir -p ~/xns-relayer
cd ~/xns-relayer

On Windows PowerShell the same two commands work as‑is.

This step saves two files side by side: the compose file and a small .env next to it. Create a file named docker-compose.yml inside ~/xns-relayer and paste in exactly this:

services:
  relayer:
    container_name: xns-relayer       # keep this name — Prometheus scrapes it by name
    image: releases.xns.tech/xns-relayer:release-149e4d63
    pull_policy: always         # `up -d` fetches the current moving-tag image, never a stale cache
    restart: unless-stopped
    privileged: true            # needed for the Relayer's disk + storage management
    # Audit-mode plumbing — turns the audit file sink on only in loki mode (the
    # default). Driven by RELAYER_AUDIT_MODE from your .env; do not edit.
    command: >
      sh -c '
      if [ "${RELAYER_AUDIT_MODE:-loki}" = "loki" ]; then
        export S3GW_AUDIT_NDJSON_PATH=/var/log/relayer-audit/audit.ndjson;
      fi;
      exec /xns/xns.sh
      '
    ports:
      - "${BIND_ADDRESS:-}${UI_PORT:-8888}:8888"   # web dashboard
      - "${BIND_ADDRESS:-}${S3_PORT:-9000}:9000"   # S3 API (plain HTTP, always on)
      - "${BIND_ADDRESS:-}${S3_TLS_PORT:-9443}:9443"   # S3 API (HTTPS, active once you install a cert)
    environment:
      - NODE_ENV=production
      - XNS_RELEASE_CHANNEL=release
      # Webhook mode only — set both in your .env; empty = disabled.
      - S3GW_AUDIT_WEBHOOK_URL=${S3GW_AUDIT_WEBHOOK_URL:-}
      - S3GW_AUDIT_WEBHOOK_SECRET=${S3GW_AUDIT_WEBHOOK_SECRET:-}
    volumes:
      - relayer_data:/relayer     # all data + database + config live here
      - ${LEGACY_DATA_PATH:-./data}:/relayer-legacy-check:ro   # B-4: lets the relayer refuse to start over a stranded bind-mount DB (see "Upgrading"); harmless on fresh installs
      - /mnt:/mnt:rslave          # host-disk passthrough for Cloud Sync (no-op if /mnt is empty)
      - audit_logs:/var/log/relayer-audit   # audit-log landing (loki mode); harmless when audit is off
      - relayer_logs:/relayer/log   # E3: app logs on their own volume so alloy can tail them without seeing /relayer/conf secrets
    networks:
      default:
        ipv4_address: 172.28.0.10   # pinned — the Grafana auth proxy trusts this IP; do not change

  # Audit-egress sidecars — ON by default. Your .env (Step 4, next block) switches
  # them via RELAYER_AUDIT_MODE; never edit these entries and never set
  # COMPOSE_PROFILES directly.
  loki:
    image: releases.xns.tech/relayer-loki:release-149e4d63
    pull_policy: always
    restart: unless-stopped
    profiles: ["loki"]
    command:
      - -config.file=/etc/loki/loki.yml
    volumes:
      - loki_data:/loki           # no host port — reached only inside the compose network
    deploy:
      resources:
        limits:
          memory: 256M

  alloy:
    image: releases.xns.tech/relayer-alloy:release-149e4d63
    pull_policy: always
    restart: unless-stopped
    profiles: ["loki"]
    command:
      - run
      - --server.http.listen-addr=0.0.0.0:12345
      - /etc/alloy/config.alloy
    environment:
      - S3GW_AUDIT_LOKI_PUSH_URL=${S3GW_AUDIT_LOKI_PUSH_URL:-}   # optional BYO-Loki push target; empty = on-box Loki
    depends_on:
      - loki
    volumes:
      - audit_logs:/var/log/relayer-audit:ro   # tails the audit log read-only
      - relayer_logs:/relayer/log:ro   # E3: tails the app logs; dedicated volume = Alloy never sees /relayer/conf secrets
    deploy:
      resources:
        limits:
          memory: 128M

  audit-logrotate:
    image: releases.xns.tech/relayer-audit-logrotate:release-149e4d63
    pull_policy: always
    restart: unless-stopped
    profiles: ["loki"]
    volumes:
      - audit_logs:/var/log/relayer-audit   # rotates audit.ndjson in place (~600 MB cap)
    deploy:
      resources:
        limits:
          memory: 32M

  # Monitoring stack — powers the dashboards under Monitoring in the web UI.
  prometheus:
    container_name: prometheus    # keep — the docs' `docker exec prometheus` commands rely on it
    image: releases.xns.tech/relayer-prometheus:release-149e4d63
    pull_policy: always
    restart: unless-stopped
    # The first two flags must stay; the retention pair reads your .env.
    command:
      - --config.file=/etc/prometheus/prometheus.yml
      - --storage.tsdb.path=/prometheus
      - --storage.tsdb.retention.time=${PROMETHEUS_RETENTION_TIME:-15d}
      - --storage.tsdb.retention.size=${PROMETHEUS_RETENTION_SIZE:-2GB}
    # Alert-threshold dials — all optional, defaults built in. See "Alerts" below.
    environment:
      - ALERT_DISK_FREE_BYTES=${ALERT_DISK_FREE_BYTES:-}
      - ALERT_DISK_FREE_FOR=${ALERT_DISK_FREE_FOR:-}
      - ALERT_S3_UNREACHABLE_FOR=${ALERT_S3_UNREACHABLE_FOR:-}
      - ALERT_S3_ERROR_RATE=${ALERT_S3_ERROR_RATE:-}
      - ALERT_S3_ERROR_RATE_FOR=${ALERT_S3_ERROR_RATE_FOR:-}
      - ALERT_S3_P95_LATENCY_SECONDS=${ALERT_S3_P95_LATENCY_SECONDS:-}
      - ALERT_S3_P95_LATENCY_FOR=${ALERT_S3_P95_LATENCY_FOR:-}
      - ALERT_HOSTIO_DOWN_FOR=${ALERT_HOSTIO_DOWN_FOR:-}
      - ALERT_GATEWAY_DOWN_FOR=${ALERT_GATEWAY_DOWN_FOR:-}
      - ALERT_CRASH_LOOP_FOR=${ALERT_CRASH_LOOP_FOR:-}
      - ALERT_CACHE_PRESSURE_RATIO=${ALERT_CACHE_PRESSURE_RATIO:-}
      - ALERT_CACHE_PRESSURE_FOR=${ALERT_CACHE_PRESSURE_FOR:-}
      - ALERT_BRIDGE_STALE_SECONDS=${ALERT_BRIDGE_STALE_SECONDS:-}
      - ALERT_BRIDGE_STALE_FOR=${ALERT_BRIDGE_STALE_FOR:-}
      - ALERT_TARGET_DOWN_FOR=${ALERT_TARGET_DOWN_FOR:-}
      - ALERT_AUDIT_SIEM_DEAD_FOR=${ALERT_AUDIT_SIEM_DEAD_FOR:-}
    volumes:
      - prometheus_data:/prometheus
    deploy:
      resources:
        limits:
          memory: ${PROMETHEUS_MEMORY_LIMIT:-512M}

  alertmanager:
    # Delivers firing alerts to your webhook/email and sends the Watchdog
    # heartbeat — see "Alerts" below. Runs fine unconfigured (no delivery).
    container_name: alertmanager   # keep — the docs' `docker exec alertmanager` commands rely on it
    image: releases.xns.tech/relayer-alertmanager:release-149e4d63
    pull_policy: always
    restart: unless-stopped
    environment:
      - ALERTMANAGER_WEBHOOK_URL=${ALERTMANAGER_WEBHOOK_URL:-}
      - ALERTMANAGER_GROUP_WAIT=${ALERTMANAGER_GROUP_WAIT:-}
      - ALERTMANAGER_REPEAT_INTERVAL=${ALERTMANAGER_REPEAT_INTERVAL:-}
      - ALERTMANAGER_SMTP_SMARTHOST=${ALERTMANAGER_SMTP_SMARTHOST:-}
      - ALERTMANAGER_SMTP_FROM=${ALERTMANAGER_SMTP_FROM:-}
      - ALERTMANAGER_SMTP_TO=${ALERTMANAGER_SMTP_TO:-}
      - ALERTMANAGER_SMTP_AUTH_USERNAME=${ALERTMANAGER_SMTP_AUTH_USERNAME:-}
      - ALERTMANAGER_SMTP_AUTH_PASSWORD=${ALERTMANAGER_SMTP_AUTH_PASSWORD:-}
      - WATCHDOG_HEARTBEAT_URL=${WATCHDOG_HEARTBEAT_URL:-}
      - WATCHDOG_REPEAT_INTERVAL=${WATCHDOG_REPEAT_INTERVAL:-}
    volumes:
      - alertmanager_data:/alertmanager
    deploy:
      resources:
        limits:
          memory: ${ALERTMANAGER_MEMORY_LIMIT:-128M}

  grafana:
    image: releases.xns.tech/relayer-grafana:release-149e4d63
    pull_policy: always
    restart: unless-stopped
    environment:
      # Auth-proxy mode: relayer-ui /grafana proxy injects X-WEBAUTH-USER; anon
      # off (fail-closed). WHITELIST pins trust to the relayer static IP
      # (172.28.0.10, the networks:/ipam pin below) so no sibling container can
      # forge the header.
      - GF_AUTH_ANONYMOUS_ENABLED=false
      - GF_AUTH_PROXY_ENABLED=true
      - GF_AUTH_PROXY_HEADER_NAME=X-WEBAUTH-USER
      - GF_AUTH_PROXY_HEADER_PROPERTY=username
      - GF_AUTH_PROXY_AUTO_SIGN_UP=true
      - GF_AUTH_PROXY_WHITELIST=172.28.0.10
      # Admin for the auto-provisioned proxy user (identity-bound). Grafana's
      # default is Viewer (read-only) — omitting this makes dashboards RO.
      - GF_USERS_AUTO_ASSIGN_ORG_ROLE=Admin
      - GF_SERVER_SERVE_FROM_SUB_PATH=true
      - GF_SERVER_ROOT_URL=%(protocol)s://%(domain)s/grafana
    volumes:
      - grafana_data:/var/lib/grafana
    deploy:
      resources:
        limits:
          memory: ${GRAFANA_MEMORY_LIMIT:-256M}

  node-exporter:
    image: prom/node-exporter:v1.11.1
    restart: unless-stopped
    command:
      - --path.rootfs=/host
    volumes:
      - /:/host:ro,rslave     # read-only host metrics (rslave: required on real Linux hosts)

volumes:
  relayer_data:
  relayer_logs:   # E3: dedicated app-log volume (relayer writes, alloy tails ro) — keeps /relayer/conf out of the log shipper
  prometheus_data:
  grafana_data:
  alertmanager_data:
  audit_logs:
  loki_data:

networks:
  # Fixed private subnet so the relayer's pinned IP above is stable — the
  # Grafana auth proxy whitelists it. Chosen not to collide with home LANs.
  default:
    driver: bridge
    ipam:
      config:
        - subnet: 172.28.0.0/24
          gateway: 172.28.0.1

Now create the second file, named .env, in the same folder — it carries the audit-logging switch the compose file reads:

# Audit logging mode — loki (default) | webhook | off. See "Audit logging" below.
#RELAYER_AUDIT_MODE=off
#S3GW_AUDIT_WEBHOOK_URL=
#S3GW_AUDIT_WEBHOOK_SECRET=

# Internal plumbing — never edit this line and never set COMPOSE_PROFILES yourself.
COMPOSE_PROFILES=${RELAYER_AUDIT_MODE:-loki}

# Need different ports? Uncomment and change if 8888/9000/9443 are taken.
#UI_PORT=8888
#S3_PORT=9000
#S3_TLS_PORT=9443
# Localhost only? Uncomment to publish all three ports on 127.0.0.1 (keep the trailing colon).
#BIND_ADDRESS=127.0.0.1:

# ---- Alerts (all optional — see the "Alerts" section below) ----
# Webhook that receives every firing alert (JSON POST):
#ALERTMANAGER_WEBHOOK_URL=
# Email as a second receiver — set all three; auth optional:
#ALERTMANAGER_SMTP_SMARTHOST=smtp.example.com:587
#[email protected]
#[email protected]
#ALERTMANAGER_SMTP_AUTH_USERNAME=
#ALERTMANAGER_SMTP_AUTH_PASSWORD=
# Off-box heartbeat (Healthchecks.io / Cronitor ping URL) — tells you when the
# monitoring itself dies. Never the same URL as the webhook above:
#WATCHDOG_HEARTBEAT_URL=
#WATCHDOG_REPEAT_INTERVAL=5m
# How often a still-firing alert re-notifies / how long the first one waits:
#ALERTMANAGER_GROUP_WAIT=30s
#ALERTMANAGER_REPEAT_INTERVAL=5m

# ---- Alert thresholds (defaults shown; *_FOR = how long before it fires) ----
#ALERT_DISK_FREE_BYTES=5368709120
#ALERT_DISK_FREE_FOR=5m
#ALERT_S3_UNREACHABLE_FOR=60s
#ALERT_S3_ERROR_RATE=0.01
#ALERT_S3_ERROR_RATE_FOR=2m
#ALERT_S3_P95_LATENCY_SECONDS=2.0
#ALERT_S3_P95_LATENCY_FOR=2m
#ALERT_HOSTIO_DOWN_FOR=60s
#ALERT_GATEWAY_DOWN_FOR=60s
#ALERT_CRASH_LOOP_FOR=2m
#ALERT_CACHE_PRESSURE_RATIO=0.85
#ALERT_CACHE_PRESSURE_FOR=5m
#ALERT_BRIDGE_STALE_SECONDS=120
#ALERT_BRIDGE_STALE_FOR=60s
#ALERT_TARGET_DOWN_FOR=2m
# How long a CONFIGURED SIEM webhook must fail continuously before the
# AuditSIEMFeedDead alert fires. No effect when no webhook is set.
#ALERT_AUDIT_SIEM_DEAD_FOR=15m

# ---- Monitoring footprint ----
# WARNING: the first time you LOWER a retention value on an existing install,
# metrics history above the new ceiling is pruned once, permanently.
#PROMETHEUS_RETENTION_TIME=15d
#PROMETHEUS_RETENTION_SIZE=2GB
# Loki (audit-log) retention is currently fixed at 14 days inside the image —
# this key is reserved and has no effect yet.
#LOKI_RETENTION=14d
#PROMETHEUS_MEMORY_LIMIT=512M
#GRAFANA_MEMORY_LIMIT=256M
#ALERTMANAGER_MEMORY_LIMIT=128M

Audit logging. Out of the box the Relayer keeps an audit trail of every S3 request and feeds it into a small on-box log stack (three extra containers: Loki, Alloy and a log rotator) — open Monitoring in the dashboard to see it. That default costs about 710 MB of disk and 416 MB of RAM, and it manages its own growth (the log file is capped around 600 MB and Loki keeps 14 days). One value in your .env switches the behavior — uncomment RELAYER_AUDIT_MODE and set it to:

• loki — the default described above; leaving the line commented out means exactly this.
• webhook — no extra containers. The Relayer pushes signed audit events straight to your own SIEM or log collector: also uncomment S3GW_AUDIT_WEBHOOK_URL (your HTTPS endpoint) and S3GW_AUDIT_WEBHOOK_SECRET (deliveries are HMAC-signed with it). The secret lives only in your .env — run chmod 600 .env so only your user can read it, and know that anyone who can reach the Docker socket on this machine can read it too (docker inspect shows container environment values).
• off — no audit trail at all; smallest footprint.

Change the mode any time: edit .env, then run docker compose --profile "*" down followed by docker compose up -d (your data is safe — it lives in the named volumes). The --profile "*" down matters: a plain up -d or down leaves the previous mode's audit containers running. Always use RELAYER_AUDIT_MODE — never set COMPOSE_PROFILES directly (an exported COMPOSE_PROFILES in your shell silently overrides the switch).

Everything the Relayer stores — your local database, config, and logs — lives in a Docker‑managed volume called relayer_data, so it survives restarts and updates.

Want the data on a specific disk? Replace the named volume with a folder of your choice by changing only the left side of the relayer's volume line:

    volumes:
      - /mnt/bigdisk/relayer-data:/relayer   # your folder : container path

The right side must stay exactly /relayer — that's where the Relayer looks for its data inside the container. If you change the right side instead, the Relayer starts with a fresh, empty data directory and your buckets and settings seem to vanish (they're safe, just not mounted). Moving an existing install? Stop the container first (docker compose down), move the whole data folder intact, update the left side, then docker compose up -d.

From inside ~/xns-relayer, run:

docker compose up -d

• The first run downloads the image (a few hundred MB) — give it a minute or two.
• When it's done, open http://localhost:8888 in your browser.
• You should land on the XNS Relayer dashboard.

The stack you just started ships ten alert rules already watching the box (disk space, S3 errors and latency, dead services, crash loops and more) plus a bundled Alertmanager that can deliver them to you. Out of the box nothing is delivered — the rules evaluate, but until you set a receiver in your .env they have nowhere to go.

1. Webhook — the primary receiver

Uncomment ALERTMANAGER_WEBHOOK_URL in your .env and point it at anything that accepts a JSON POST (a chat-ops bridge, PagerDuty/Opsgenie webhook ingestion, your own endpoint), then recreate the alertmanager so it picks the value up — restarting is not enough, the config is rendered when the container starts:

docker compose up -d --force-recreate alertmanager

2. Email — an optional second receiver

Uncomment and fill the three ALERTMANAGER_SMTP_* lines (smarthost, from, to — all three together; the AUTH pair only if your relay needs a login), recreate the alertmanager the same way, and the same notifications also go out by mail.

3. Heartbeat — know when the watcher itself dies

If Prometheus or the Alertmanager crashes, no alert can tell you — the messenger is dead. The fix is a dead-man's-switch: the stack sends a check-in every few minutes to an off-box service that pages you when the check-ins stop. Create a free check at Healthchecks.io (or a Cronitor heartbeat monitor), give it an expected period of 5 minutes plus a few minutes' grace, paste its ping URL into WATCHDOG_HEARTBEAT_URL, and recreate the alertmanager. Don't reuse your webhook URL here — a receiver that only reacts to messages it receives can never tell you about silence.

Tuning thresholds and footprint

Every dial lives in the same .env: the ALERT_* lines change when each rule fires (recreate prometheus to apply those), and the retention/memory lines at the bottom bound how much history and RAM the monitoring stack uses. A bad value fails the container start with the validator's message as the last line of docker logs alertmanager (or docker logs prometheus) instead of silently breaking the monitoring — if a container is missing after a change, check those logs, fix the value, recreate again. Mind the retention warning in the .env: lowering retention on an existing install prunes the over-ceiling history once, permanently.

Searching your logs

You don't need to SSH in and grep to chase a fault. In the Relayer dashboard, Monitoring → Log Search runs one search across both your application logs (hostio, gateway, s3gateway, and the Relayer UI process) and the audit trail together — type a term once and matching lines from every service and the audit events come back in one list, newest first. It's additive to the richer Audit Log page, not a replacement. A provisioned Relayer Log Search Grafana dashboard shows recent activity at a glance without writing a query.

Every Relayer image in the compose file is pinned to one build (release-<build>), so your install only changes when you change that file. The dashboard shows a banner when a new build is available. To update, from ~/xns-relayer, keep your current file and fetch the new one:

cp docker-compose.yml docker-compose.yml.previous
curl -fsSL -o docker-compose.yml https://releases.xns.tech/relayer/release/docker-compose.yml
docker compose up -d

To go back to the build you ran before:

cp docker-compose.yml.previous docker-compose.yml
docker compose up -d

Your settings live in .env, which neither step touches, and your data in relayer_data is untouched. If you edited the compose file itself, carry those edits into the new file.

The Relayer reports crashes and errors back to the dev team automatically — nothing for you to set up or configure. If the UI crashes, the server throws, or the S3 gateway returns a 5xx, we see the stack trace, tagged with the exact build you're running.

Still report it in Discord, though. The automatic report tells us what broke; your message tells us what you were doing when it broke — and that's the half that actually helps us fix it.

By default your buckets, objects, database and config all live in a Docker named volume called relayer_data (the relayer_data:/relayer line in the compose file). A normal update keeps that volume, so your data carries across new versions automatically.

Switching from an older bind-mount install? Read this first.

If you previously ran the Relayer with a bind-mount — a line like - ./data:/relayer or - /your/path:/relayer — your data lives in that host folder, not in the relayer_data named volume. If you just adopt the named-volume compose, the Relayer would start against an empty volume and your buckets would look gone. They are not lost — the old data is safe in your folder, just no longer connected.

To prevent silent data loss, the Relayer now refuses to start when it detects an existing database in the old folder while the named volume is empty, and prints migration steps in the logs. Pick one of these:

• Keep your data where it is (simplest). In the compose file, point the volume back at your bind-mount instead of the named volume:

      volumes:
        - /your/path:/relayer        # your existing data folder

  then docker compose up -d.
• Move your data into the named volume. With the stack stopped, copy the old folder's contents into the relayer_data volume, then start normally. Ask your AI assistant (or us in Discord) for the exact copy command for your setup.

Used a custom bind-mount path (not ./data)? Point the safety check at it by adding one line to a .env file next to your compose: LEGACY_DATA_PATH=/your/old/path. On a clean first-time install none of this applies — the check is a no-op, and an empty data folder appearing next to the compose is harmless.

Every shipped release build — expand a version to see what changed.

Stop, but keep your data

docker compose down

Stop and wipe everything for a clean slate

docker compose down -v

The -v flag deletes the relayer_data volume — your local database, config, and any stored objects. Use it when you want to start completely fresh.