A restic REST server written in Go, implementing the official REST backend API (v1 + v2). It features pluggable storage backends and an optional Tailscale listener for zero-config, encrypted connectivity via tsnet.

• Full restic REST API (v1 and v2) compatibility
• Multiple storage backends: Filesystem, S3-compatible, WebDAV, Rclone, SMB/CIFS, NFS, In-Memory
• Multi-repository support via URL path prefixes (e.g. /host-a/backups, /host-b/docs)
• Optional Tailscale integration for TLS without certificates or port forwarding
• ACL engine with per-identity, per-repo-path access control (Tailscale tags, users, hostnames, IPs)
• Web UI with dashboard, repository list, and lock management
• Per-repository traffic statistics (SQLite-backed)
• Prometheus metrics for HTTP, ACL, storage, and per-host observability
• Append-only mode (deletes blocked except for lock removal)
• Data sharding (data/00-ff) for restic-server compatible directory layout with unsharded fallback
• Structured JSON logging with per-request IDs (zap)
• HTTP security response headers
• Graceful shutdown with configurable timeout
• Configuration via CLI flags, config file, or environment variables (with ${VAR} substitution)

This project is in early development and was largely vibe-coded with AI assistance. It may contain bugs or missing edge cases. Pull requests and bug reports are welcome!

Download pre-built binaries and Debian packages from the GitHub Releases page. Available for:

• Linux (amd64, arm64, armv7)
• macOS (amd64, arm64)
• Windows (amd64)

Debian/Ubuntu:

sudo dpkg -i ts-restic-server_*_linux_amd64.deb

docker pull ghcr.io/c-mueller/ts-restic-server:latest

docker run -d \
  -p 8880:8880 \
  -v ./config.yaml:/etc/ts-restic-server/config.yaml:ro \
  -v restic-data:/data \
  ghcr.io/c-mueller/ts-restic-server:latest \
  serve --config /etc/ts-restic-server/config.yaml

Or with Docker Compose — create a directory with compose.yaml and config.yaml:

# compose.yaml
services:
  ts-restic-server:
    image: ghcr.io/c-mueller/ts-restic-server:latest
    ports:
      - "8880:8880"
    volumes:
      - ./config.yaml:/etc/ts-restic-server/config.yaml:ro
      - data:/data
    command: ["serve", "--config", "/etc/ts-restic-server/config.yaml"]
    restart: unless-stopped

volumes:
  data:

# config.yaml
listen: ":8880"
listen_mode: plain
storage:
  backend: filesystem
  path: /data

docker compose up -d

Multi-arch images (amd64 + arm64) are published to ghcr.io/c-mueller/ts-restic-server on every push to master. Tagged releases are available under the corresponding tag name.

See docs/docker.md for more details.

Requires Go 1.27+.

go build -o ts-restic-server .

Version information can be embedded at build time:

go build -ldflags "-X github.com/c-mueller/ts-restic-server/internal/buildinfo.Version=1.0.0" -o ts-restic-server .

# Start with filesystem backend (default)
./ts-restic-server serve

# Start with in-memory backend
./ts-restic-server serve --storage-backend memory

# Start with a config file
./ts-restic-server serve --config config.yaml

# Register the Tailscale node once, then start with the Tailscale listener
echo "$TS_AUTHKEY" | ./ts-restic-server init --auth-key-stdin
./ts-restic-server serve --listen-mode tailscale

# Print version and build information
./ts-restic-server version

# Initialize a repository
restic -r rest:http://localhost:8880/ init

# Initialize a repository under a sub-path (multi-repo)
restic -r rest:http://localhost:8880/my-host/backups init

# Backup
restic -r rest:http://localhost:8880/my-host/backups backup ~/Documents

# With Tailscale
restic -r rest:https://my-restic-server.my-tailnet.ts.net/my-host/backups init

Configuration is loaded with the following priority: CLI flags > config file > environment variables.

Without --config, the first existing file of ./config.yaml, ./config.yml, /etc/ts-restic-server/config.yaml and /etc/ts-restic-server/config.yml is used. If none exists, defaults and environment variables apply. A config file that is given or found but cannot be read is a startup error.

Environment variables use the prefix RESTIC_ with underscores replacing dots (e.g. RESTIC_STORAGE_BACKEND=s3).

See config.example.yaml for all available options:

listen: ":8880"
listen_mode: plain       # "plain" or "tailscale"
append_only: false
log_level: info
shutdown_timeout: 30     # graceful shutdown timeout in seconds

tailscale:
  hostname: restic-server
  state_dir: ./ts-state
  auth_key: ""            # still supported, not recommended: use `ts-restic-server init`
  interactive_login: false

metrics:
  enabled: true
  password: ""            # if set, /-/metrics requires Basic Auth (user: prometheus)
  per_host_enabled: true  # per-identity/repo-path metrics (disable to reduce cardinality)
  acl_enabled: false      # route /-/metrics through ACL instead of Basic Auth

stats:
  enabled: false           # per-repo traffic stats (SQLite)
  db_path: ./stats.db

ui:
  enabled: false           # web UI at /-/ui/
  auth:
    username: ""
    password: ""

storage:
  backend: filesystem     # "filesystem", "s3", "webdav", "rclone", "smb", "nfs", "memory"
  path: ./restic_data
  max_memory_bytes: 104857600  # 100MB for memory backend
  s3:
    bucket: my-bucket
    prefix: ""
    region: eu-central-1
    endpoint: ""
    access_key: ""
    secret_key: ""
  webdav:
    endpoint: ""
    username: ""
    password: ""
    prefix: ""
  rclone:
    endpoint: ""
    username: ""
    password: ""
  smb:
    server: ""
    share: ""
    username: ""
    password: ""
    domain: WORKGROUP
    port: 445
    base_path: ""
  nfs:
    server: ""
    export: ""
    base_path: ""
    uid: 65534
    gid: 65534

ts-restic-server init registers the Tailscale node once; see Tailscale Integration and docs/tailscale.md for its flags.

The default backend. Stores data in the local filesystem with restic's standard directory layout (data/00-ff subdirectories, atomic writes with fsync).

storage:
  backend: filesystem
  path: ./restic_data

Works with AWS S3, MinIO, Hetzner Object Storage, and other S3-compatible providers. Supports custom endpoints and static credentials. If access_key and secret_key are left empty, the standard AWS credential chain is used (environment, shared credentials file, IAM role, etc.).

storage:
  backend: s3
  s3:
    bucket: my-backup-bucket
    prefix: ""                                    # optional key prefix
    region: eu-central-1
    endpoint: https://fsn1.your-objectstorage.com # leave empty for AWS
    access_key: AKIA...
    secret_key: wJal...

Works with any WebDAV-compatible cloud storage: Nextcloud, ownCloud, HiDrive, Box, and others. No rclone intermediary needed.

storage:
  backend: webdav
  webdav:
    endpoint: https://cloud.example.com/remote.php/dav/files/user
    username: myuser
    password: mypassword
    prefix: backups            # optional subdirectory within the WebDAV server

Pure-Go SMB2/3 client — no OS-level mounting required. Supports NTLM authentication, atomic writes via temp+rename, and automatic reconnection on connection loss.

storage:
  backend: smb
  smb:
    server: nas.local
    share: backups
    username: backup-user
    password: ${SMB_PASSWORD}  # env var substitution
    domain: WORKGROUP
    port: 445
    base_path: restic          # optional subdirectory within the share

Pure-Go NFSv3 client using AUTH_SYS authentication — no OS-level mounting required. Supports automatic reconnection on connection loss.

storage:
  backend: nfs
  nfs:
    server: nas.local
    export: /volume1/backups
    base_path: restic          # optional subdirectory within the export
    uid: 1000                  # UID for NFS AUTH_SYS (default: 65534/nobody)
    gid: 1000                  # GID for NFS AUTH_SYS (default: 65534/nogroup)

Proxies all storage operations to a remote restic REST server, such as rclone serve restic. This enables using any of rclone's 70+ supported cloud providers as storage.

storage:
  backend: rclone
  rclone:
    endpoint: http://localhost:8080
    username: ""       # optional basic auth
    password: ""

Useful for testing. All data is lost when the server stops. Enforces a configurable memory cap (default 100MB).

storage:
  backend: memory
  max_memory_bytes: 104857600

The built-in web UI provides a dashboard with repository overview, per-repo traffic statistics, and lock management. It is served at /-/ui/ and uses a dark theme (Bootswatch darkly) with all assets embedded in the binary.

ui:
  enabled: true
  auth:
    username: admin        # optional Basic Auth
    password: secret

Requires stats.enabled: true for traffic statistics display.

When listen_mode is set to tailscale, the server uses tsnet to join your Tailnet and serve over HTTPS with automatic TLS certificates. No port forwarding or manual certificate management required.

listen_mode: tailscale
tailscale:
  hostname: restic-server        # appears as restic-server.my-tailnet.ts.net
  state_dir: /var/lib/ts-restic-server/ts-state   # persistent Tailscale state

The auth key is only needed once, to register the node. Pass it to init instead of storing it in the config:

# key from stdin (not visible in the process list), or TS_AUTHKEY / --auth-key
echo "$TS_AUTHKEY" | ts-restic-server init --auth-key-stdin
ts-restic-server serve

init waits until the node is up, fetches its TLS certificate and exits. It is idempotent: with a valid node identity in state_dir it does nothing and exits 0. Run it as the same user as serve.

serve then needs no auth key. If neither node state nor an auth key exists, it fails with a hint to run init instead of waiting for a browser login (opt back in with --tailscale-interactive-login). tailscale.auth_key in the config file or TS_AUTHKEY still work as before, but keeping the key on the host is not recommended. See docs/tailscale.md for details.

The Tailscale listener always binds to port 443, so restic clients can connect without specifying a port.

The server supports hosting multiple independent repositories under different URL paths. The path prefix is transparently passed to the storage backend:

• S3: path prefix becomes part of the S3 key (e.g. {prefix}/host-a/backups/data/...)
• WebDAV: path prefix becomes a subdirectory on the WebDAV server
• Filesystem/SMB/NFS: path prefix becomes a subdirectory
• Memory: each path prefix gets its own isolated in-memory store

restic -r rest:http://localhost:8880/host-a/daily init
restic -r rest:http://localhost:8880/host-b/daily init
# These are completely independent repositories