Dockhand User Manual

Welcome to Dockhand, a modern, powerful Docker management application. This manual covers all features and functionality to help you get the most out of Dockhand.

Quick start

Get Dockhand running in minutes with Docker:

docker run -d \
  --name dockhand \
  --restart unless-stopped \
  -p 3000:3000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v dockhand_data:/app/data \
  fnsys/dockhand:latest

Or with matching paths (required for stacks with relative file paths):

# Create the directory on the host
mkdir -p /opt/dockhand

# Use matching paths with DATA_DIR
docker run -d \
  --name dockhand \
  -p 3000:3000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /opt/dockhand:/opt/dockhand \
  -e DATA_DIR=/opt/dockhand \
  fnsys/dockhand:latest

Or using Docker Compose:

services:
  dockhand:
    image: fnsys/dockhand:latest
    container_name: dockhand
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - dockhand_data:/app/data

volumes:
  dockhand_data:

Then open http://localhost:3000 in your browser.

Docker socket permissions

Dockhand needs access to Docker to manage containers. By default, the Dockhand container runs as a non-root user, which may not have permission to access the socket on your host system.

If you see a "permission denied" error when trying to add your local environment, you'll need to configure socket access. Here are the options:

# Find the Docker group ID on your host (Linux)
stat -c '%g' /var/run/docker.sock
# On macOS, use: stat -f '%g' /var/run/docker.sock
# Example output: 999

# Run Dockhand with the matching group
docker run -d \
  --name dockhand \
  --restart unless-stopped \
  --group-add 999 \
  -p 3000:3000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v dockhand_data:/app/data \
  fnsys/dockhand:latest

services:
  dockhand:
    image: fnsys/dockhand:latest
    container_name: dockhand
    restart: unless-stopped
    group_add:
      - "999"  # Replace with your host's Docker GID
    ports:
      - "3000:3000"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - dockhand_data:/app/data

volumes:
  dockhand_data:

docker run -d \
  --name dockhand \
  --restart unless-stopped \
  --user 0:0 \
  -p 3000:3000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v dockhand_data:/app/data \
  fnsys/dockhand:latest

services:
  dockhand:
    image: fnsys/dockhand:latest
    container_name: dockhand
    restart: unless-stopped
    user: "0:0"
    ports:
      - "3000:3000"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - dockhand_data:/app/data

volumes:
  dockhand_data:

services:
  dockhand:
    image: fnsys/dockhand:latest
    container_name: dockhand
    restart: unless-stopped
    environment:
      - PUID=1000  # Your user ID (run: id -u)
      - PGID=1000  # Your group ID (run: id -g)
    group_add:
      - "999"  # Docker group GID for socket access
    ports:
      - "3000:3000"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - dockhand_data:/app/data

volumes:
  dockhand_data:

# Get your user and group IDs
id -u  # PUID (e.g., 1000)
id -g  # PGID (e.g., 1000)

# once, on the host - PUID:PGID is what you set on the container
sudo chown -R 1000:1000 /path/to/dockhand/data/stacks

services:
  dockhand:
    image: fnsys/dockhand:latest
    container_name: dockhand
    restart: unless-stopped
    user: "1000:1000"
    group_add:
      - "999"  # Docker group GID for socket access
    ports:
      - "3000:3000"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./data:/app/data  # Must use bind mount, not named volume

volumes:
  dockhand_data:

# Create data directory owned by your user (1000:1000)
mkdir -p ./data
chown 1000:1000 ./data

# Start the container
docker compose up -d

# NOT RECOMMENDED - makes socket accessible to everyone
sudo chmod 666 /var/run/docker.sock

services:
  socket-proxy:
    image: tecnativa/docker-socket-proxy
    container_name: socket-proxy
    restart: unless-stopped
    environment:
      # Required for Dockhand core functionality
      - CONTAINERS=1
      - IMAGES=1
      - NETWORKS=1
      - VOLUMES=1
      - EVENTS=1
      - POST=1
      - DELETE=1
      # Required for dashboard host info and disk usage
      - INFO=1
      - SYSTEM=1
      # Required for vulnerability scanning
      - ALLOW_START=1
      - ALLOW_STOP=1
      - ALLOW_RESTARTS=1
      # Required to view container logs, AND for vulnerability scanning:
      # Dockhand reads the scanner container's output through the logs API
      - ALLOW_LOGS=1
      # Optional: enable for the container terminal, volume browsing,
      # and the in-container file browser (all use the Docker exec API)
      # - EXEC=1
      # With THIS proxy (tecnativa) backups need no extra variable: the helper's
      # archive calls are covered by CONTAINERS=1, and POST=1 lets a non-GET
      # request through. linuxserver/socket-proxy is different - see the note below.
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks:
      - socket-proxy

  dockhand:
    image: fnsys/dockhand:latest
    container_name: dockhand
    restart: unless-stopped
    depends_on:
      - socket-proxy
    ports:
      - "3000:3000"
    volumes:
      - dockhand_data:/app/data
    networks:
      - socket-proxy
      - default

networks:
  socket-proxy:
    internal: true

volumes:
  dockhand_data:

Recommendations by environment

Home lab or private server behind a VPN (Tailscale/WireGuard):

Option 1 (GID matching) or Option 2 (root) is acceptable. The risk is manageable assuming your network is secure and you trust the Dockhand application code.

Production or any internet-reachable host:

Do not expose Dockhand to the public internet - keep it behind a VPN or an authenticating proxy (see the warning under Deployment examples). On top of that network restriction, use a Socket Proxy (Option 4) to limit what Dockhand can do with the Docker socket, so a compromise cannot take the whole host.

Security summary

* Higher than direct socket access, but actual security depends on proxy configuration (which API endpoints are enabled) and container hardening.

Platform notes

Deployment examples

ports:
  - "127.0.0.1:5432:5432"  # Only accessible from the host
  # NOT "5432:5432"         # Exposed on ALL interfaces

Behind a reverse proxy (Traefik)

When running behind Traefik or another reverse proxy, you don't need to expose ports directly:

services:
  dockhand:
    image: fnsys/dockhand:latest
    container_name: dockhand
    restart: unless-stopped
    user: "0:0"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - dockhand_data:/app/data
    networks:
      - proxy  # Must match your Traefik network
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.dockhand.rule=Host(`dockhand.example.com`)"
      - "traefik.http.routers.dockhand.entrypoints=websecure"
      - "traefik.http.routers.dockhand.tls=true"
      - "traefik.http.routers.dockhand.tls.certresolver=letsencrypt"
      - "traefik.http.services.dockhand.loadbalancer.server.port=3000"
      - "traefik.docker.network=proxy"  # Required if container has multiple networks

networks:
  proxy:
    external: true  # Assumes Traefik network already exists

volumes:
  dockhand_data:

With Nginx reverse proxy

Example Nginx configuration for proxying to Dockhand:

server {
    listen 443 ssl http2;
    server_name dockhand.example.com;

    ssl_certificate /etc/ssl/certs/dockhand.crt;
    ssl_certificate_key /etc/ssl/private/dockhand.key;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

With Tailscale (VPN-only access)

The simplest and usually most secure approach: Traefik listens on 80/443, but ports are only accessible within your Tailnet (no public port exposure on the host).

services:
  tailscale:
    image: tailscale/tailscale:latest
    hostname: homelab-gw
    environment:
      - TS_AUTHKEY=${TS_AUTHKEY}
      - TS_STATE_DIR=/var/lib/tailscale
    volumes:
      - tailscale_state:/var/lib/tailscale
      - /dev/net/tun:/dev/net/tun
    cap_add:
      - net_admin
      - sys_module
    restart: unless-stopped

  socket-proxy:
    image: tecnativa/docker-socket-proxy
    environment:
      - CONTAINERS=1
      - SERVICES=1
      - NETWORKS=1
      - EVENTS=1
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks: [socket_proxy]
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true

  traefik:
    image: traefik:v3
    network_mode: service:tailscale
    depends_on: [socket-proxy]
    command:
      - --api.dashboard=true
      - --providers.docker=true
      - --providers.docker.endpoint=tcp://socket-proxy:2375
      - --providers.docker.exposedbydefault=false
      - --entrypoints.web.address=:80
      - --entrypoints.websecure.address=:443
    volumes:
      - traefik_data:/data
    restart: unless-stopped

  dockhand:
    image: fnsys/dockhand:latest
    labels:
      - traefik.enable=true
      - traefik.http.routers.dockhand.rule=Host(`dockhand.homelab-gw.ts.net`)
      - traefik.http.routers.dockhand.entrypoints=websecure
      - traefik.http.routers.dockhand.tls=true
      - traefik.http.services.dockhand.loadbalancer.server.port=3000
    networks: [default]
    restart: unless-stopped
    volumes:
      - dockhand_data:/app/data

networks:
  socket_proxy:
    internal: true

volumes:
  tailscale_state:
  traefik_data:
  dockhand_data:

This works because Traefik "inherits" the Tailscale network via network_mode: service:tailscale, so ports 80/443 are reachable at the Tailscale address (MagicDNS) but not exposed publicly.

Using PostgreSQL database

Dockhand can also use PostgreSQL instead of the default SQLite:

docker run -d \
  --name dockhand \
  --restart unless-stopped \
  --user 0:0 \
  -p 3000:3000 \
  -e DATABASE_URL=postgres://user:password@postgres-host:5432/dockhand \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v dockhand_data:/app/data \
  fnsys/dockhand:latest

The database schema is created automatically on first run. Just ensure the database exists and the user has sufficient privileges.

Managing remote Docker hosts

Dockhand can manage Docker hosts beyond your local machine. There are several ways to connect to remote environments. Configure connections in Settings → Environments.

Hawser is a lightweight agent that enables secure remote Docker management without exposing the Docker API directly. It's especially useful for:

• Hosts behind NAT or firewalls (Edge mode - no inbound ports required)
• VPS or cloud instances with dynamic IPs
• Secure access without exposing Docker TCP port
• Homelab environments across different networks

See the Hawser section for detailed setup instructions.

System requirements

Environment variables

Dockhand can be configured using the following environment variables. All are optional.

Prometheus metrics Since 1.0.37

Dockhand can export a detailed set of Prometheus metrics covering the state of every connected environment and Dockhand's own internals. Point Prometheus at it and build dashboards or alerts in Grafana.

Enabling

services:
  dockhand:
    image: ghcr.io/finsys/dockhand:latest
    environment:
      - EXPORT_METRICS=true
    # ...

Metrics are then served at http://<dockhand>/metrics in the standard Prometheus text exposition format.

Access control

The endpoint follows Dockhand's own authentication state:

• Auth disabled - /metrics is public (like the health endpoint), so a scrape on a trusted network works out of the box.
• Auth enabled - a valid session or an API token is required. Create an API token in Settings and have Prometheus send it as a bearer credential.
• Auth enabled, endpoint left public Since 1.0.55 - set EXPORT_METRICS_PUBLIC=true to keep /metrics reachable without authentication even while the rest of Dockhand stays behind login. This avoids minting an API token (which in the Community edition carries full access) just for a scrape. It opens only /metrics; every other route stays authenticated. Off by default.

Prometheus scrape config

scrape_configs:
  - job_name: dockhand
    metrics_path: /metrics
    static_configs:
      - targets: ['dockhand:3000']
    # Only when Dockhand auth is enabled:
    authorization:
      type: Bearer
      credentials: <your-api-token>

What's exported

All series are prefixed dockhand_. Per-environment series carry env and env_id labels. Collection is cached for ~15 seconds so a tight scrape interval never hammers your Docker hosts, an unreachable environment is skipped rather than failing the scrape, and CPU/memory are reused from the collector (no extra load).

• Environment state - dockhand_env_up (1/0, ideal for alerting), containers by state and health, containers_count, container_restarts_total, updates_available.
• Images & storage - images_count, images_dangling, image_bytes, volumes_count, networks_count, stacks_count.
• Resources - env_cpu_percent, env_memory_used_bytes, env_memory_total_bytes (from the metrics collector).
• Vulnerabilities - dockhand_vulnerabilities{severity}, vulnerabilities_count, images_scanned, plus scan freshness (scan_oldest_age_seconds, scan_avg_duration_seconds) to spot stale or slow scans.
• Activity - container_events_total, container_events_today, and container_events_by_action{action} (start, die, oom, health-change, …).
• Scheduled tasks - schedule_executions{type,status}, plus schedule_last_run_seconds{type} and schedule_last_success_seconds{type} to catch a scheduler that stopped firing or keeps failing.
• Inventory - environments, users, registries, git_repositories, config_sets.
• Internals - build_info, uptime_seconds, hawser_agents_connected + hawser_agent_info + hawser_pending_requests, jobs{status}, scan_queue, vuln_cache_entries, scheduler_running + scheduler_active_jobs, api_tokens{state} (total / expired / never-used), plus the standard Node.js process metrics (heap, event-loop lag, GC, file descriptors).
• Database - database_info{type,version} (engine + version), database_size_bytes, database_rows{table} for high-churn tables, and database_stat{stat} (Postgres: connections / max_connections; SQLite: freelist bytes) for tuning.

Native HTTPS Since 1.0.33

For deployments where a reverse proxy in front of Dockhand isn't viable - bare appliances, hosts with restricted resources, or organizations whose compliance posture requires end-to-end TLS - Dockhand can terminate TLS itself.

When enabled, Dockhand reads your PEM-encoded certificate and key at startup and uses them for all inbound traffic: the UI, the REST API, server-sent event streams (dashboard, container logs), and WebSockets (container terminal, Hawser Edge agents). Bring your own certificate; Dockhand does not generate self-signed certificates and does not run HTTP and HTTPS in parallel.

Docker run

docker run -d \
  -v /host/certs:/etc/dockhand/certs:ro \
  -e HTTPS_MODE=on \
  -e HTTPS_CERT_PATH=/etc/dockhand/certs/cert.pem \
  -e HTTPS_KEY_PATH=/etc/dockhand/certs/key.pem \
  -p 443:3000 \
  fnsys/dockhand:latest

Docker Compose

services:
  dockhand:
    image: fnsys/dockhand:latest
    volumes:
      - /host/certs:/etc/dockhand/certs:ro
    environment:
      - HTTPS_MODE=on
      - HTTPS_CERT_PATH=/etc/dockhand/certs/cert.pem
      - HTTPS_KEY_PATH=/etc/dockhand/certs/key.pem
    ports:
      - "443:3000"

Startup logging

On startup Dockhand logs the certificate's subject, issuer, Subject Alternative Names, and validity window so you can confirm the right file was mounted. A warning is printed if the certificate is within 30 days of expiry, and the process exits if the certificate or key file is unreadable or not a valid PEM:

[HTTPS] mode=on
[HTTPS] cert=/etc/dockhand/certs/cert.pem
[HTTPS] key=/etc/dockhand/certs/key.pem
[HTTPS] ca=(none)
[HTTPS] cert subject: CN=dockhand.example.com
[HTTPS] cert issuer:  CN=Let's Encrypt R3
[HTTPS] cert SAN:     DNS:dockhand.example.com
[HTTPS] cert valid:   Apr 10 00:00:00 2026 GMT → Jul  9 23:59:59 2026 GMT
[HTTPS] cert expires in 64 day(s)
[HTTPS] HSTS enabled: max-age=31536000
Listening on https://0.0.0.0:3000/ with WebSocket

Some certificates carry no subject or issuer name at all - Let's Encrypt's newer profiles identify the host through the Subject Alternative Names alone. Those lines then read (none), which is expected and does not affect serving; the SAN line is what tells you which hostnames the certificate covers.

Hawser Edge agents

If you enable HTTPS with a self-signed or internal CA-issued certificate, Hawser Edge agents connecting in to Dockhand need to trust that certificate. Set CA_CERT on the agent to the path of a PEM file containing your CA (mount it into the agent's container), or skip verification with TLS_SKIP_VERIFY=true (insecure, testing only). Agents must also use a wss:// URL in DOCKHAND_SERVER_URL. See Hawser TLS configuration.

Custom CA certificates

If your OIDC provider, Docker registry, or other service uses a self-signed or internal CA certificate, mount the certificate file and set NODE_EXTRA_CA_CERTS:

Adding a custom CA certificate

Docker Compose:

services:
  dockhand:
    image: fnsys/dockhand:latest
    volumes:
      - ./my_ca.crt:/app/certs/my_ca.crt:ro
    environment:
      - NODE_EXTRA_CA_CERTS=/app/certs/my_ca.crt

Docker run:

docker run -d \
  -v ./my_ca.crt:/app/certs/my_ca.crt:ro \
  -e NODE_EXTRA_CA_CERTS=/app/certs/my_ca.crt \
  fnsys/dockhand:latest

This appends the custom CA to Node.js built-in trusted certificates. All existing public CAs (Let's Encrypt, etc.) remain trusted.

Multiple custom CAs

To trust multiple CAs, concatenate them into a single PEM bundle:

cat ca1.crt ca2.crt > custom-cas.crt

Then mount and reference the bundle:

volumes:
  - ./custom-cas.crt:/app/certs/custom-cas.crt:ro
environment:
  - NODE_EXTRA_CA_CERTS=/app/certs/custom-cas.crt

Enterprise / corporate environments

If your organization manages CA certificates at the OS level (custom base image with certs baked into the system store), you can tell Node.js to use the system OpenSSL CA store instead of its built-in one:

environment:
  - NODE_OPTIONS=--use-openssl-ca

Git operations Since 1.0.27

When NODE_EXTRA_CA_CERTS is set, Dockhand automatically creates a merged CA bundle that combines your custom certificate(s) with the system CA store. This merged bundle is passed to Git via GIT_SSL_CAINFO, so Git stack operations work with both self-signed repositories (e.g. Gitea, Forgejo, GitLab CE on your LAN) and public repositories (GitHub, GitLab.com, Codeberg.org) at the same time.

No additional configuration is needed - just set NODE_EXTRA_CA_CERTS and both HTTPS Git clones and Node.js requests will trust your custom CA alongside all public CAs.

Data storage & volume paths

Dockhand stores all persistent data (database, stack files, git repositories) in its data directory. By default this is /app/data inside the container, but can be configured with the DATA_DIR environment variable.

What's in DATA_DIR

Everything Dockhand persists lives under this one directory:

$DATA_DIR/
├── db/
│   └── dockhand.db        # SQLite database (only when not using PostgreSQL)
├── .encryption_key        # key that decrypts stored secrets (tokens, registry creds)
├── stacks/
│   └── {environment}/{stack}/   # compose + .env for internal & git stacks
├── git-repos/             # cloned git repositories
├── scanner-cache/         # grype / trivy vulnerability DB cache
└── tmp/                   # transient files (e.g. TLS certs during compose ops)

Custom stacks directory Since 1.0.46

STACKS_DIR changes where Dockhand keeps stack files on its own filesystem for local environments (Docker socket or direct connection). By default those files live under DATA_DIR/stacks/{environment}/{stack}/, grouped by environment. Set STACKS_DIR to keep them in a single flat directory of your choosing instead:

docker run -d \
  --name dockhand \
  -p 3000:3000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /opt/stacks:/opt/stacks \
  -e STACKS_DIR=/opt/stacks \
  fnsys/dockhand:latest

With STACKS_DIR set, a stack named web is stored at /opt/stacks/web/ instead of DATA_DIR/stacks/{environment}/web/. Because the layout is flat (no per-environment folder), local stack names must be unique across your local environments - creating a second web is rejected with a clear error.

Recommended setup: matching paths

When deploying compose stacks with relative volume paths (like ./config.toml:/config.toml), the Docker daemon on the host needs to find these files. The simplest and most reliable approach is to use matching paths inside and outside the container:

# Create the directory on the host
mkdir -p /opt/dockhand

# Use matching paths with DATA_DIR
docker run -d \
  --name dockhand \
  -p 3000:3000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /opt/dockhand:/opt/dockhand \
  -e DATA_DIR=/opt/dockhand \
  fnsys/dockhand:latest

With this setup, paths like /opt/dockhand/stacks/mystack/config.toml exist at the same location on both the host and inside the container - no translation needed.

If you already have Dockhand running with a named volume (e.g., started with -v dockhand_data:/app/data), see Moving Dockhand's data to another directory for migration instructions.

Automatic path translation (local only)

When Dockhand runs on the same host where you deploy stacks, it can automatically detect and translate paths by querying the Docker API. So if you use different paths (e.g., -v /opt/dockhand:/app/data), Dockhand will attempt to rewrite relative volume paths at deployment time. This works in most cases, but matching paths is more reliable.

HOST_DATA_DIR fallback

Automatic path detection can fail in certain environments:

• cgroups v2 - Modern Linux distributions (Ubuntu 22.04+, Fedora 31+) use cgroups v2 where container ID detection may not work
• Custom hostname - If you set --hostname on the Dockhand container, the fallback detection method won't work
• Rootless Docker - Container introspection may behave differently
• Podman or other runtimes - Detection is designed for Docker and may not work with alternatives

If you see [Startup] Could not detect host data path in the logs and can't use matching paths, you can manually specify the host path with the HOST_DATA_DIR environment variable:

# Find where Docker stores your named volume
docker volume inspect dockhand_data --format '{{.Mountpoint}}'
# Output: /var/lib/docker/volumes/dockhand_data/_data

# Start Dockhand with HOST_DATA_DIR
docker run -d \
  --name dockhand \
  -p 3000:3000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v dockhand_data:/app/data \
  -e HOST_DATA_DIR=/var/lib/docker/volumes/dockhand_data/_data \
  fnsys/dockhand:latest

This tells Dockhand where the data volume is located on the host filesystem, enabling it to translate relative volume paths in compose stacks correctly.

Remote deployments

For remote Docker environments, relative volume paths need the files present on the remote host. Hawser environments handle this automatically (the agent writes the files). Direct TCP environments can too - set a Remote stacks directory on the environment and Dockhand stages the files onto the remote host before deploying; without it, the files must already exist there (matching paths). Automatic in-place path translation only applies to local socket deployments.

Options for remote deployments with relative paths:

• Use absolute paths that exist on the remote host
• Pre-create files on the remote host before deployment
• Use Git stacks where the repository is cloned directly on the remote host (via Hawser agent)

Credential encryption

Dockhand encrypts sensitive credentials at rest using AES-256-GCM authenticated encryption. This protects registry passwords, Git credentials, SSH keys, OIDC client secrets, LDAP passwords, and other sensitive data stored in the database.

Automatic encryption

Encryption is automatic and transparent - no configuration required for basic usage:

• A random 256-bit encryption key is generated on first startup
• The key is stored in $DATA_DIR/.encryption_key with permissions 0600 (readable only by the owner)
• All sensitive fields are encrypted before being written to the database

Using ENCRYPTION_KEY environment variable

You can provide your own encryption key via the ENCRYPTION_KEY environment variable. This approach offers several advantages:

• Key is stored in your secrets manager (Vault, Docker secrets, etc.) instead of on disk
• Key file is automatically deleted when env var is provided - key never touches disk
• Easier to manage in containerized environments

Migration workflow

If you have an existing Dockhand installation with an auto-generated key file and want to switch to using ENCRYPTION_KEY:

1. Copy your existing key from the key file:
   Bash Copy

   # Read the existing key and encode as base64
   cat /opt/dockhand/.encryption_key | base64

2. Store the key in your secrets manager or Docker secrets
3. Set the environment variable and restart Dockhand
4. On startup, Dockhand detects the matching key and deletes the key file
5. From now on, the key only exists in memory - never on disk

Generating a key

Generate a 32-byte (256-bit) random key encoded as base64:

openssl rand -base64 32

Then provide it when starting Dockhand:

docker run -d \
  --name dockhand \
  -e ENCRYPTION_KEY="your-base64-encoded-key-here" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /opt/dockhand:/opt/dockhand \
  -e DATA_DIR=/opt/dockhand \
  fnsys/dockhand:latest

Encrypted fields

The following sensitive data is encrypted at rest:

• Registry credentials - passwords for Docker registries
• Git credentials - passwords, SSH private keys, SSH passphrases
• Environment settings - Hawser tokens, TLS private keys
• OIDC configuration - client secrets
• LDAP configuration - bind passwords
• Notification settings - SMTP passwords
• Stack secrets - environment variables marked as secrets

Sidebar

The sidebar is Dockhand's main navigation menu - your entry point to the Dashboard, Containers, Logs, Shell, Stacks, Images, Volumes, Networks, Templates, Registry, Activity, Schedules, and Settings. Use the button at the top of the sidebar to collapse it and reclaim screen space.

Customizing the menu

The menu is customizable. Hover over the version number at the bottom of the sidebar and click the pencil (Edit) icon to enter customize mode.

In customize mode you can:

• Reorder items - drag the handle on the left of any item to move it up or down.
• Hide or unhide items - toggle the eye icon on the right of an item.
• Apply - save your changes, or Reset to restore the default menu.

Dashboard

The dashboard provides a real-time overview of all your Docker environments. Each environment is displayed as a tile that can be resized and repositioned to suit your workflow.

Environment tiles

Each environment tile displays key information at a glance:

• Header - Environment name, icon, and connection status
• Container counts - Running, stopped, and total containers
• Resource metrics - CPU and memory usage with progress bars
• Health status - Warning banner for unhealthy or restarting containers
• Activity summary - Today's events and recent activity
• Top containers - Containers sorted by CPU usage (larger tiles)

Status indicators

Tiles display status icons in the header:

Tile sizing

Tiles can be resized to show more or less information. Drag the corner of any tile to resize it.

Layout management

The dashboard provides several ways to organize your tiles:

Auto-layout presets

Use the dropdown in the header to quickly apply preset layouts:

• Compact - All tiles at 1x1 size
• Standard - All tiles at 1x2 size
• Detailed - All tiles at 1x3 size
• Full - All tiles at 2x3 size

Drag and drop

Drag tiles by their header to reposition them. The layout is automatically saved to your browser's local storage.

Label filtering

If you've assigned labels to environments, you can filter the dashboard to show only environments with specific labels. Click the label pills at the top of the dashboard to toggle filtering.

Containers

The Containers page provides comprehensive management of all Docker containers across your environments. You can also organise the list with your own tags - filter, group and colour-code containers by tag.

List view

The container list displays all containers with sortable columns:

Search and sort

Use the search box to filter containers by name, image, or stack. Click column headers to sort. Press Esc to clear the search.

Wildcard search. The * button inside the search box switches it to wildcard matching: * stands for any run of characters (also none) and ? for exactly one, and the pattern has to match a whole name, image, label key or label value. With names like <service>_<role>_<env>, api_*_prod finds every api container in prod and leaves out api_worker_staging. Other examples: web-?, *-cache. A label: filter works as before. The stacks page has the same button, matching a whole stack name or status. The setting is remembered in your browser, separately for containers and stacks; a search opened from a link on another page starts in plain mode.

Bulk operations

Select multiple containers using the checkboxes, then use the bulk action buttons:

• Start - Start all selected stopped containers
• Stop - Stop all selected running containers
• Restart - Restart all selected containers
• Remove - Delete all selected containers

Changelog links Since 1.0.34

When a container has an update available, Dockhand surfaces a release-notes icon next to the image name that links to the project's changelog. See Settings → General → Show changelog links for how the URL is resolved, how to override it with a dockhand.changelog.url label, and how to turn the feature off.

Reverse-proxy URL surfacing Since 1.0.34

If you run Traefik, Pangolin, or caddy-docker-proxy as your reverse proxy, Dockhand reads their labels and surfaces the resulting public URL as a clickable pill next to a container's ports - no dockhand.url label needed. See Settings → General → Honor reverse-proxy labels for the full label vocabulary, the precedence rules, and how to turn it off.

Icons Since 1.0.44

Dockhand can show an app logo next to each container instead of a generic box. When the global setting is on, it matches a logo automatically from the container's image name (for example lscr.io/linuxserver/freshrss resolves to the FreshRSS logo). If the image name itself has no logo, Dockhand tries the container name, then the publisher-qualified name (so apache/superset finds the Superset logo), and finally the publisher itself - but only when the image is that publisher's own product, such as victoriametrics/victoria-logs. A publisher that ships many different apps is never used as a logo, so grafana/promtail keeps the generic icon rather than wearing the Grafana one. Repackagers such as LinuxServer or Bitnami, and OS vendors, are skipped entirely. Matching is deliberately conservative: if it isn't confident, it leaves the generic icon rather than guessing wrong.

Turn it on. App logos are off by default. Enable Settings → General → Use selfh.st icons. The logos come from selfh.st; Dockhand fetches each one once and caches it locally, so your browser never contacts an external CDN. Logos are licensed CC BY 4.0.

Pin a specific icon. Open Edit for a container and click the icon next to its name (Change icon). The picker offers three sources - built-in icons, a search of the selfh.st app logos, or your own uploaded image - the same picker used for stack icons. The choice is remembered per container and per environment, and survives recreation, so an updated or recreated container keeps its icon. An explicit icon always shows, even when the global selfh.st setting is off. Use Clear icon to return to automatic matching.

Container actions

Each container row has action buttons for common operations:

Generate a compose file from a container Since 1.0.44

The container inspect dialog has a Compose tab (the last tab) that turns any running container - however it was created, including ones started outside Dockhand - into a ready-to-use docker-compose.yml service definition. Dockhand reads the container's configuration and writes out the image, ports, volumes, networks, restart policy, healthcheck, capabilities, labels and the rest, skipping the noise a daemon adds automatically (the auto-generated hostname, an inherited entrypoint, and so on) so the result reads like a compose file you would write by hand.

• Environment toggle - User-set only keeps just the variables you set on the container (the ones baked into the image are hidden); switch to All to include every variable.
• Validate runs the same preflight linter used on stacks against the generated file, opening a findings panel beside the editor - errors and warnings grouped by severity, each flagged inline on its line - so you can catch problems (a hard-coded secret, a read-write docker.sock, a :latest tag, a name collision) before you save it anywhere.
• Copy / Download put the compose on your clipboard or save it as a .yaml file.

You can edit the generated compose in place, then save it two ways:

• Save as new stack opens the new-stack dialog pre-filled with the generated compose, so you can deploy it as a fresh stack.
• Append to existing merges the service into one of your managed stacks - pick the stack from the list, review the merged file (the newly added service is highlighted), then save. If a service of the same name already exists in that stack, the added one is given a numbered suffix so nothing is overwritten.

If the container already belongs to a stack, the tab says so - the generated compose is a separate definition you can keep or merge elsewhere, it does not change the running stack.

Creating containers

Click the Create container button to launch a new container. The modal provides all configuration options:

Basic settings

• Image - Select from local images or enter image:tag to pull
• Name - Container name (auto-generated if empty)
• Command - Override the default command
• Working directory - Set the working directory

Port mappings

Map container ports to host ports. Format: host_port:container_port/protocol

# docker-compose.yml
labels:
  - "dockhand.port.8123.url=https://ha.example.com"

# docker run
docker run -l "dockhand.port.8123.url=https://ha.example.com" ...

# docker-compose.yml
labels:
  - "dockhand.url=https://myapp.example.com"

# docker run
docker run -l "dockhand.url=https://myapp.example.com" ...

labels:
  - "dockhand.url=[My App](https://myapp.example.com)"
  - "dockhand.port.8123.url=[Home Assistant](https://ha.example.com)"

Volume mounts

Mount host directories or named volumes into the container:

• Bind mount - /host/path:/container/path
• Named volume - volume_name:/container/path
• Read-only - Append :ro for read-only access

Environment variables

Set environment variables as key-value pairs. Sensitive values are masked in the UI.

Network

Select the network mode:

• bridge (default) - Container gets its own IP on a bridge network
• host - Container shares the host's network stack
• none - No networking
• Custom network - Connect to a user-defined network

Restart policy

Resource limits

• CPU limit - Maximum CPU cores (e.g., 0.5 for half a core)
• Memory limit - Maximum memory (e.g., 512m, 1g)

Logs viewer

The logs viewer provides real-time streaming of container logs with ANSI color support.

Features

• Real-time streaming - Logs appear instantly via Server-Sent Events
• Stopped container support - View logs from stopped, exited, or dead containers
• ANSI color rendering - Full color support for formatted output
• Pause/Resume - Toggle streaming to freeze the view
• Auto-scroll - Automatically scroll to the latest logs
• Download - Export logs as a text file
• Font size - Adjust between 10-18px

Connection status

The status indicator shows the current connection state:

• Live (green pulse) - Streaming active
• Connecting (yellow) - Establishing connection
• Disconnected (red) - Connection lost, will retry
• Paused (amber) - Streaming manually paused

Terminal

Open an interactive terminal session inside a running container.

Configuration

• Shell - Select bash, sh, zsh, or ash
• User - Run as root, nobody, or container default
• Font size - Adjust terminal font size

Keyboard shortcuts

• Cmd + L - Clear terminal
• Cmd + C - Copy selection
• Cmd + V - Paste

File browser

Browse and manage files inside running containers.

Features

• Navigation - Browse directories with breadcrumb trail
• Download - Download files or directories as tar archive
• Upload - Upload files to the container
• File info - View file sizes, types, and permissions
• Ownership - Set the owner when creating or uploading a file, or change it later with the "Change owner" action. Enter a user or user:group (names or numeric ids); leave it blank on create to use the container's default user.

Auto-update

Configure automatic image updates for a container to keep it running the latest version. Enable it per container in the container editor's Settings tab; view and manage all schedules on the Schedules page. This is separate from the on-demand update check - auto-update applies image (digest) updates on its own schedule.

Schedule options

• Daily - Update once per day at a specific time
• Weekly - Update on a specific day and time
• Custom - Use a cron expression for precise scheduling

Vulnerability criteria

When vulnerability scanning is enabled, you can configure vulnerability criteria to control when auto-updates are blocked. This gives you fine-grained control over the balance between staying up-to-date and avoiding newly introduced security issues.

Available criteria

Criteria explained in detail

Never block - Use this when you always want the latest image regardless of vulnerabilities. The scan still runs (for visibility in the UI and notifications), but the update proceeds regardless of results. Suitable for development containers, internal tools, or situations where you trust upstream vendors to quickly patch issues.

Any vulnerability - The strictest option. Blocks the update if the new image contains any vulnerability of any severity (critical, high, medium, or low). Most container images have at least some low-severity vulnerabilities, so this option may block most updates. Use only for zero-tolerance security environments where any known vulnerability is unacceptable.

Critical or High - A balanced approach for production. Allows updates with medium and low severity vulnerabilities but blocks if critical or high severity issues are found. This is the recommended setting for most production workloads, as it prevents serious security issues while allowing routine updates.

Critical only - Blocks only for the most severe vulnerabilities (CVSS 9.0+). High, medium, and low severity issues are tolerated. Use this when you need updates to flow more freely but still want protection against the most dangerous vulnerabilities like remote code execution or privilege escalation.

More than current - A unique comparative approach. Instead of blocking based on absolute thresholds, this compares the total vulnerability count between your current image and the new image. The update is blocked only if the new image has more total vulnerabilities than what you're currently running.

How "More than current" works

When using the "More than current" criteria, Dockhand performs these steps:

1. Scan the new image to count its vulnerabilities
2. Look up the cached scan for your current image (by SHA256 ID)
3. If no cached scan exists, scan the current image on-the-fly
4. Compare total vulnerability counts (summing critical + high + medium + low)
5. Block update only if new_count > current_count

This means an update from 10 vulnerabilities to 10 vulnerabilities is allowed (not worse). An update from 5 to 3 is allowed (improved). Only updates that increase the total are blocked.

Secure update flow

When vulnerability scanning is enabled, Dockhand uses a safe-pull strategy to protect your running containers. The key insight is that your container keeps running the current, known-safe image throughout the entire process. If the new image fails vulnerability checks, it's deleted and your container is never affected.

How protection works

The challenge with Docker updates is that docker pull nginx:latest overwrites your local image tag. If the new image has vulnerabilities and you've already pulled it, your running container's image tag now points to the vulnerable version.

Dockhand solves this with temporary tag protection:

Step-by-step breakdown

1. Registry check - Dockhand queries the registry to check if a newer image digest exists. This is a metadata-only request - no image data is downloaded yet. If no update exists, the process stops here.
2. Pull new image - The new image is downloaded. This overwrites the local nginx:latest tag to point to the new image (this is normal Docker behavior).
3. Restore original tag (safety step) - Immediately after pull, Dockhand re-tags the original image back to nginx:latest. The new image is tagged as nginx:latest-dockhand-pending. Now your running container's image reference is safe again.
4. Scan temporary image - Trivy and/or Grype scan the temporary image for vulnerabilities. This can take 10-60 seconds depending on image size.
5. Security decision:
   • If approved: The new image is re-tagged to nginx:latest, the container is recreated, and the temp tag is cleaned up.
   • If blocked: The temp image is deleted entirely. Your container continues running on the original, safe image as if nothing happened.

Why this approach is safe

The "more than current" criteria

When using the More than current vulnerability criteria, Dockhand performs an additional comparison:

1. Scans the NEW image (as described above)
2. Looks up the cached scan for the CURRENT running image (by SHA256 ID)
3. If no cached scan exists, scans the current image on-the-fly
4. Compares total vulnerability counts: new_total > current_total
5. Blocks update only if the new image has MORE vulnerabilities

This allows updates that reduce or maintain the vulnerability count, while blocking updates that would make things worse.

Environment-wide auto-update

Configure auto-updates for all containers in an environment via Settings > Environments > Updates tab:

• Update checks - Enable scheduled checks for updates across all containers
• Schedule - Set when to check (daily, weekly, or custom cron)
• Auto-update - Enable automatic deployment when updates are found
• Vulnerability criteria - Set blocking rules for the entire environment
• Timezone - Set the local timezone for scheduling (e.g., Europe/Warsaw, America/New_York)

Registry rate limits on scheduled updates Since 1.0.56

A registry can refuse a pull for a moment with toomanyrequests. GitHub Container Registry (ghcr.io, and lscr.io, which is served by it) limits pulls per image owner across all its users, so it throttles most when many installations run their scheduled updates at the same time - on the hour. A scheduled update check or auto-update that hits this retries the pull up to three times, after 1, 5 and 15 seconds or after the wait the registry asks for when that is longer (up to a minute), and only then reports the update as failed.

Schedules always run at the time you set. If your updates often fail this way, pick a minute other than :00, for example 17 4 * * * instead of 0 4 * * *. For linuxserver images, the Docker Hub reference (linuxserver/sonarr instead of lscr.io/linuxserver/sonarr) is the same image under different limits.

Environment variables & labels on update Since 1.0.38

When a container is recreated during an update (manual or automatic), Dockhand keeps the container's existing configuration and only changes the image. Environment variables and labels get special handling so that a new image's updated defaults actually take effect - without discarding anything you set yourself.

For each env variable and label, Dockhand compares the container's value against the old image's value and decides:

Example. An image bakes its version into both an env var and an OCI label, and you run it with one override plus one extra variable:

docker run -d --name myapp \
  -e APP_VERSION=1.0        # baked by the image (you did NOT set this) \
  -e LOG_LEVEL=debug        # you override the image's default (info) \
  -e FEATURE_FLAG=on \      # your own variable, not in the image
  myapp:1.0

The image is updated from 1.0 to 2.0. After the update the container has:

APP_VERSION=2.0     # refreshed  — you never touched it, so it follows the new image
LOG_LEVEL=debug     # kept       — your override wins (never silently reset)
FEATURE_FLAG=on     # kept       — your own variable
# label org.opencontainers.image.version: 1.0 → 2.0   (refreshed)

The update log shows exactly what happened, for example:

Env rebase — adopted from new image: APP_VERSION; kept your overrides: LOG_LEVEL; kept your vars: FEATURE_FLAG
Label rebase — adopted from new image: org.opencontainers.image.version

Scheduled start and stop Since 1.0.55

Start and stop a container on a schedule - for example, stop a media server with loud disks at night and start it again in the morning. Each container can have a scheduled start, a scheduled stop, or both. Every run is recorded on the Schedules page like any other schedule.

Setting a schedule

Open the container editor and go to Settings > Scheduled start and stop. Turn on Start at and/or Stop at and pick when each runs: daily, weekly or a custom cron expression. Save the container to apply it. Changing only the schedule does not recreate the container.

Times are in the environment's timezone (Settings > Environments). A schedule follows the container by name, so it survives an update or a recreate. Removing the container from Dockhand removes its schedule.

A start for a container that is already running, or a stop for one that is already stopped, does nothing and is recorded as skipped. A paused container counts as running: a scheduled stop stops it, a scheduled start leaves it paused. Switching a schedule off on the Schedules page keeps it off when the container's times are edited later.

Setting a schedule with labels

A schedule can also live in the compose file, using two labels. Each takes a time of day (HH:MM, every day) or a five-field cron expression:

services:
  jellyfin:
    image: jellyfin/jellyfin
    labels:
      - "dockhand.stop.at=23:30"          # every day at 23:30
      - "dockhand.start.at=0 7 * * 1-5"   # weekdays at 07:00

Cron fields are minute hour day-of-month month day-of-week; day-of-week runs from 0 (Sunday) to 6 (Saturday). Some examples:

• Labels win. When a container carries either label, its labels set the schedule and the container editor shows it read-only. To change it, change the labels and redeploy. Adding the labels replaces a schedule set in the editor; removing them later does not bring that schedule back.
• Picked up within five minutes. The container editor shows a label schedule as soon as the container exists; the rows on the Schedules page appear at the next label check, which runs every five minutes.
• An invalid value is ignored and listed in the container editor, so a typo cannot stop a container at the wrong time.
• When the container is removed, or deployed again without the labels, its label schedule goes too. Bringing the stack up again brings it back.

Notifications

A scheduled stop or start does not send the ordinary Container stopped or Container started notification. It sends its own events instead, so they can be switched on or off separately in each environment's notification event types:

New event types are not added to notification channels that already exist: tick the three events in each environment's notification settings to receive them.

Permissions

Setting a schedule needs permission to edit schedules and to start and stop containers in that environment. Running one from the Schedules page needs permission to run schedules and to start or stop containers.

Container labels Since 1.0.27

Dockhand supports Docker container labels to control its behavior on a per-container basis. Labels follow an opt-out model - by default, all containers are visible, updatable, and generate notifications. Add labels to change this behavior for specific containers.

Labels override Dockhand's UI settings (label wins). If a container has dockhand.update=false, it will be skipped during auto-updates regardless of any schedules configured in the UI.

What's Up Docker labels are respected too. Since 1.0.52 Dockhand reads the WUD labels that mean the same thing - wud.watch, wud.watch.digest, wud.tag.include and wud.tag.exclude - so a container already carrying them keeps behaving the way it does, with no re-labelling. A native dockhand.* label always wins when both are set. See Respecting What's Up Docker labels for the full mapping.

Available labels

All label values are case-insensitive. You can use: true, TRUE, True, yes, YES, 1 for truthy values, and false, FALSE, False, no, NO, 0 for falsy values.

Usage examples

Docker Compose

services:
  socket-proxy:
    image: tecnativa/docker-socket-proxy
    labels:
      - "dockhand.update=false"    # Never auto-update
      - "dockhand.notify=false"    # Don't send notifications

  reverse-proxy:
    image: traefik:latest
    labels:
      - "dockhand.update=false"    # Manage updates manually

  monitoring:
    image: grafana/grafana
    labels:
      - "dockhand.hidden=true"     # Hide from Dockhand UI

  media:
    image: jellyfin/jellyfin
    labels:
      - "dockhand.stop.at=23:30"          # Stop every night (since 1.0.55)
      - "dockhand.start.at=0 7 * * 1-5"   # Start on weekdays at 07:00

  # Custom URL labels (since 1.0.29)
  nextcloud:
    image: nextcloud:latest
    ports:
      - "8080:80"
    labels:
      - "dockhand.url=https://cloud.example.com"          # Plain URL — shows "cloud.example.com"
      # Or use markdown syntax for a friendly name:
      # - "dockhand.url=[Cloud](https://cloud.example.com)"  # Shows "Cloud"

  homeassistant:
    image: homeassistant/home-assistant
    ports:
      - "8123:8123"
      - "1883:1883"
    labels:
      - "dockhand.port.8123.url=https://ha.example.com"   # Override URL for port 8123

  # Container display order (since 1.0.30)
  nginx:
    image: nginx:alpine
    labels:
      - "dockhand.order=1"    # Show first in the stack
  app:
    image: myapp:latest
    labels:
      - "dockhand.order=2"    # Show second
  redis:
    image: redis:alpine
    # No label - shown after the ordered ones, alphabetically among the rest

  # Custom changelog URL (since 1.0.34) — overrides the automatic GHCR/OCI resolution
  postgres:
    image: postgres:16
    labels:
      - "dockhand.changelog.url=https://www.postgresql.org/docs/release/"

Docker CLI

# Create container with update protection
docker run -d --name socket-proxy \
  --label "dockhand.update=false" \
  --label "dockhand.notify=false" \
  tecnativa/docker-socket-proxy

# Hide a container from Dockhand
docker run -d --name internal-svc \
  --label "dockhand.hidden=true" \
  myapp:latest

Behavior details

• dockhand.update=false - The container is skipped during per-container auto-updates, environment-wide auto-updates, manual batch updates, and update availability checks. The "update available" badge is not shown for these containers.
• dockhand.hidden=true - The container is filtered from the container list API response. It won't appear in the containers page, batch update modal, or any container-related UI. The container still runs normally and can be managed via Docker CLI.
• dockhand.start.at / dockhand.stop.at - The container is started or stopped on that schedule, in the environment's timezone. Each takes HH:MM (every day) or a five-field cron expression. The labels override a schedule set in the container editor, which then shows them read-only; an invalid value is ignored and listed there. Not available for the Dockhand and Hawser containers. See Scheduled start and stop.
• dockhand.notify=false - Notifications (email, Discord, Slack, Telegram, etc.) are suppressed for this container's Docker events. The events are still logged to the activity database for audit purposes.
• dockhand.url - A clickable link with a globe icon is displayed alongside the container's port badges. Accepts two formats:
  • Plain URL: dockhand.url=https://cloud.example.com - displays the URL with the protocol stripped (e.g., "cloud.example.com")
  • Named link: dockhand.url=[Cloud](https://cloud.example.com) - displays the friendly name "Cloud" instead of the URL
  Useful for containers behind a reverse proxy where the actual access URL differs from the host:port. If you already publish Traefik, Pangolin, or caddy-docker-proxy labels, you can skip this - Dockhand picks the URL up from those automatically. See Settings → General → Honor reverse-proxy labels. The explicit dockhand.url still wins when both are present.

• dockhand.port.<hostPort>.url - Overrides the link for a specific port. Clicking it opens the custom URL instead of the auto-generated http://host:port link, and custom port links are visually highlighted to distinguish them from auto-detected links. Accepts the same two formats as dockhand.url:
  • Plain URL: dockhand.port.8123.url=https://ha.example.com - the port badge still shows the port number
  • Named link: dockhand.port.8123.url=[Home Assistant](https://ha.example.com) - the port badge shows the friendly name "Home Assistant" instead of the port number
• dockhand.order - Controls the display position of containers within a stack on the stacks page. Primary sort is by order value (ascending), secondary sort is alphabetical by service name. Containers without the label come after every labelled one, so only label the containers you want to reorder - no need to label everything.

services:
  dockhand-socket-proxy:
    image: linuxserver/socket-proxy:latest
    labels:
      - "dockhand.update=false"   # Dockhand connects through this — never auto-update
      - "dockhand.notify=false"   # Reduce noise from proxy events
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro

  dockhand:
    image: fnsys/dockhand:latest
    environment:
      - DOCKER_HOST=tcp://dockhand-socket-proxy:2375

Checking for updates

Dockhand can tell you when the containers and stacks in an environment have an update available. There are three independent kinds of update, and it is worth understanding the difference:

• Image updates - the tag you run has not changed, but its image has moved. For a floating tag like nginx:latest, or any tag the publisher re-pushes, the digest behind the tag changes. Dockhand compares the digest you run against the registry and flags a pending update. This is the classic behaviour and can be applied automatically.
• Newer version tags Since 1.0.43 - you are pinned to a specific version (postgres:16.2-alpine) and a newer version tag exists upstream (16.15-alpine). Dockhand surfaces it as an advisory badge but never applies it - the version lives in your compose file. See Newer version tags below.
• Moved digests on a pinned tag Since 1.0.54 - you run a tag together with the digest it resolved to (mariadb:13.0.2-ubi@sha256:856f…), which is how a base image patched for a CVE is usually pinned. The tag stays put while the digest behind it moves. Dockhand reports the move with a pin icon on the row but never applies it - pulling that reference returns the manifest you pinned, so the digest in your compose file is what has to change.

Manual and scheduled checks

Run a check on demand with the Check for updates button on the Containers or Compose stacks page. It queries every container in the current environment and flags the ones with an update.

To check automatically, enable a schedule per environment in Settings → Environments → (edit) → Updates. The scheduled check runs on a cron you choose and can either just notify you, or update containers automatically.

• Automatically update containers - when on, containers are recreated with the new image as soon as an image update is found. When off, Dockhand only records the pending update and sends a notification. This applies to image (digest) updates only; newer version tags are always advisory and never applied automatically.
• Block updates with vulnerabilities - when auto-update and a scanner are both enabled, the new image is pulled to a temporary tag, scanned, and only deployed if it passes the chosen vulnerability criteria. Blocked images are discarded and the container is left untouched. See Vulnerability scanning.

Minimum image age Since 1.0.52

A freshly published image is the one most likely to be broken, or to have been pushed from a compromised maintainer account. Dockhand can wait before applying it: set a minimum image age and an automatic update only proceeds once the candidate image is older than that.

The cooldown is off by default (0 hours). Set it globally in Settings → General → Minimum image age, in hours, up to 720 (30 days). An individual environment can override the global value in Settings → Environments → (edit) → Updates, so you can hold production back for three days while staging updates immediately.

When a newer image arrives mid-cooldown

The clock belongs to a specific image, not to the tag. If you check today and find a new image with 71 hours left, and tomorrow the publisher releases another one, tomorrow's check measures the age of that image - the counter goes back up to roughly 70 hours rather than continuing down from 47. The superseded image is no longer a candidate, so its remaining time stops mattering.

That is the intended behaviour: the point is never to deploy an image that was published moments ago, and carrying the old clock forward would do exactly that. It has one consequence worth knowing:

What the cooldown does not hold back:

• Pulling an image yourself - a manual pull warns that the image is younger than the configured age and proceeds. The cooldown governs unattended updates, not your own deliberate action.
• Stack deployments, including scheduled Git deployments - the image a compose file asks for is part of that deployment, and holding it back would leave the stack half-applied.
• Noticing the update - the check still finds it. While the cooldown runs the container is reported as deferred rather than updatable, and Check for updates tells you how many hours remain; the usual update arrow appears once the image is old enough.

To set the period for every environment at once without touching the database, use the MINIMUM_RELEASE_AGE_HOURS environment variable. While it is set, the field in Settings is read-only and shows that the variable owns it.

Seeing what is waiting Since 1.0.55

A container whose update is held by the cooldown shows a muted clock with the hours still to go, rather than the amber update arrow - there is nothing to act on yet, so it reads as deferred, not updatable. The clock appears beside the image name on the Containers list and, on the Compose stacks page, on each held container tile, with the hours next to it (for example 5h). Hovering it says how long is left.

On the Containers list an optional Cooldown column shows the same hours in its own column; enable it from the column menu (the control at the right of the list header). On the Compose stacks page a clock badge with a count sits on the stack row, counting that stack's held containers.

To see only what is waiting, open the status filter and pick Waiting for cooldown. The option appears on both the Containers and Compose stacks pages while anything is in cooldown, and narrows the list to the held containers or stacks. The toolbar also carries a clock counter of how many are waiting, alongside the update and newer-version counters.

Update indicators

When an image update is available, an amber up-arrow appears before the image name on the Containers list, and a toolbar button lets you update all flagged containers at once.

On the Compose stacks page the same arrow aggregates on the stack row (with a count) and repeats on each container tile. Internal and Git stacks can be redeployed to apply the updates; external stacks show the indicator for information only.

The same arrow also appears in a container's details view, both in the header actions and beside the Image field, where clicking it updates that container without going back to the list. The edit dialog shows it beside the image too, for information only.

Indicators persist across a page reload and are refreshed by the scheduled check. Clear them with the dismiss control in the toolbar.

Newer version tags Since 1.0.43

Besides the digest-based image update above, Dockhand can detect when a newer version tag is published for an image you have pinned to a specific version. If you run forgejo:9.0.0 and 16.0.2 exists upstream, or postgres:16.2-alpine when 16.15-alpine is out, Dockhand surfaces it as a badge.

This is advisory only. The version tag lives in your compose file, which Dockhand does not own, so a newer version is never applied automatically - you bump the tag yourself. It is purely a heads-up that a newer release is available.

Enabling detection

Newer-version detection is a global setting. Enable it in Settings → General → Newer version tags, under Check for newer version tags. Both update-check paths - the scheduled check and the manual Check for updates button - read this one setting. The split is deliberate: a per-environment schedule decides whether to check automatically; the global setting decides how versions are read (on/off, maximum bump, flavor matching, prereleases).

Four options control how many suggestions you see:

• Which updates to show - cap the surfaced jump. Patch shows only bug-fix releases (1.4.2 → 1.4.3); Minor adds new-feature releases (→ 1.5.0); Major shows everything, including breaking changes (→ 2.0.0).
• Match the tag flavor - only suggest tags with the same suffix as the one you run. With it on, 1.2-alpine only ever suggests another -alpine tag, never a bare 1.5. This is the most effective filter for images that publish many variants.
• Include prereleases - consider -rc / -beta tags. Off keeps a stable deployment on stable releases.
• Ignore tags older than what you run Since 1.0.52 - a tag is a name, not a date, and some repositories still carry old tags whose names sort high. lidarr:8.1.2135 is really 0.8.1.2135 built in 2021, which outranks a current 3.1.0 on name alone. Off by default: when a project rebuilds all its version lines at once, a genuine newer tag can be built minutes before the image you run and would be skipped. With this on, Dockhand checks when the candidate image was built and skips it when it predates the one you run, then carries on down the list so a genuine newer version below it is still found. It adds a registry lookup for the suggested tag, cached per image, so a repeat check costs nothing. When a build date cannot be read the tag is kept, so a registry that does not answer never hides a real update.

Version comparison is library-free and handles both SemVer (1.2.3) and CalVer (2024.1.3) tags, tolerating a leading v and build suffixes. Floating tags like latest or stable are not versions, so they are skipped entirely - enabling the option on a latest container simply does nothing.

How a newer version is chosen

For each tag the registry offers, Dockhand reads the first dotted-number run as the version (1.25 in v1.25-alpine) and the text around it as the flavor. A candidate has to clear every one of these before it can be offered, in order:

• Same flavor (when "Match the tag flavor" is on). The flavor is the non-numeric skeleton of the suffix: a build variant such as -alpine or -fpm is kept, a trailing commit hash and a linuxserver -lsNNN counter are normalised away. A version baked into a variant token keeps it distinct, so -php8.1 and -php8.2, or -alpine3.19 and -alpine3.20, are different flavors and never offered as an update to one another - a pin to one PHP or Alpine base is never silently moved to a different one.
• Not a prerelease (unless "Include prereleases" is on, or the tag you run is itself a prerelease).
• Not a version-scheme jump. A tag using semantic versions is never offered a calendar-versioned tag: a container on 3.1.0 is not moved to a 2025.1.1 or an Ubuntu-style 24.04, even though those sort higher as plain numbers.
• Strictly newer. The numeric version decides first; when two tags share it, the build/revision suffix breaks the tie numerically, so 2.5.1-ls121 is older than 2.5.1-ls122, 4.2.8-1.1 older than 4.2.8-1.2, and ...-ls9 older than ...-ls10 (not sorted as text). A later build of the same version is therefore recognised as a newer image.
• Within the bump cap (patch / minor / major).

The highest surviving candidate is the suggestion; the rest are listed as skipped. If an image's tags do not follow this shape, teach the parser with a dockhand.tag.transform or dockhand.version.pattern label (see the container label reference).

Filtering candidates per container Since 1.0.52

The settings above apply to every image. When one repository needs an exception, say so on the container with dockhand.tag.include and dockhand.tag.exclude:

services:
  lidarr:
    image: ghcr.io/linuxserver/lidarr:3.1.0
    labels:
      - "dockhand.tag.exclude=^8\\."

Both take a regular expression and are matched unanchored, so write ^ and $ when you mean the whole tag. They only ever narrow what the global settings already offer, and exclude wins when both name the same tag. You do not need to let your own version through the filter: the comparison only ever looks for tags newer than what you run, so filtering it out changes nothing. A pattern that does not compile is ignored, which means a typo costs you the filter and not the update check.

A few patterns are turned down on purpose, and in each case the filter is simply not applied rather than the check breaking: anything over 300 characters, the shapes that make a regular expression backtrack for minutes on a single tag ((a+)+$ and its relatives), and a pattern containing ${…}. That last one matters if your labels came from WUD, which substitutes ${major} and friends into the pattern before using it; Dockhand does not, so such a filter would match nothing at all. Write the value out, for example ^16\. instead of ^${major}\..

A few shapes that come up in practice:

A longer example, pinning a database to one major line while ignoring its release candidates:

services:
  db:
    image: postgres:16.2-alpine
    labels:
      - "dockhand.tag.include=^16\\."
      - "dockhand.tag.exclude=(rc|beta)"

With those two, 16.15-alpine is offered, 17.0-alpine is not, and 16.16-rc1 is dropped even though it matches the include.

Respecting What's Up Docker labels Since 1.0.52

Containers often already carry WUD labels. Dockhand reads the ones that mean the same thing, so a filter you have written once keeps working without being re-labelled:

A native dockhand.* label always wins when both are present, so you can override one container at a time without removing anything.

Two differences are worth knowing, both deliberate:

• Digest watching stays on. WUD leaves it off by default for version tags. Dockhand keeps reporting re-pushed tags unless wud.watch.digest=false or dockhand.watch.digest=false says otherwise, so reading your labels never quietly stops a report you were already getting.
• An include filter narrows, it does not replace. When tag.include is set, WUD switches off its own default filtering. In Dockhand the filter is applied on top of the global settings above, so maximum bump, flavor matching and prereleases still apply. Those are an instance-wide choice, and a label on one container should not be able to widen them. The practical effect is that an include filter brought across from WUD can offer fewer candidates here; if that is not what you want, relax the global setting rather than the label.

A label you have not set never changes what Dockhand already did for you.

Custom tag patterns

Some images use a version scheme the generic parser can't read on its own - most often a date-based tag with a trailing commit hash, like 2024.12.5-a1b2c3d. For those, set a dockhand.version.pattern label on the container to override how Dockhand reads that image's tags. The value is regex: followed by a regular expression with numeric named groups major, an optional minor, and an optional patch:

services:
  app:
    image: example/app:2024.12.5-a1b2c3d
    labels:
      - "dockhand.version.pattern=regex:^(?<major>\d{4})\.(?<minor>\d+)\.(?<patch>\d+)-[0-9a-f]+$"

The captured groups become the version to compare, so 2024.12.6-... is correctly seen as newer than 2024.12.5-.... The override only changes newer-version detection - it never touches the digest-based update check. It is scoped to the one container it is set on; other containers keep using the default parser. An invalid pattern, or one that doesn't match the running tag, safely falls back to the default. See Container labels for the full label reference.

Badges and release notes

When a newer version is found, an amber tag badge showing the target version appears before the image name - on the Containers list, on each container tile inside a stack, and as an aggregate count on the stack row. A tooltip summarises the jump.

Clicking a badge opens a dialog with the full version path (every release between what you run and the newest) and the release notes for each step, rendered from Markdown.

Notes are fetched from the image's source forge when the image carries an org.opencontainers.image.source label pointing at GitHub, or a Gitea / Forgejo instance such as Codeberg (ghcr.io/<owner>/<repo> images resolve to GitHub automatically). Images without a readable source - most Docker Hub base images like nginx - show the version path with a link to the changelog when one can be inferred, but no inline notes.

Badges are cleared with the dismiss control in the toolbar, the same way image-update indicators are, and persist across a page reload. When newer-version detection runs on a schedule, Dockhand sends a Newer version tag notification listing the affected containers - only for versions not surfaced on the previous run, so a daily check does not re-notify the same suggestion. Enable it per environment under the environment's notification event types, in the auto-update group.

Compose stacks

Manage Docker Compose stacks for multi-container applications. Dockhand supports both manually created stacks and stacks deployed from Git repositories. Stacks can also be organised with your own tags - filter, group and colour-code them by tag.

Remote deployment architecture

Dockhand acts as a centralized control plane. When you deploy a stack to a remote node, Dockhand reads the docker-compose.yml file from its own local filesystem (where Dockhand is running) and sends the instructions directly to the remote Docker daemon via the Docker API.

This means:

• Source of truth: Compose files live on the Dockhand node. You don't need to manually sync or copy files to remote servers.
• Deployment: Dockhand handles context switching and payload delivery to the target environment.
• Volumes: If your stack mounts local paths (e.g., ./data:/app/data), those paths refer to the target remote node's filesystem, not Dockhand's. The Docker daemon on the remote node will look for ./data on its own disk.

Summary:

• Stack definitions (YAML): Stored centrally on the Dockhand node
• Data/Volumes: Must exist on the remote node (the target)

You don't need stack definitions on the remote node, but you do need the data directories on the remote node if you are binding host paths.

Stack types

Dockhand categorizes stacks based on how they are managed:

A local stack and a Git stack are not locked in: you can convert a stack between local and Git management at any time without recreating it.

Creating stacks

Click Create stack to open the YAML editor:

1. Enter a stack name (becomes the Compose project name)
2. Write or paste your docker-compose.yml content
3. Add environment variables in the right panel (optional)
4. Optionally check "Deploy immediately" to start the stack
5. Click Create

Environment variables Since 1.0.5

Stack environment variables are managed with a clear separation between regular variables and secrets. The env file (configured per stack - can be .env, .env.production, or any custom path) is the single source of truth for non-secret variables.

Regular variables

• Written directly to the configured env file on disk
• Docker Compose reads them via --env-file at deploy time
• You can edit the file manually (via SSH, git, or the text editor in Dockhand)
• Comments and formatting are preserved
• Not stored in the database - the file is the only copy

Secret variables

Variables marked as secret are stored encrypted in the database and injected at runtime - never written to disk. Values are masked (***) after saving. See Secrets for full details on storage, injection, and important caveats.

Built-in Docker and Compose variables

Docker and Docker Compose define a set of well-known environment variables that are read implicitly from the shell at deploy time. You can reference them in your compose file with ${VAR} syntax (for example ${COMPOSE_PROJECT_NAME}) without defining them in the env panel - the editor recognises them and will not flag them as missing.

The following variables are treated as built-ins:

Reference: Compose envvars, Docker CLI environment variables.

services:
  app:
    image: myapp:latest
    environment:
      - MY_VAR=${MY_VAR}
      - DATABASE_URL=${DATABASE_URL}
      - API_KEY=${API_KEY}

Redeploy options

The redeploy menu next to a stack, and next to Save & redeploy and Create & start in the editor, chooses how docker compose up runs. The command it will run is shown under the options.

• Pull images - adds --pull always, so every image is pulled again before the stack starts. This overrides each service's pull_policy.
• Respect pull_policy Since 1.0.56 - available with Pull images. Instead of --pull always, Dockhand first runs docker compose pull, which follows each service's pull_policy: a service set to never or build, or to missing with the image already present, is not pulled. A service with a build: section and no pull_policy is still pulled when its tag exists in a registry. If an image cannot be pulled, the failure is written to the log and the deploy continues with the images that are present; one image that cannot be pulled can also stop the pulls of the other services, which then keep their current images. Use it for stacks that build or tag their own images, for example localhost/myapp with pull_policy: missing or never, which a registry pull can never find.
• Build images - adds --build, so services with a build: section are rebuilt.
• Pull base images Since 1.0.56 - available with Build images. A normal build reuses the base image already on the host, so FROM nextcloud:35-apache keeps building against the old copy and a new upstream release never arrives; Pull images does not help, because it pulls only the services' own images. With this option Dockhand runs docker compose build --pull, which pulls a newer version of each Dockerfile's FROM image, and then starts the stack without building again. When Pull images is also ticked, the images are pulled before the build and services that are built are skipped, so a pull never replaces an image that was just built. On a Hawser environment it needs agent v0.2.51 or newer; an older agent builds with the base images it has and the log shows a warning. On Hawser the pull before the build follows each service's pull_policy even when Pull images would force it, and a service with pull_policy: build is built once more when the stack starts, from the base images already on the host.
• Force recreate - adds --force-recreate, so every container is recreated even if nothing changed.

Live deploy console Since 1.0.47

When you deploy a stack - Save & redeploy in the editor, Deploy on a Git stack, or a stack start/stop/down - the compose output streams into a console at the bottom of the editor as it happens, instead of appearing all at once when the operation finishes. You watch each Container ... Recreate / Started line arrive in real time, so a slow pull or a stuck depends_on health check is visible while it is happening rather than after.

The console header shows what is running and a live status - a spinner while in progress, then a green success or red failure line when it ends. The toolbar lets you adjust font size, toggle line wrapping, search, and copy or download the full log. When a deploy fails, the reason is written on the last line of the same log - there is no separate error dialog to chase.

Deploy history Since 1.0.47

Every deploy is recorded. Open a stack and switch to the Deploys tab to see its full run history - the tab label carries a success / failure tally (a green success count and a red failure count) so you can tell at a glance how a stack has been behaving.

Each row summarises one deploy:

• Status - success or failure.
• When and Duration - when the deploy ran and how long it took.
• Trigger - what started it: a manual deploy, a scheduled sync, or a webhook.
• Summary - what changed (created / recreated / started counts and whether anything was built), the deploy options used (Pull, Build, Force recreate), and, for a failed deploy, the reason.

Expand a row to see the containers it touched, the build result, who or what triggered it, and the complete log for that run - the same searchable, copyable console as a live deploy, kept so you can review a deploy long after it finished.

Because the history covers every trigger, it also captures deploys that failed before compose even ran - for example a Git clone or fetch error on a scheduled sync - each with its reason in the log, so a stack that quietly stopped updating leaves a visible trail.

Stack icons Since 1.0.44

Give a stack its own icon so it stands out in the list. Open the stack and click the icon next to its name (Change stack icon) to open the picker. The choice is saved per stack and per environment, and a set stack icon always shows regardless of the global Use selfh.st icons setting. Use Clear icon to go back to the default.

The picker has three tabs:

Compose validate Since 1.0.43

Compose validate is a preflight linter for your compose file. Click Validate above the editor and Dockhand checks the file for problems before you deploy, showing each issue inline in the editor and in a panel beside it.

It draws on two independent sources:

• Docker's own validator. Dockhand runs docker compose config on the file, so any schema or syntax error Docker itself would reject (a wrong field type, an unknown key it drops, a bad interpolation, an include:/extends: problem) is surfaced with its line. This is the authoritative "will it even deploy" check. config only renders the file - it does not talk to any Docker daemon - so it runs the same way for local, Direct TCP and Hawser environments.
• Dockhand's own rule set. A catalog of checks that go beyond what docker compose config can know - a host port already taken by another stack on the same environment, a database exposed on all interfaces, a hard-coded secret in environment:, a typo in a key that Docker would silently ignore, a writable mount of a host system path, and more.

Findings and severities

Each finding has a severity and, where the problem points at a specific line, an editor marker (a gutter icon plus a faint line tint). Click a marker to jump to that finding in the panel, or click a finding to jump to its line in the editor.

• Errors - the file will not deploy as-is, or a definite mistake (duplicate host port, a service that depends on a service that does not exist, an undefined network or volume reference, a read-write mount of the Docker socket or a host system path).
• Warnings - risky or fragile, but valid (a :latest / untagged image, a privileged container, network_mode: host, a near-privileged cap_add, a database port published on all interfaces, a hard-coded secret value, a typo`d key).
• Suggestions - advisory nudges (the obsolete top-level version: key, a service with no restart: policy).

One-click fixes

Where a fix is completely unambiguous, the finding shows a small Fix button that rewrites the compose in place and re-validates, so the finding drops off the list. Fixes are only offered when there is exactly one correct edit - a typo whose intended key is known, the obsolete version: line, a database port to bind to 127.0.0.1, or a missing restart policy. Problems that need a real decision (which port to change, whether a network should be external, which image tag to pin) are never auto-fixed - they show the problem and a hint instead.

The rule catalog

Dockhand's rules are a plugin catalog. Each rule has a stable id (shown on every finding, e.g. DUPLICATE_HOST_PORT) and a default severity. The check is advisory - Compose validate never blocks a deploy, it only reports. The built-in rules:

On top of these, any schema or syntax error from docker compose config appears as a COMPOSE_SCHEMA_ERROR finding. Validation is read-only - it inspects the compose text and, for the context-aware rules, the target environment's live containers, networks and volumes, and never changes anything until you click a Fix or deploy.

Secrets

Dockhand separates regular environment variables from secrets. Regular variables live in .env files on disk, while secrets are stored encrypted in the database and injected at runtime. This ensures sensitive values like database passwords, API keys, and private tokens are never exposed in plain-text files.

Secrets can also come from an external secret store (HashiCorp Vault, 1Password, Bitwarden, Infisical, Doppler, and more) instead of being typed into Dockhand - see External secrets.

Secrets vs regular variables

Marking a variable as secret

In the environment variables editor, click the key icon next to any variable to toggle it as a secret. The key icon turns amber to indicate the variable is marked as secret.

You can also mark variables as secret in the raw text editor mode. When switching between form and text views, secret flags are preserved.

How secrets are stored

• Encrypted with AES-256-GCM in the Dockhand database
• Never written to any file on disk - not to .env, not to .env.dockhand, not to temporary files
• Values are masked (***) in the UI after saving - they cannot be retrieved or viewed again. To change a secret, you must enter a new value
• The encryption key is automatically derived from your Dockhand instance

How secrets are injected

When you deploy a stack, Dockhand injects secrets as shell environment variables passed to the docker compose process. The .env file on disk contains only regular variables - secrets exist only in the process environment for the duration of the deployment.

# Conceptual example — this is what Dockhand does internally:
DB_PASSWORD=secret123 API_KEY=abc docker compose --env-file .env up -d

The injection mechanism differs slightly depending on the stack type and deployment target:

Making secrets available inside containers

Secrets (and all environment variables) are injected into the docker compose process, not directly into containers. This means they are available for variable interpolation (${VAR} syntax) in your compose file, but they are not automatically visible inside containers.

To pass secrets into your containers, you must explicitly reference them in the environment: section of your compose file:

services:
  app:
    image: myapp:latest
    environment:
      - DB_PASSWORD=${DB_PASSWORD}    # Secret from Dockhand
      - API_KEY=${API_KEY}            # Secret from Dockhand
      - LOG_LEVEL=${LOG_LEVEL:-info}  # Regular var with default

The environment: section is only needed to pass a value into a container. ${VAR} interpolation of secrets works anywhere in the compose file - for example in volume driver_opts, labels, or image tags:

volumes:
  share:
    driver: local
    driver_opts:
      type: cifs
      device: //nas.local/share
      o: username=${CIFS_USERNAME},password=${CIFS_PASSWORD}  # Secrets from Dockhand

When secrets survive, and when they do not

Regular variables are never affected - they live in the .env file on disk, which Docker Compose reads on every run, so they are resolved the same way no matter who recreates the container.

Recovering a stack whose secrets were emptied

Open the stack in Dockhand and click Deploy. The secrets are injected from the database and the container is recreated with real values. To avoid the problem in the first place, deploy stacks that use secrets from Dockhand rather than from a shell, and point any external update tooling at Dockhand's own update instead.

Why this happens

Secrets are never written to the .env file - that is what keeps them off disk. They exist only in the environment of the docker compose up that Dockhand runs, and from there they are baked into the container that command creates. Anything that reuses that container keeps them; anything that builds a new one needs the same environment again.

Troubleshooting

Adopting untracked stacks Since 1.0.7

Import Docker Compose stacks from your filesystem. This converts Untracked stacks (where Dockhand doesn't know the compose file location) into Internal stacks that can be fully managed. This is useful for adopting stacks created via CLI or stored in custom locations.

How to import

1. Click the Import button on the Stacks page
2. Browse to a directory containing compose files
3. Either click a compose file directly to import it, or click Scan this folder to find all stacks
4. Select which stacks to import and click Import

Recent locations

The import dialog remembers recently browsed locations in the left sidebar. The first location becomes the default starting point when opening the dialog.

Scan results

When scanning a folder, Dockhand recursively searches for Docker Compose files (docker-compose.yml, compose.yml, etc.) and presents them for import:

• Compose name - If the compose file defines a top-level name property, it is used as the stack name instead of the directory name Since 1.0.28
• Service count - Number of services defined in the compose file
• Running indicator - Shows if a stack is already running on the current environment
• .env detection - Automatically detects associated .env files

Running stack detection

When scanning, Dockhand uses the compose file's name property (if defined) or the directory name as the stack name. Running stacks are identified by matching this project name against the com.docker.compose.project container label. This ensures stacks started outside Dockhand with a name property are correctly detected as running.

• Running stacks display a green indicator with the container count
• Running stacks are not pre-selected for import (they're likely already managed)

Relative volume paths Since 1.0.8

Imported stacks with relative volume paths (like ./data:/app/data) work correctly because Dockhand uses the original compose file location as the working directory when deploying.

For example, if you import a stack from /opt/myapp/docker-compose.yml with:

services:
  app:
    image: myapp:latest
    volumes:
      - ./data:/app/data    # Resolves to /opt/myapp/data
      - ./config:/app/config

The relative paths ./data and ./config will resolve relative to /opt/myapp/, not Dockhand's data directory.

Mounting external stack directories

To import stacks from directories outside the container, you need to mount those directories as volumes.

For example, if your stacks are in /opt/stacks on the host:

docker run -d \
  --name dockhand \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v dockhand_data:/app/data \
  -v /opt/stacks:/opt/stacks \
  -p 3000:3000 \
  fnsys/dockhand

You can mount multiple directories if your stacks are spread across different locations:

docker run -d \
  --name dockhand \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v dockhand_data:/app/data \
  -v /opt/stacks:/opt/stacks \
  -v /home/user/projects:/home/user/projects \
  -v /srv/docker:/srv/docker \
  -p 3000:3000 \
  fnsys/dockhand

Git integration

Deploy stacks directly from Git repositories with automatic synchronization. Configure Git credentials in Settings → Git.

Triggers: Scheduled auto-sync • Webhook from CI/CD • Manual deploy button

Configuration

• Repository - Select from configured Git repositories or add a new one
• Branch - Target branch to track. Pick one from a live list of the repository's branches (fetched from the remote), or type a name. This is a per-stack override Since 1.0.44: two stacks can track different branches of the same repository, and changing it re-deploys the stack from the new branch.
• Compose file path - Path to the compose file (default: docker-compose.yml)
• Context directory - Working directory for Docker Compose, relative to the repo root (see Context directory)
• Auto-sync - Enable automatic sync on a schedule (see Schedules)
• Schedule - Cron expression for auto-sync timing

Deploy options Since 1.0.23

Each git stack has three per-stack deploy options that control how Docker Compose runs during deployment:

Deployment behavior

Git stacks use intelligent deployment that only redeploys when necessary:

What counts as a change? Dockhand checks if any files in the stack's compose directory changed (using git diff). Only changes to files in that directory trigger a redeploy:

• Changed compose file - redeploys
• Changed .env file in compose directory - redeploys
• Changed config files, scripts in compose directory - redeploys
• Changed files elsewhere in repo - skipped (not in compose directory)
• No new commits - skipped

Directory deployment

When deploying a Git stack, Dockhand clones the entire directory containing your compose file, not just the compose file itself. This means:

• Any .env files referenced by env_file: directives are automatically available
• Config files, secret files, and other supporting files are included
• Multi-file compose setups (compose.yaml + compose.override.yaml) work out of the box

Clone directory location

Git repositories are cloned into the git-repos/ subdirectory inside Dockhand's data directory. Each stack gets its own directory organized by environment name:

$DATA_DIR/git-repos/{environmentName}/{stackName}/

For example, with DATA_DIR=/opt/dockhand, an environment called production, and two git stacks:

/opt/dockhand/
└── git-repos/
    └── production/
        ├── webapp/               # stack "webapp" on "production"
        │   ├── docker-compose.yml
        │   ├── .env
        │   └── config/
        └── monitoring/           # stack "monitoring" on "production"
            └── docker-compose.yml

Context directory Since 1.0.28

By default, Dockhand uses the compose file's parent directory as the working directory for Docker Compose. The Context directory field lets you override this to a wider directory (relative to the repo root), so files outside the compose file's folder become available for volume mounts, build contexts, and env_file: references.

Example: your repo has shared config files referenced by multiple stacks:

my-repo/
├── shared/
│   ├── certs/
│   │   └── ca.pem
│   └── config.toml
├── apps/
│   ├── webapp/
│   │   └── compose.yaml      ← volumes: - ../../shared/config.toml:/config.toml
│   └── api/
│       └── compose.yaml
└── monitoring/
    └── gotify/
        └── compose.yaml

Without a context directory, Dockhand only copies apps/webapp/ - the ../../shared/ reference breaks because those files aren't included. Setting Context directory to . (repo root) makes the entire repository available:

You can also set it to a subdirectory. For example, if your stacks share a deploy/ folder:

my-repo/
├── deploy/
│   ├── shared-config.env
│   ├── webapp/
│   │   └── compose.yaml      ← env_file: ../shared-config.env
│   └── api/
│       └── compose.yaml
└── src/
    └── ...

This copies the entire deploy/ directory, making shared-config.env available via the relative path ../shared-config.env from the compose file's location.

How .env files work

Dockhand automatically detects a .env file in the compose directory and passes it to Docker Compose via --env-file. No configuration is needed for the standard .env file.

Docker Compose uses environment files in two ways:

• Variable substitution - Replaces ${VAR} placeholders in the compose file (e.g., image: ${REGISTRY}/app)
• Container environment - The env_file: directive can reference any file (e.g., env_file: prod.env) to pass variables to containers at runtime

The Additional env file field is for non-standard env file names (e.g. .env.production, .env.staging). If configured, it is added as a second --env-file and its values override the default .env.

Environment variable overrides

The right panel in the git stack editor lets you define environment variables that override values from the repository's env files during deployment. This is useful for setting deployment-specific values (like server URLs, ports, or feature flags) without modifying the repository. Secrets are never written to disk - they are stored in the database and injected via shell environment at deploy time.

How it works

At deploy time, Dockhand chains --env-file flags in order of precedence:

1. .env in the compose directory (auto-detected, base defaults)
2. Additional env file if configured (e.g. .env.production)
3. A generated .env.dockhand override file (your edits from the right panel)

Docker Compose applies env files in order, so later files override earlier ones. This means your overrides always win over repository defaults.

Complete example with all three env files:

docker compose -p mystack -f docker-compose.yml \
  --env-file .env \
  --env-file .env.production \
  --env-file .env.dockhand \
  up -d --remove-orphans --force-recreate

Secret variables

Variables marked as secret are stored encrypted in the database and injected via shell environment at deploy time - never written to any file on disk. See Secrets for full details on storage, injection, and what happens when a container is recreated outside Dockhand.

What gets saved

Only variables that differ from the repository's env file (or are new) are stored in the database. Unchanged values are not saved, so if the repository updates a default, your stack picks up the new value automatically.

How overrides reach your containers

Variables set in the overrides panel (and secrets) are injected into the shell environment of the docker compose process. This means they are available for compose file interpolation using ${VAR_NAME} syntax, but they are not automatically passed into containers.

To make Dockhand-managed variables available inside your containers, you must explicitly reference them in your compose file:

Option 1: Using the environment: section (recommended)

services:
  web:
    image: myapp:latest
    environment:
      - SECRET_KEY=${SECRET_KEY}
      - DATABASE_URL=${DATABASE_URL}
      - DEBUG=${DEBUG:-false}

Option 2: Reference .env.dockhand in env_file:

Dockhand writes non-secret overrides to .env.dockhand. You can reference it directly in your compose file:

services:
  web:
    image: myapp:latest
    env_file:
      - .env            # Base values from repo
      - .env.dockhand   # Dockhand overrides (later files win)

Note: Secrets are never written to disk, so they won't appear in .env.dockhand. Use environment: with ${VAR} syntax for secrets.

Force recreate behavior

When environment variables change in the repository, Docker Compose doesn't automatically detect this (it only detects compose file changes). Dockhand handles this by using --force-recreate whenever git changes are detected in the compose directory:

Convert between local and Git Since 1.0.57

A stack managed locally and a stack deployed from a Git repository can be switched to the other kind without deleting and recreating it. The containers keep running; only how Dockhand manages the stack changes.

Local to Git. Open a local stack in the editor and choose Convert to Git from the actions menu in the top-right corner. Dockhand asks for the repository (an existing one or a new URL, branch and credential), the compose path and optional env file path inside the repo, and the usual auto-update, webhook and build options. The stack's current environment variables are carried over, and you can deploy from the repository right away.

Git to local. Open a Git stack in the editor and choose Convert to local from the same actions menu. Dockhand writes the stack's last-deployed compose and .env into its managed directory and stops tracking the repository, so you can edit the files directly in Dockhand. The repository definition and its auto-sync are removed; the cloned copy is deleted, but the running stack and its data are untouched.

Webhooks

Trigger stack deployments from external services like GitHub, GitLab, or CI/CD pipelines.

Push to repo → webhook triggers → Dockhand pulls changes → deploys updated stack

Webhook URL

Each Git stack gets a unique webhook URL:

https://your-dockhand.com/api/git/stacks/{id}/webhook

Supported methods

• POST - Standard webhook with signature verification (GitHub, GitLab, CI/CD)
• GET - Simple trigger with secret as query parameter

Webhook secret

For security, configure a webhook secret. Dockhand supports three authentication methods:

GitHub

In your GitHub repository, go to Settings > Webhooks > Add webhook. Paste the webhook URL, set content type to application/json, and enter your secret. GitHub sends the X-Hub-Signature-256 header automatically.

GitLab

In your GitLab project, go to Settings > Webhooks. Paste the webhook URL and enter your secret as the Secret token. GitLab sends the X-Gitlab-Token header automatically.

Gitea / Forgejo

In your Gitea/Forgejo repository, go to Settings > Webhooks > Add webhook > Gitea. Paste the webhook URL into Target URL and enter your secret in the Secret field. Leave other settings at their defaults.

Gitea/Forgejo sends the X-Hub-Signature-256 header (same format as GitHub), so signature verification works automatically.

CI/CD pipelines

You can trigger webhooks from any CI/CD pipeline using curl. Store the webhook secret as a CI/CD variable (e.g. DOCKHAND_WEBHOOK_SECRET).

GitLab CI (recommended - uses native GitLab token header):

deploy:
  stage: deploy
  script:
    - |
      curl -sf -X POST "https://dockhand.example.com/api/git/stacks/42/webhook" \
        -H "X-Gitlab-Token: $DOCKHAND_WEBHOOK_SECRET" \
        -d '{}'

GitHub Actions / generic CI (HMAC-SHA256 signature):

PAYLOAD='{}'
SIGNATURE="sha256=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$DOCKHAND_WEBHOOK_SECRET" | awk '{print $NF}')"
curl -sf -X POST "https://dockhand.example.com/api/git/stacks/42/webhook" \
  -H "Content-Type: application/json" \
  -H "X-Hub-Signature-256: $SIGNATURE" \
  -d "$PAYLOAD"

Simple GET (easiest, secret visible in URL):

curl -sf "https://dockhand.example.com/api/git/stacks/42/webhook?secret=$DOCKHAND_WEBHOOK_SECRET"

Tags Since 1.0.49

Tags are Dockhand's own labels for organizing containers and stacks - separate from Docker labels. Give a tag a name, a colour and an icon, then attach it to any container or stack to filter, group and colour-code them across the grid. Tags work the same way on the Containers and Compose stacks pages.

Creating tags

Manage the tag catalog under Settings → Labels and tags. Type a name, pick a colour and an optional icon, and press Add tag. Existing tags are listed below with edit and delete buttons. A tag name is at most 32 characters and is unique in the catalog (case-insensitive), so re-adding a name just returns the existing tag.

Assigning tags

With Inline tag editing turned on (see below), each container and stack row shows a small tag button. Click it to open a picker, search the catalog, and toggle tags on or off for that row. Administrators can also create a new tag straight from the picker by typing a name that doesn't exist yet and choosing a colour and icon.

Tags from container labels Since 1.0.51

A container can name its own tags with the dockhand.tags label. The labels are read wherever containers and stacks are listed, so this works for anything the daemon runs - including containers and stacks Dockhand never deployed, started with docker run or with docker compose from a terminal.

Docker CLI

docker run -d --name jellyfin \
  --label "dockhand.tags=media, prod" \
  jellyfin/jellyfin

Docker Compose

Compose keeps project-level labels off the containers, so the label goes on the services. A stack shows the tags of all its services together:

services:
  web:
    image: nginx:alpine
    labels:
      dockhand.tags: "frontend, prod"
  db:
    image: postgres:16
    labels:
      dockhand.tags: "prod"

Here web shows frontend and prod, db shows prod, and the stack itself shows frontend and prod - the union of what its services ask for. To tag a whole stack with one word, put the label on any one service.

Spacing around the commas is ignored and repeats are collapsed, so "prod, web" and "prod,web" are the same. Tags named by a label sit alongside the ones assigned in Dockhand - neither replaces the other - and they filter, group and colour exactly like any other tag.

Choosing a colour and an icon

An entry can ask for a colour, and an icon after it, separated by colons. Both are optional:

dockhand.tags=prod, media:amber, backup:cyan:database

Here prod takes the default look, media is amber, and backup is cyan with a database icon. To set an icon without naming a colour, leave the middle empty: backup::database.

The catalog wins. If the name matches a tag under Settings → Labels and tags, that tag is drawn the way you defined it there and the colour and icon in the label are ignored. A catalog tag is shared by the whole instance, so one container cannot repaint it for everyone. The colour and icon in a label apply only to tags the catalog does not have.

A colour or icon name Dockhand does not recognise is ignored and the tag still appears with its default look - a typo costs you the colour or the icon, never the tag.

Filtering, grouping and colouring

The All tags dropdown at the top of the Containers and Stacks pages controls how tags shape the grid. Its settings section is open by default and collapsible.

• Group by tag - partition the rows into a group per tag, or per unique tag combination (a container tagged prod + devel forms its own group, distinct from just prod). Untagged rows collect in their own group.
• Color group bands - draw a coloured band down the left of each group in the tag's colour.
• Show tags - show the tag chips on each row.
• Inline tag editing - show the per-row tag button used to assign tags.
• Match any / all - when you select tags to filter by, choose whether a row must match any of them or all of them.
• Untagged - the tag list ends with an Untagged entry that filters to the rows with no tag. On its own it shows only untagged rows; combined with tags under any it adds the untagged rows to the selected tags.

These view preferences are remembered per browser, separately for the Containers and Stacks pages.

Grouped by tag, the Containers page reads like this - a group per tag and per tag combination, coloured bands down the left, and the tag chips on each row:

The Compose stacks page works the same way, including the inline picker for assigning tags to a stack:

Secrets management Since 1.0.42

Dockhand can pull deploy-time secrets from an external secret store and inject them into a stack, so a password never lives in your compose file or a plaintext .env on disk. Secrets are resolved when the stack is deployed, started, recreated, or a service is updated, and are passed to docker compose through the shell environment - exactly like Dockhand's built-in secrets. Nothing is written to disk. Values pulled from a provider are also masked (***) in the container inspect view, so they are not exposed there in plaintext.

Dockhand fetches the value from the provider when the stack deploys, keeps it only in memory, and passes it to docker compose through the shell environment. It is never written to the on-disk .env, never stored in the container image, and never committed anywhere.

Secrets are re-resolved on deploy, start, recreate, and service update - every time the stack is (re)brought up. A plain restart reuses the container's existing environment and does not re-resolve.

Supported providers

Configure providers under Settings → Secrets, then bind one to a stack using the Secret provider dropdown in the stack editor (next to the environment variables, above the compose/env panes). It defaults to None - disabled.

If most of your stacks use the same provider, you can save that choice instead of repeating it. On any provider card under Settings → Secrets, press Make default: that provider is then preselected whenever you create a new stack. You can still pick a different provider, or None, on any individual stack - the default only sets the starting value. Press the button again on the starred provider to go back to no default.

The default applies to new stacks only. Editing or redeploying an existing stack never changes the provider it is already bound to, and deleting the provider that was marked as default simply leaves new stacks with no preselection.

In editions with role-based access control, binding a provider to a stack requires the Secrets permission - a user who can edit stacks but has no secrets permission cannot attach a provider (and so cannot pull its secrets into a container).

Each provider supports one or both resolution modes. Pick your provider below for its setup and a worked example; this table is the overview:

Bulk pull & inline references

Inline references replace a single variable whose value is a reference in the backend's own syntax. Bulk pull fetches every secret under a selector as a flat key/value map. Explicitly configured secrets always win over bulk-pulled ones. In both cases the resolved values reach your services through normal compose interpolation - you reference them with ${VAR}.

How bulk pull works

The selector variable DOCKHAND_SECRET_SELECTOR goes in the stack's environment variables, not in the compose file. It triggers the pull and is then stripped, so it never reaches the stack. The pulled keys become available to your compose as ${KEY}.

When you pick a provider in the stack editor, a labelled field appears next to the dropdown - Environment for 1Password, KV v2 path for Vault, Secret path for Infisical (Doppler needs none). Type the selector there; it is the same value as the DOCKHAND_SECRET_SELECTOR environment variable, just shown as a field, so you can set it either way.

Putting DOCKHAND_SECRET_SELECTOR inside a service's environment: block in the compose file does nothing - Dockhand only looks for it among the stack's own environment variables.

Names must match exactly. A bulk pull injects each secret under its own key from the provider. So ${DB_PASSWORD} only resolves if the secret is named DB_PASSWORD in the store - the variable name and the secret's key must be identical, character for character (case-sensitive). A secret named db-password in Vault will not fill ${DB_PASSWORD}; it would be a separate ${db-password} key. Rename on the provider side if they don't line up. The selector value differs per provider - see each provider's section below.

How inline references work

With a provider that supports references bound, a variable whose value is a reference (op://..., pass://..., azurekv://..., or keepass://...) is resolved in place at deploy time and injected as a secret - the reference string is never written into the container. Unlike bulk pull, the variable name is yours to choose; the reference itself points at the vault/item/field.

1. In the stack's environment (stack editor → Environment tab, or the .env file) - the value is the reference:

# stack environment (NOT the compose file)
STRIPE_KEY=op://Production/stripe/api_key
SMTP_PASSWORD=op://Production/smtp/password

2. In the compose file - reference the resolved value by name:

services:
  app:
    image: myapp:latest
    environment:
      STRIPE_KEY: ${STRIPE_KEY}
      SMTP_PASSWORD: ${SMTP_PASSWORD}

At deploy time Dockhand resolves STRIPE_KEY / SMTP_PASSWORD from the provider, injects the real values as secrets via the shell environment (never written to disk), and ${STRIPE_KEY} interpolates them into the container.

Seeing what the provider supplies

With a provider bound to the stack, the editor tells you two things: what was injected at the last deploy, and which variables are in the provider right now.

• A green banner in the Environment variables panel names the provider (icon, type and instance name) and lists the secret keys that were pulled at the last deploy - injected into the container, never written to .env. This banner is post-deploy feedback, so a brand-new stack shows nothing until its first deploy.
• In the compose editor, a ${VAR} that currently exists in the bound provider gets a green IN VAULT badge instead of the red MISSING one, and it no longer counts toward the panel's missing total or the Add missing list. This is checked live as you edit - reference a new ${VAR} the provider already holds and it turns green immediately, no deploy needed.
• A ${VAR} the provider does not supply still shows the red MISSING badge - so a genuine gap is still obvious.
• If Dockhand can't reach the provider (network, wrong token, wrong selector path), the editor keeps showing MISSING rather than a false green, and the panel adds a short line explaining what went wrong.

1Password (service account & Connect)

Two 1Password providers are supported: a service account (bulk pull + op:// references) and 1Password Connect (op:// references only, no bulk). Configure one under Settings → Secrets and bind it to the stack.

Bulk pull (service account only): the selector DOCKHAND_SECRET_SELECTOR is a 1Password Environment id; every variable in that Environment is pulled. The alias OP_ENVIRONMENT_ID is also accepted for the same selector.

# stack environment
# OP_ENVIRONMENT_ID is also accepted here (a 1Password alias for the same selector)
DOCKHAND_SECRET_SELECTOR=<your Environment id>

# compose
services:
  db:
    image: postgres:17
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}

Inline reference (both providers): the value is an op:// reference. The variable name is free; the reference points at the field.

op://<vault>/<item>/<field>              # a field on an item
op://<vault>/<item>/<section>/<field>    # a field inside a section

• vault - the vault's name (the service account must have access to it).
• item - the item's title, e.g. a Login named stripe.
• field - the field's label, e.g. api_key, or password on a Login item.

# stack environment (Environment tab or .env)
# the var name (DB_PASSWORD) is yours; the reference picks which field to read.
DB_PASSWORD=op://Production/database/password
STRIPE_KEY=op://Production/stripe/api_key
SMTP_PASSWORD=op://Shared/smtp/password
# field inside a section: op://<vault>/<item>/<section>/<field>
TLS_CERT=op://Production/certs/web/certificate

# compose  -  reference each resolved value by name
services:
  db:
    image: postgres:17
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}

The literal op:// string is never written to the container or back to disk.

HashiCorp Vault (KV v2)

Vault is bulk-only. The selector DOCKHAND_SECRET_SELECTOR is a KV v2 path under the mount: dockhand/prod reads secret/dockhand/prod. Every key at that path becomes a variable.

A secret named DB_PASSWORD at KV path secret/dockhand/prod:

# stack environment
DOCKHAND_SECRET_SELECTOR=dockhand/prod

# compose  -  ${DB_PASSWORD} must match the secret's name in Vault
services:
  db:
    image: postgres:17
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}

Infisical

Infisical is bulk-only. Its DOCKHAND_SECRET_SELECTOR is a secret path (folder) within one project (/ or /backend) - it does not switch projects. Point a provider at a project, then use a folder per stack:

1. Add the provider under Settings → Secrets, type Infisical. API host: https://us.infisical.com (or your EU / self-hosted URL).
2. Access token: in Infisical, Organization → Access Control → add a Token Auth method and create a token. Make sure the project you'll use appears under that identity's Projects - if not, add it as a member.
3. Project ID: open the project in Infisical; it's the ID in the URL after /secret-management/.
4. Environment: prod (or your slug). Secret path: / to start.
5. One project, folder per stack: in the project, use Add Secret → New Folder and name it after your stack. Then in the stack editor, bind the Infisical provider and set the Secret path (the DOCKHAND_SECRET_SELECTOR) to /YourFolderName. Every secret in that folder is pulled.

If you want hard isolation instead of folders, add one Dockhand provider per Infisical project. (A st. service token already targets one project, so its Project ID / Environment are optional.)

Infisical accepts two ways to authenticate - fill in one or the other:

• Access token - a static service/access token, sent straight through as a bearer token. The simplest option.
• Universal Auth (Machine Identity) - a Client ID + Client secret from an Infisical Machine Identity. Dockhand exchanges them for a short-lived access token via Infisical's Universal Auth login endpoint and caches it until shortly before it expires. Prefer this for least-privilege setups: a Machine Identity can be scoped per project / environment / path and rotated on its own, independently of any static token.

Leave the Access token field blank when you use Universal Auth, and leave the Client ID / Client secret blank when you use a static token. The Client ID is the identity's Universal Auth client ID (shown under the identity's Authentication tab), not the identity's own ID.

An Infisical service token (st.) already targets one project, so the Project ID and Environment fields are optional for it - leave them blank and Infisical takes both from the token. One exception: a service token with more than one scope, or a glob secret path, cannot be resolved from the token alone, so for those you still fill in the Project ID and Environment. Universal Auth and any non-st. token always need both.

A secret named DB_PASSWORD at path / in the bound project/environment:

# stack environment
DOCKHAND_SECRET_SELECTOR=/

# compose
services:
  db:
    image: postgres:17
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}

Doppler

Doppler is bulk-only. The selector value is ignored - the token identifies the config, so any non-empty DOCKHAND_SECRET_SELECTOR triggers the pull.

The token type matters: a service token (dp.st.) is scoped to one config and needs nothing else; a personal token (dp.pt.) is account-wide, so set the provider's Project and Config fields (otherwise Doppler answers "You must specify a project"). Doppler's own DOPPLER_PROJECT/DOPPLER_CONFIG/DOPPLER_ENVIRONMENT keys are stripped and never reach the stack.

A secret named DB_PASSWORD in the config the token points at:

# stack environment
DOCKHAND_SECRET_SELECTOR=x

# compose
services:
  db:
    image: postgres:17
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}

Bitwarden Secrets Manager Since 1.0.43

The Bitwarden provider is an adapter around the official bws command-line client, which the operator installs - Dockhand does not bundle, download, or redistribute it. It runs /usr/local/bin/bws by default; set the absolute-path DOCKHAND_BWS_PATH process variable to point elsewhere. For the official Dockhand container, mount the operator-managed binary read-only, e.g. -v /opt/dockhand-tools/bws:/usr/local/bin/bws:ro. Obtaining, verifying, updating, and licensing bws remains the operator's responsibility.

Bitwarden is bulk-only. Configure a Machine Account access token in the provider settings and set the selector DOCKHAND_SECRET_SELECTOR to the Bitwarden Project UUID; every secret in that Project is pulled. For Bitwarden EU or a self-hosted server, also set the optional server URL.

A secret named DB_PASSWORD in a Bitwarden Project:

# stack environment
DOCKHAND_SECRET_SELECTOR=123e4567-e89b-42d3-a456-426614174000

# compose
services:
  db:
    image: postgres:17
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}

Proton Pass Since 1.0.43

The Proton Pass provider is an adapter around the official pass-cli command-line client, which the operator installs - Dockhand does not bundle, download, or redistribute it. It runs /usr/local/bin/pass-cli by default; set the absolute-path DOCKHAND_PASS_CLI_PATH process variable to point elsewhere. For the official Dockhand container, mount the operator-managed binary read-only, e.g. -v /opt/dockhand-tools/pass-cli:/usr/local/bin/pass-cli:ro. Because the container is headless with no system keyring, Dockhand defaults pass-cli to its filesystem key provider (PROTON_PASS_KEY_PROVIDER=fs) so it works out of the box with no configuration on your side. You only need to set PROTON_PASS_KEY_PROVIDER yourself if you want to override that default (for example kernel on a host that does have a keyring); leave it unset and the fs default applies. Obtaining, verifying, updating, and licensing pass-cli remains the operator's responsibility.

Configure a Proton Pass personal access token (pst_...) in the provider settings. The token is handed to pass-cli through its own environment channel, never on the command line, inside an isolated session that is logged out after each lookup. Proton Pass supports both modes.

Bulk pull: the selector DOCKHAND_SECRET_SELECTOR is a vault name; each item becomes a variable keyed by its title.

# stack environment
DOCKHAND_SECRET_SELECTOR=Personal

# compose
services:
  db:
    image: postgres:17
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}

Inline reference: put a pass://SHARE_ID/ITEM_ID/FIELD value in the stack environment and interpolate it in compose. The FIELD segment is required.

# stack environment (Environment tab or .env)
DB_PASSWORD=pass://ajQOpSS.../nTIWqIq.../password

pass-cli item list

By vault and item name Since 1.0.44: instead of ids you can use human-readable names - pass://VAULT_NAME/ITEM_NAME/FIELD. pass-cli resolves the names to ids itself, and names are the same across every Proton Pass client, so this avoids the share_id mismatch above entirely. Names may contain spaces; the field label is a single token.

# stack environment (Environment tab or .env) - names, not ids
DB_PASSWORD=pass://dockhand/database/password
API_KEY=pass://Work/GitHub Account/token

Azure Key Vault Since 1.0.44

Azure Key Vault supports both modes.

Bulk pull: the selector is ignored (a vault has no sub-paths, so a bulk pull is every secret in the vault); any non-empty DOCKHAND_SECRET_SELECTOR triggers it. Each secret becomes a variable keyed by its name.

# stack environment
DOCKHAND_SECRET_SELECTOR=x

# compose
services:
  db:
    image: postgres:17
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}

Inline reference: put an azurekv://<secret-name> value in the stack environment and interpolate it in compose.

# stack environment (Environment tab or .env)
DB_PASSWORD=azurekv://db-password

KeePassXC Since 1.0.45

The KeePassXC provider is an adapter around the keepassxc-cli command-line client, which the operator installs - Dockhand does not bundle, download, or redistribute it. It reads a local .kdbx database file; no networked service is involved. It runs /usr/bin/keepassxc-cli by default; set the absolute-path DOCKHAND_KEEPASSXC_CLI_PATH process variable to point elsewhere.

Mounting the client and the database. For the official Dockhand container, install keepassxc-cli in the container (or mount the operator-managed binary) and bind-mount the .kdbx file (and the key file, if any) read-only. The provider's Database path and Key file path fields are the paths as seen inside the container. Example compose:

services:
  dockhand:
    image: fnsys/dockhand
    volumes:
      - dockhand_data:/app/data
      # the KeePass database (and optional key file), read-only
      - /host/secrets/passwords.kdbx:/secrets/passwords.kdbx:ro
      - /host/secrets/db.keyx:/secrets/db.keyx:ro
      # if keepassxc-cli is not in the image, mount the operator-managed binary
      - /opt/dockhand-tools/keepassxc-cli:/usr/bin/keepassxc-cli:ro

# on the host, build a self-contained tools folder
mkdir -p /opt/dockhand-tools/keepassxc/lib
apt-get download keepassxc   # or: dpkg-deb -x keepassxc_*.deb ...
dpkg-deb -x keepassxc_*.deb /tmp/kxc
cp /tmp/kxc/usr/bin/keepassxc-cli /opt/dockhand-tools/keepassxc/
# copy every shared object the binary needs, plus the dynamic loader.
# NOTE: a single ldd pass lists only DIRECT dependencies - it misses libraries
# pulled in transitively (e.g. libgssapi_krb5 via Qt Network), and the binary then
# fails at runtime with "cannot open shared object". Resolve the closure fully:
# the simplest reliable way is to copy the package's whole library directory.
cp -Ln /tmp/kxc/usr/lib/x86_64-linux-gnu/*.so* /opt/dockhand-tools/keepassxc/lib/ 2>/dev/null || true
ldd /tmp/kxc/usr/bin/keepassxc-cli | grep -o '/[^ ]*\.so[^ ]*' \
  | xargs -I{} cp -Ln {} /opt/dockhand-tools/keepassxc/lib/
cp /lib64/ld-linux-x86-64.so.2 /opt/dockhand-tools/keepassxc/

# wrapper: sets the private library path for THIS call only, not the container
cat > /opt/dockhand-tools/keepassxc/run <<'EOF'
#!/bin/sh
here=$(dirname "$0")
exec "$here/ld-linux-x86-64.so.2" --library-path "$here/lib" \
  "$here/keepassxc-cli" "$@"
EOF
chmod +x /opt/dockhand-tools/keepassxc/run

services:
  dockhand:
    image: fnsys/dockhand
    environment:
      # absolute path INSIDE the container to the wrapper
      - DOCKHAND_KEEPASSXC_CLI_PATH=/opt/keepassxc/run
    volumes:
      - /opt/dockhand-tools/keepassxc:/opt/keepassxc:ro
      - /host/secrets/passwords.kdbx:/secrets/passwords.kdbx:ro

Then configure the provider under Settings → Secrets: the in-container Database path (e.g. /secrets/passwords.kdbx), and a Master password and/or a Key file path (at least one is required). The password is stored encrypted and handed to keepassxc-cli on standard input, never on the command line. KeePassXC supports both modes.

Bulk pull: the selector is a group name. Every entry under that group becomes a variable keyed by the entry title, with the entry's Password as the value. Leave the selector blank to inject only inline keepass:// references (no bulk pull). Titles that are not valid environment-variable names (a dash, a space) are skipped with a warning, and if the same title appears in more than one subgroup the first one wins.

# stack environment
DOCKHAND_SECRET_SELECTOR=Web

Inline reference: a keepass://GROUP/ENTRY/FIELD value. Groups may nest; the last segment is the attribute to read (Password, UserName, URL, or any custom attribute), and everything before it is the entry path. A field is required.

# stack environment (Environment tab or .env)
DB_PASSWORD=keepass://Web/Postgres/Password
API_TOKEN=keepass://APIs/Stripe/token

Psono Since 1.0.54

Psono is a self-hostable password manager. Dockhand reads it with an API key, and the secrets are decrypted inside Dockhand - the key’s secret key is never sent to the Psono server, so Psono itself never sees what it hands over in the clear.

Create the key in Psono under API keys, then attach the secrets it may read. Two settings on the key matter:

• Restrict to secrets - on. The key then reaches only the secrets you attach, instead of the whole vault.
• Allow insecure access - off. That option exists for clients that want the server to decrypt for them, which means sending it the secret key. Dockhand never does, and Psono’s own documentation discourages it.

Psono shows the API key id and secret key once, when the key is created. Enter them under Settings → Secrets together with the Server URL of your instance (for example https://psono.example.com; the /server path its API lives under is added for you). Leaving the key read-only is enough - Dockhand only reads.

Test connection does more than check that the server answers: it decrypts the first secret the key grants, because a wrong secret key looks fine until something is actually opened. If the key is wider than it needs to be, the test still passes but says so.

Bulk pull: the selector enables it, and its value is ignored - a restricted key already decides the scope, so every secret attached to the key is pulled. Each one is named after its username field, which is where an environment-variable name naturally goes, and falls back to the secret’s title (upper-cased, with anything unusable replaced by an underscore). A secret with no value, or no usable name, is skipped with a warning rather than injected empty.

# stack environment — any value turns the bulk pull on
DOCKHAND_SECRET_SELECTOR=1

# a Psono secret whose username is DB_PASSWORD arrives as:
#   DB_PASSWORD=<its password>

Inline reference: a psono://<secret-id> value, optionally with a field. The id is the secret’s UUID, which you can copy from Psono. Without a field Dockhand reads the secret’s main value - the password for a website or application entry, the text of a note, the URL of a bookmark - and naming a field reads that field instead.

# stack environment (Environment tab or .env)
DB_PASSWORD=psono://552f5ea3-c8a9-4448-b98d-3bc7e41e16a4
DB_USER=psono://552f5ea3-c8a9-4448-b98d-3bc7e41e16a4/application_password_username

Environment Variables secrets Since 1.0.55 - Psono has a secret type that holds many key/value pairs in one entry, meant to be a whole stack’s .env. A bulk pull injects every pair, each key used verbatim as the variable name (a key that is not a valid variable name is skipped with a warning, never rewritten). A field on an inline reference addresses a single key of such a secret by name.

# one Environment Variables secret holding SECRET_KEY and API_KEY:
#   bulk pull injects both as SECRET_KEY=<value> and API_KEY=<value>
# or address one key inline:
SECRET_KEY=psono://552f5ea3-c8a9-4448-b98d-3bc7e41e16a4/SECRET_KEY

Every read is recorded by Psono against the secret, so provider activity shows up in its own audit trail.

SOPS (age) Since 1.0.55

SOPS encrypts an env file value by value, so a Git stack can keep its secrets in the repository, version-controlled, and still never store them in the clear. Unlike the other providers there is no backend to reach: the secrets live in the stack's own env file, and the provider only holds the age key that opens them.

Encrypt the file with sops and an age recipient, commit it to the repository, and point the stack's env file at it. Then add a SOPS (age) provider under Settings → Secrets with the matching age secret key (one or more AGE-SECRET-KEY-... identities, or the whole keys.txt that age-keygen writes), and bind it to the stack. At deploy time the file is decrypted with that key and the values are injected as secrets - they reach the containers through the shell environment and are never written to disk.

# encrypt a dotenv file for your age recipient
sops encrypt --age age1... --input-type dotenv --output-type dotenv secrets.env > secrets.sops.env
# commit secrets.sops.env, set it as the stack's env file, bind the SOPS provider

Only values SOPS actually encrypted become secrets; a value it left in the clear is read from the file like any other. Explicit stack secrets and env overrides still win over a decrypted value. The age key is stored encrypted and is passed only to the sops client, never on its command line. The client ships in the image; to use your own, set an absolute path in DOCKHAND_SOPS_PATH (sops 3.12 or newer).

Images

The Images page shows all Docker images on the selected environment, grouped by repository.

Load an image from a .tar (air-gapped)

On hosts with no registry access, use Load from tar on the Images page to upload a docker save archive (.tar) and load it directly into the daemon. The file is streamed to the server without being held in memory, so multi-gigabyte images work. Available on local and direct-TCP environments; on Hawser-connected hosts, copy the tar over and run docker load there instead. In editions with role-based access control this requires the Load images from tar permission, which is separate from Pull because it accepts an arbitrary, unsigned image rather than one from a trusted registry.

Image actions

Unused images indicator Since 1.0.7

Images not used by any container (running or stopped) display an amber Unused badge. This helps identify images that can be safely removed to reclaim disk space.

Prune unused images Since 1.0.7

Click Prune unused in the Images toolbar to remove all images not used by any container. This is equivalent to running docker image prune -a.

Three images are kept back automatically. Dockhand runs some of its own work in throwaway containers, and the images those come from survive a "Prune unused": the grype and trivy scanners, and the backup helper (fnsys/dockhand-backup unless you set your own in Settings). Each is pulled once and reused, so removing one costs the next scan a fresh download of the vulnerability database, and the next backup a fresh pull of the helper - which on a host with no internet access fails outright. They still appear in the Images list marked unused, because that is what they are between jobs; you can always delete one by hand from its row. To let the prune take them like any other image, turn off Protect helper images from prune in Settings > General.

Exclude an image from pruning Since 1.0.44

To keep a specific image that would otherwise be removed by a "Prune unused" (manual or scheduled), label it dockhand.prune=false. Dockhand's unused-image prune then skips it. This is useful for images that are pulled or built on demand and look unused between uses.

Add the label when you build or pull the image, for example:

docker build --label dockhand.prune=false -t myimage .

Or on an existing image by re-tagging through a one-line build:

echo "FROM kasmweb/chrome:1.17.0" | docker build --label dockhand.prune=false -t kasmweb/chrome:1.17.0 -

Only the "prune unused" action honors the label; the dangling (untagged) prune is unaffected. Removing the label (or setting it to any other value) lets the image be pruned normally again.

Pulling images

Click Pull image to download a new image:

1. Optionally select a registry (default: Docker Hub)
2. Enter the image name (e.g., nginx, redis)
3. Enter the tag (e.g., latest, alpine)
4. Click Pull

Progress is shown layer-by-layer with download percentages.

Vulnerability scanning

Dockhand integrates with Grype and Trivy vulnerability scanners to identify security issues in your images. Configure scanner settings in Settings → Environments.

Severity levels

Export formats

Scan results can be exported in multiple formats, both from the scan dialog and the aggregated Vulnerabilities dashboard:

• Markdown - Human-readable report (per-image scan dialog)
• CSV - Spreadsheet format for analysis
• JSON - Raw data for automation
• SARIF - SARIF 2.1.0 for security platforms such as DefectDojo, Dependency-Track, and GitHub code scanning Since 1.0.37

The Vulnerabilities dashboard export respects the active search and severity/image/container/stack filters, so the download matches what is on screen. Exports are also available programmatically - see the API reference.

Scan caching

Scan results are cached by image SHA256. Re-scanning the same image version returns cached results unless you force a fresh scan.

Registry operations

Pushing images

Push images to configured registries. Select the target registry and optionally specify a new tag.

Image history

View the layer-by-layer build history of an image, including:

• Layer size
• Creation timestamp
• Command that created the layer

Volumes

Manage Docker volumes for persistent data storage. Mount volumes to containers when creating new containers.

Volume actions

• Browse - Open volume browser (uses helper container)
• Clone - Create a new named volume and copy the source volume's data into it (via a temporary helper container; the source is mounted read-only). Driver, options, and labels are preserved.
• Inspect - View detailed volume information
• Export - Download volume contents as tar archive
• Delete - Remove the volume (fails if in use)

Volume browser

Browse the contents of Docker volumes using a helper container.

Networks

Manage Docker networks for container communication.

Network drivers

Creating networks

The Create network dialog is organized into tabs:

• Basic - Name, driver, and the core toggles: Internal (restrict external access) and Attachable (allow manual container attachment). For the macvlan and ipvlan drivers, the parent interface and mode are set here too.
• IPAM - address management: Subnet in CIDR notation (e.g. 172.20.0.0/16), Gateway, IP range, auxiliary addresses, and any IPAM-driver options as key/value pairs.
• Options - arbitrary driver options as key/value pairs (see below).
• Labels - metadata labels on the network.

Driver options

The Options tab lets you set any driver-specific option as a key/value pair - the equivalent of docker network create -o key=value. This is how you pass options that have no dedicated field, and Dockhand suggests the common options for the selected driver. For example, on a host with a second interface whose upstream router applies policy routing by source IP, you can pin the network's outbound source address:

That is equivalent to the following Docker CLI and Compose:

docker network create \
  --driver bridge \
  --opt com.docker.network.host_ipv4=192.168.2.20 \
  vpn_network

networks:
  vpn_network:
    driver: bridge
    driver_opts:
      com.docker.network.host_ipv4: "192.168.2.20"

Connecting containers

Use the "Connect container" action to attach running containers to a network. You can also configure networks when creating new containers.

Connection options:

• Aliases - DNS aliases for the container on this network
• IPv4 address - Specific IP address assignment

Registry browser

Browse and search Docker registries to discover and pull images. Configure registries in Settings → Registries.

Features

• Search across configured registries
• View available tags for each image
• Pull images directly from search results
• View image details and manifests

Templates Since 1.0.34

Browse and one-click deploy Docker containers and Compose stacks from curated template catalogs. Templates open in the standard stack editor with image, ports, volumes, and environment variables pre-filled, so you can review and adjust before deploying.

Browsing and deploying

The Templates page shows a grid of template cards aggregated from all enabled catalog sources. Use the search box, category filter, and source filter at the top to narrow the list. Clicking a card opens the stack deploy modal with all fields pre-populated - you can change ports, edit environment variables, and then deploy. Templates always deploy to the environment currently selected in the header dropdown.

Each card can carry up to two reference links in its footer. Project opens the template's homepage or source repository (taken from the catalog entry), so you can read more about the app or report an issue with the template. Details appears for templates from the Lissy93 catalog and opens the matching rich guide on the community site portainer-templates.as93.net, which walks through configuration, ports, volumes, and troubleshooting. The Details link is only shown when a matching page actually exists on that site.

Sources tab

Switch to the Sources tab to manage the catalogs Dockhand pulls templates from. Each row shows a source name, URL, status, and an enable/disable toggle.

• Enable / disable - toggle individual sources without removing them
• Validate all sources - fetches each enabled URL and reports the template count or error
• Disable inactive - bulk-disables any source that failed validation
• Delete - only available for custom sources you added; built-ins can be disabled but not removed

Built-in catalogs

Dockhand ships with a selection of well-known community catalogs. A small number are enabled by default; the rest are disabled and can be turned on from the Sources tab as needed. Built-in sources can be disabled but not deleted.

Adding your own catalog

You can point Dockhand at any URL that returns a JSON template catalog. On the Sources tab, fill in a Name and URL and click Add. The URL must return JSON in the Portainer v2 format (described below). Dockhand fetches each enabled source on first request and caches the result server-side for one hour.

Catalog JSON format

Dockhand expects the Portainer v2 template format. The top level is either a bare array of templates, or an object with a templates array:

{
  "version": "2",
  "templates": [
    {
      "type": 1,
      "title": "Nginx",
      "description": "High performance web server",
      "logo": "https://raw.githubusercontent.com/example/templates/main/nginx.png",
      "image": "nginx:latest",
      "categories": ["Web", "Proxy"],
      "ports": ["80:80/tcp", "443:443/tcp"],
      "volumes": [
        { "bind": "/host/path/html", "container": "/usr/share/nginx/html" }
      ],
      "env": [
        { "name": "TZ", "label": "Timezone", "default": "Etc/UTC" }
      ],
      "restart_policy": "unless-stopped",
      "network": "bridge"
    },
    {
      "type": 3,
      "title": "WordPress",
      "description": "WordPress + MySQL compose stack",
      "logo": "https://example.com/wordpress.png",
      "categories": ["CMS"],
      "repository": {
        "url": "https://github.com/example/templates",
        "stackfile": "wordpress/docker-compose.yml"
      }
    }
  ]
}

Field reference

Activity log

Track all Docker container events across your environments in real-time.

Event types

Filtering

Filter the activity log by:

• Container name - Text search
• Event type - Select specific event types
• Environment - Filter by environment
• Labels - Filter by environment labels
• Date range - Presets or custom range

Schedules

View and manage all scheduled jobs in one place.

Schedule types

Cron expression editor

When configuring schedules, you can use preset options or write custom cron expressions:

Cron expressions use 5 fields: minute hour day-of-month month day-of-week

• * - any value
• */15 - every 15 units (e.g., */15 * * * * = every 15 minutes)
• 0-5 - range (e.g., 0 9-17 * * * = hourly from 9 AM to 5 PM)
• 1,15 - specific values (e.g., 0 0 1,15 * * = 1st and 15th of month)

The visual cron editor shows a human-readable preview of your schedule (e.g., "At 03:00 AM, every day").

Schedule management

• Enable/Disable - Toggle schedule without deleting
• Last run - When the schedule last executed
• Next run - Calculated next execution time (respects environment timezone)
• Delete - Remove the schedule

System schedules

Dockhand includes built-in cleanup schedules that run automatically:

Configure retention periods for schedule execution and container event cleanup in Settings > General > Cleanup jobs. Volume browser container cleanup runs automatically and cannot be disabled.

Backups Beta Since 1.0.38

docker run -d \
  --name dockhand \
  --restart unless-stopped \
  -p 3000:3000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v dockhand_data:/app/data \
  -e FEAT_BACKUPS_ENABLED=true \
  fnsys/dockhand:latest

services:
  dockhand:
    image: fnsys/dockhand:latest
    container_name: dockhand
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - FEAT_BACKUPS_ENABLED=true
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - dockhand_data:/app/data

volumes:
  dockhand_data:

Introduction

Dockhand backs up containers and compose stacks using restic under the hood. A backup snapshot captures the contents of every volume attached to the target, the container or stack metadata (image, env vars, networks, ports, labels, mounts), and - for stacks - the compose file and any sibling files in the stack directory.

Why restic instead of plain tar, cp, or rsync? A hand-rolled script can copy files, but a backup tool has to do more than copy - and restic is what turns "some files somewhere" into a dependable, restorable history:

• Deduplication - restic splits data into content-addressed chunks and stores each unique chunk once. Ten daily snapshots of a database that barely changes cost roughly one copy plus the deltas, not ten copies. You get the convenience of "full snapshot every run" with the disk footprint of an incremental - no ZFS/Btrfs dedup filesystem required.
• Encryption by default - every repository is encrypted (authenticated) with your password. Backups can safely live on a cloud bucket or a shared server without exposing their contents. tar/rsync give you neither encryption nor integrity out of the box.
• Integrity you can verify - snapshots are checksummed, so restic check can prove the repository is internally consistent and --read-data can re-hash the actual bytes to catch silent bit-rot on the backend.
• Snapshots and retention - each run is an immutable point-in-time snapshot. Keep-last / keep-daily / keep-weekly policies expire old ones automatically, and prune reclaims the freed space - history management a copy script would have to reinvent.
• Many backends, one workflow - the same repository format works over local paths, a REST server, and S3/B2/Azure/GCS object storage (see destination types). You learn it once.
• Fully integrated with how you already manage containers - this is the real difference from running restic yourself on the CLI. Dockhand knows what a container or stack is: it discovers the attached volumes for you, captures the container/stack configuration (image, env vars, networks, ports, labels, mounts) and the compose file alongside the data, runs restic inside a helper container right next to that data, and streams live progress into the UI. A restore doesn't just drop files back - it recreates the whole working container or redeploys the whole stack from the snapshot, on the environment you choose (including a different host). Scheduling, retention, prune, integrity checks and restore are all buttons in the same interface you use for everything else - no restic commands, no cron jobs, no glue scripts to maintain.

Learn more about restic itself at the restic homepage, in the restic documentation, or on GitHub .

The metadata is always captured, so a target with no volumes or bind mounts is still a valid backup - it produces a config-only snapshot. There is no volume data to restore, so a restore of one simply recreates the container (or redeploys the stack) from the stored configuration.

Where can I create a backup schedule? There are four entry points, and they all create the same kind of backup config behind the scenes:

1. Backups page - full list of configs across all environments, with a "Backup" button
2. Container edit modal → Backups tab - schedule a backup for that one container
3. Stack modal → Backups tab - schedule a backup for the whole stack
4. Settings > Environments > (env) > Backups tab - batch setup: pick a destination and a schedule, then create backup configs for every container or stack in that environment in one click

Creating a backup config

All four entry points open the same backup config dialog and create equivalent configs - only the pre-fill differs. Pick whichever entry point matches the unit of work you're thinking about: a specific container, a specific stack, or "everything on this environment". You can always edit a config later regardless of where it was created.

From the Backups page

The unified Backups page in the main nav shows every config across every environment. Click Backup in the top-right corner; the dialog opens with no pre-fill, so you pick the environment, target (container or stack), and destination from scratch. Best when you want a bird's-eye view of all your scheduled backups before adding one, or when configuring a fresh environment's first backup.

Each row expands inline to show that config's snapshots, which you can browse, restore, or delete without leaving the page.

The page also surfaces orphan snapshots - snapshots that exist in the repository but that this Dockhand instance has no matching config for. That can be a config you deleted earlier, snapshots written by a different Dockhand installation pointing at the same repo, or even snapshots created directly with the restic CLI. Orphans expand inline like regular backups: you can browse their contents and download files or directories. If the orphan was originally written by Dockhand (so the snapshot contains the metadata it needs), you can also restore it like any other snapshot - the target name comes from the snapshot's stored metadata, and you pick the target environment and destinations in the restore dialog.

From the container edit modal

Open any container's edit modal and switch to the Backups tab. The dialog opens with target = this container, environment = its environment, and the volume picker pre-populated with whatever the container has mounted. By default all volumes are included; toggle Backup all volumes off to pick a subset by name. Best for "I want this database container backed up nightly" - minimal clicks, no risk of typing the wrong target name.

The Backups tab has three sub-tabs:

• Schedules - the backup configs for this target: add, edit, duplicate, enable/disable, run one now, or delete. This is also where you set the cron schedule, retention, and volume selection. A target can have several schedules, e.g. a nightly local backup plus a weekly offsite one. Duplicate opens a new schedule prefilled with the existing one's settings and preselects a repository this target has no schedule for yet (or the same repository when every one is already in use); a copy of a manual backup starts enabled; each schedule applies its retention only to its own snapshots.
• Snapshots - every snapshot taken of this target, with its id, time, size added, and repository. Restore, browse the files, or delete a snapshot from here.
• History - the run log of past backup executions (success/failure, duration, and output) so you can see what happened and when.

From the stack modal

Stack modal (either in the Stacks page or when editing a stack from anywhere) has a Backups tab too. The dialog opens with target = stack, environment = the stack's environment, and the volume picker showing every volume mounted by every container in the stack. As with the container dialog, all volumes are included by default and you can switch to a hand-picked subset. The stack's whole directory - compose file, .env, and sibling config files - is captured in the snapshot automatically (you can't turn this off - see Stack secrets & backups for why). The helper reads the stack directory straight from the host, so there is no size cap. If Dockhand can't locate the stack folder on the host - a remote environment without matching paths or a Remote stacks directory - the backup fails with a clear message rather than silently skipping the stack files. Best when you treat the stack as the unit of recovery - restoring will redeploy the full compose, not just one container's data.

From the environment settings (batch)

In Settings > Environments, open an environment and switch to the Backups tab. The tab lists every container and stack on the environment; each row expands inline to the same backup config form you'd see on the container or stack modal - destination, schedule, volume picker, retention, and so on, all per-target.

The tab also has a Schedule all shortcut at the top: pick one destination and one schedule, and Dockhand creates a backup config for every still-unconfigured container and stack in one click. Batch-created configs always back up all volumes on each target (asking you to pick volumes for dozens of containers at once would be unworkable). To narrow volume selection for any specific target, expand that target's row afterwards and edit its config individually.

Destinations

A destination is a restic repository - the place backups are written to. You configure destinations in Settings > Backups. One destination can hold many backups, and a single container or stack can have multiple backup configs pointing at different destinations on independent schedules - e.g. a fast local backup nightly and a cloud backup weekly for off-site disaster recovery.

The dialog has two parts. The top configures where and how the repository lives (name, backend, password); the bottom - Repository policies - sets up automatic maintenance. Taking the top first:

• Name - a friendly label for the destination, shown throughout the UI so you don't have to read the full repository URL to recognise it. It's purely cosmetic and can be changed anytime.
• Backend type - Local path, Amazon S3, Backblaze B2, Azure Blob, Google Cloud, or REST server. The fields below adapt to the choice (bucket + access keys for S3, account + key for B2, a host/path for REST, and so on). See Destination types for the exact URL patterns and required credentials.
• Encryption password - restic encrypts all repository data with this password; you need it to restore, so store it safely. The dice button generates a strong random one. Dockhand cannot recover a lost repository password - there is no backdoor.
• Extra restic flags - optional flags passed through to every restic call for this destination, e.g. --limit-upload, --limit-download, --verbose, --compression max.

The Repository policies section - the bottom half of the dialog - sets up automatic maintenance so the repo stays healthy without you remembering to run it. Each policy has an on/off toggle and its own schedule (a cron picker with presets or a custom expression):

• Scheduled prune - periodically runs restic prune to actually reclaim space freed by retention (deleting a snapshot only forgets it; prune removes the now-unreferenced data). Max unused % lets prune leave a small fraction of dead data in place for speed - a higher value makes prune faster but reclaims a little less.
• Scheduled integrity check - periodically runs restic check to verify the repository's structure (indexes, snapshots, and that every referenced pack exists). Catches metadata corruption early; it reads structure, not the file contents themselves.
• Scheduled data verification - a deeper, heavier restic check --read-data-subset that actually re-reads and re-hashes a portion of the stored data to catch bit-rot on the backend. Off by default because it downloads data; enable it for critical repositories.
• Auto-unlock stale locks - before a scheduled maintenance task, clear any stale restic lock left behind by a crashed or killed operation, so maintenance isn't blocked waiting on a dead lock. It only removes locks restic can prove are stale, so it's safe alongside other instances sharing the repo.

All of these can be changed later, and run on demand, from the destination's row toolbar (see Repository maintenance). Test checks the connection without saving; Create saves the destination and initialises the repository.

When you create a destination, Dockhand:

1. Encrypts the repository password and any cloud credentials with AES-256-GCM and stores them in the database
2. Calls restic init against the repository (safe to call on already-initialised repos - restic detects an existing repo and skips re-creation)
3. Registers three maintenance schedules with default cron expressions (see Repository maintenance)

If init fails (wrong credentials, network unreachable, password mismatch on an existing repo), the destination row is still saved so you can fix the configuration without re-entering everything - use Test to diagnose the failure and Initialize from the row's menu to retry.

Destination types

The destination type is detected from the repository URL prefix. Dockhand supports every backend restic itself supports:

Local filesystem

A local filesystem destination writes the restic repository to a plain directory on the Docker host - the drive Dockhand is running from, an attached disk, or a mounted NAS share. It's the simplest option when you just want backups on the same machine or a directly-attached volume, with no external service to set up.

It has one extra requirement: the path must be bind-mounted into the Dockhand container at the same host path (e.g. -v /mnt/backup:/mnt/backup), or init and the backup helper end up looking at different directories. See how a backup runs across environments for the details and a diagram.

Amazon S3

Two things to get right when setting up an AWS S3 destination:

1. Set the region. A bucket lives in one region, and the generic s3.amazonaws.com endpoint does not know which - pointing at it returns 301 Moved Permanently on init. Type your bucket's region in the Region field (or pick it from the AWS regions quick-pick, which also fills in the endpoint s3.<region>.amazonaws.com). The region is shown in the S3 console next to the bucket name.
2. Attach the right IAM policy. The access key needs standard S3 API permissions. Attach AmazonS3FullAccess to the IAM user. Do not use AmazonS3FilesFullAccess - despite the similar name that policy is for S3 Access Grants and does not grant bucket API access, so restic fails with Stat: Access Denied on init even though the region is correct. (For production, scope a custom policy to just the one backup bucket rather than full access.)

With the region set and AmazonS3FullAccess attached, initialise the repository from the destination row and back up as usual.

Non-AWS S3 providers (MinIO, Wasabi, Cloudflare R2, Garage, …) use the same Amazon S3 backend - just fill the fields by hand instead of using the AWS quick-pick:

The Access key ID / Secret access key fields work the same for every provider (they become AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY), and the Region field becomes AWS_DEFAULT_REGION - so any provider that needs a region gets one, regardless of endpoint.

Azure Blob

Azure asks for a storage account, a container inside it, and one access key. Set it up from the Azure portal:

1. Create a storage account. Search for Storage accounts → Create. Pick a resource group and a globally-unique account name (lowercase letters and digits) - that name goes in the Account name field. Standard performance with LRS redundancy is the cheapest option that works; pick a higher tier or geo-redundant replication if your setup calls for it. The account name resolves to <account>.blob.core.windows.net, so a wrong name makes the connection hang until it times out.
2. Create a container. Open the account → Data storage → Containers → + Container. Give it a name (e.g. backups) with private access - that name goes in the Container field.
3. Copy an access key. Open the account → Security + networking → Access keys, reveal key1, and copy the Key value into the Account key field. This is a long-lived key (it does not expire), so scheduled backups keep working.

The container must exist before you initialise the repository - Dockhand writes into it but does not create it. Leave Path blank to store snapshots at the container root, or set one (e.g. dockhand) to keep several repositories apart in the same container.

Backblaze B2

In the Backblaze B2 console create a bucket (its name goes in the Bucket field), then under Application Keys create an application key scoped to that bucket. The keyID goes in Key ID and the applicationKey (shown once) in Application key. Both are long-lived, so scheduled backups keep working.

Google Cloud Storage

Google Cloud authenticates with a service account whose key is a JSON file. Dockhand uses that JSON to obtain and refresh access automatically, so scheduled backups keep working without manual re-authentication. Set it up in the Google Cloud console:

1. Create a bucket. Cloud Storage → Buckets → Create. The name is globally unique - it goes in the Bucket field. Keep Public access prevention on and Uniform access control; the service account grants the access, not public ACLs. Note your Project ID from the top bar (it can differ from the project name) for the Project ID field.
2. Create a service account. IAM & Admin → Service Accounts → Create service account. Give it a name (e.g. dockhand-backup) and finish - the optional project-wide role step can be skipped, since access is granted on the bucket instead.
3. Grant it access to the bucket. Open the bucket → Permissions → Grant access, add the service account's email as the principal, and assign the role Storage Object Admin (roles/storage.objectAdmin). This scopes it to reading, writing, and deleting objects in that one bucket - restic needs delete for prune/forget, and bucket-scoped access is safer than a project-wide role.
4. Create a JSON key. On the service account → Keys → Add key → Create new key → JSON. A .json file downloads once - keep it safe.

In the destination dialog, fill in the Bucket and Project ID, then paste the JSON into the Service account JSON field or use Upload file to load the downloaded .json directly. Leave Path blank to store snapshots at the bucket root, or set one (e.g. dockhand) to keep several repositories apart in the same bucket. The bucket must exist before you initialise the repository - Dockhand writes into it but does not create it.

SFTP (SSH key) Since 1.0.52

An SFTP destination backs up over SSH to any machine that accepts key-based logins - a NAS, a VPS, a spare box in another building, or a hosted offsite box such as a Hetzner Storage Box. restic speaks SFTP natively, so nothing extra runs on the far end.

Add one under Settings > Backups > Add backup destination and pick SFTP (SSH key). The SSH model is deliberately narrow, because a backup destination holds a copy of everything:

• SSH host and SSH port - the server and the port it listens on. Leave the port blank for the default 22.
• SSH username - the account to log in as.
• Repository path - optional. Leave it blank to use the account's home directory; a relative path starts from that directory, and an absolute path is taken as given.
• SSH private key - a dedicated key with no passphrase, since the backup runs unattended. Generate one just for this (ssh-keygen -t ed25519 -N '' -f dockhand-backup) and install the public half in the account's authorized_keys.
• Verified known_hosts data - the server's host key, which you supply. Strict host-key checking is always on and there is no trust-on-first-use, so a destination cannot be created by accepting whatever key answers first.

Password and keyboard-interactive logins, ssh-agent and agent forwarding are all disabled. The private key and the host-key data are encrypted in the database, and they exist on disk only as 0600 files for as long as restic is running. The private key is never returned by the API; the host-key data is readable by anyone who may edit the destination, so a rotated server key can be reviewed and replaced.

ssh-keyscan collects what a server advertises, but its output is only a claim until you compare the fingerprint against one the server or provider published through another channel:

ssh-keyscan -p 2222 backup.example.com > known_hosts
ssh-keygen -lf known_hosts

Paste the verified lines into Verified known_hosts data. If the server's key is ever rotated, the backup fails with a host-key mismatch rather than connecting anyway - edit the destination and paste the new verified key.

Self-hosting a REST server destination

The restic REST server is the simplest self-hosted destination - a single container, no buckets, no access keys, no cluster layout. It speaks restic's native HTTP protocol, so it's often faster than going through an S3 gateway. Use the rest: repository type.

Create a password file and start the container. Port 8000 is the REST API:

mkdir -p /srv/rest-server/data

# Create a user (bcrypt). Any htpasswd tool works; here we borrow one from httpd.
docker run --rm httpd:alpine htpasswd -nbB dockhand-user 'a-strong-password' \
  > /srv/rest-server/data/.htpasswd

docker run -d --name rest-server \
  -p 8000:8000 \
  -v /srv/rest-server/data:/data \
  --restart unless-stopped \
  restic/rest-server:latest

The startup log should show Authentication enabled and Loaded htpasswd file. That's the whole setup - no init step here (Dockhand's Test / Init button runs restic init for you).

Then in Dockhand, add a REST server destination and fill in the three fields:

• Server URL: http://<rest-host>:8000/my-backups
• Username: dockhand-user
• Password: the password you put in the htpasswd file

Keep the username and password in their own fields rather than typing them into the URL. Dockhand encodes them for you, so a password containing %, @, : or / works exactly as generated - written into a URL by hand those characters have to be percent-encoded, or the destination cannot connect.

The last path segment (my-backups) is the repository name - restic creates it on init. Use https://… if you put the server behind a TLS reverse proxy (recommended, since the password travels in the URL otherwise). For extra safety you can run the server with --append-only so a compromised client can add snapshots but never delete them.

Self-signed or private-CA certificates. Since 1.0.44 If the backend is served over HTTPS with a certificate that isn't signed by a public CA (a self-hosted REST server or MinIO with your own CA, an internal PKI), open the destination's TLS certificates section and paste or upload the CA certificate (PEM). Dockhand stores it encrypted and hands it to restic so the backend's certificate validates. If the backend also requires mutual TLS, add a client certificate (certificate and private key in one PEM). Both fields are optional and apply to any backend type; leave them blank to use the system trust store. The certificates travel with the backup helper, so they work the same on local, Direct TCP, and Hawser environments.

Self-hosting an S3 destination

The s3: repository type works against any S3-compatible server, not just AWS. Three free, open-source options that run as a single container are RustFS, MinIO and Garage. Pick whichever fits your topology.

RustFS

Start a single-node RustFS container, exposing the S3 API and the web console on two ports. Pick host ports that are free - the examples below use 9010 for the S3 API and 9011 for the console (RustFS defaults to 9000/9001, but those often clash with other services):

docker run -d --name rustfs \
  -p 9010:9000 -p 9011:9001 \
  -e RUSTFS_ACCESS_KEY=dockhand \
  -e RUSTFS_SECRET_KEY=<strong-secret> \
  -v /srv/rustfs:/data \
  --restart unless-stopped \
  rustfs/rustfs:latest

Create a bucket for your backups - either from the console or with any S3 client (the AWS CLI shown here):

AWS_ACCESS_KEY_ID=dockhand AWS_SECRET_ACCESS_KEY=<strong-secret> \
  aws --endpoint-url http://<rustfs-host>:9010 s3 mb s3://dockhand-backups

Then in Dockhand, create an S3 destination with:

• Repository: s3:http://<rustfs-host>:9010/dockhand-backups (use https:// if you've put TLS in front - see below)
• AWS_ACCESS_KEY_ID: dockhand (or a dedicated access key you create in the console)
• AWS_SECRET_ACCESS_KEY: the secret you set above

RustFS uses path-style addressing and the default us-east-1 region, both of which restic handles automatically - no extra configuration is needed. If you front RustFS with a reverse proxy for TLS (for example a public hostname with a valid certificate), point the repository at the HTTPS URL instead (s3:https://rustfs.example.com/dockhand-backups); the proxy forwards to the S3 API port and no CA upload is needed for a publicly-trusted certificate.

MinIO

Start a single-node MinIO container, exposing the S3 API on port 9000 and the web console on 9001:

docker run -d --name minio \
  -p 9000:9000 -p 9001:9001 \
  -e MINIO_ROOT_USER=dockhand \
  -e MINIO_ROOT_PASSWORD=<strong-password> \
  -v /srv/minio:/data \
  --restart unless-stopped \
  quay.io/minio/minio:latest \
  server /data --console-address ":9001"

Create a bucket for your backups - use the bundled mc client inside the container:

docker exec minio mc alias set local http://127.0.0.1:9000 dockhand <strong-password>
docker exec minio mc mb local/dockhand-backups

Then in Dockhand, create an S3 destination with:

• Repository: s3:http://<minio-host>:9000/dockhand-backups (use https:// if you've put TLS in front)
• AWS_ACCESS_KEY_ID: dockhand (or a dedicated user/service account you create in the MinIO console)
• AWS_SECRET_ACCESS_KEY: the password you set above

Garage

Garage needs a small TOML config file. Generate an RPC secret and write the config first:

mkdir -p /srv/garage/meta /srv/garage/data
RPC_SECRET=$(openssl rand -hex 32)
cat > /srv/garage/garage.toml <<EOF
metadata_dir = "/var/lib/garage/meta"
data_dir = "/var/lib/garage/data"
db_engine = "sqlite"

replication_factor = 1
rpc_bind_addr = "[::]:3901"
rpc_public_addr = "127.0.0.1:3901"
rpc_secret = "${RPC_SECRET}"

[s3_api]
api_bind_addr = "[::]:3900"
s3_region = "garage"
root_domain = ".s3.garage.local"

[admin]
api_bind_addr = "[::]:3903"
admin_token = "$(openssl rand -hex 32)"
EOF

Start the container - port 3900 is the S3 API, 3903 is the admin API:

docker run -d --name garage \
  -p 3900:3900 -p 3903:3903 \
  -v /srv/garage/garage.toml:/etc/garage.toml \
  -v /srv/garage/meta:/var/lib/garage/meta \
  -v /srv/garage/data:/var/lib/garage/data \
  --restart unless-stopped \
  dxflrs/garage:v2.3.0

Garage v2 needs an explicit cluster layout before the S3 API will accept requests. The bootstrap is a one-time setup:

NODE_ID=$(docker exec garage /garage node id -q | head -c 64)
docker exec garage /garage layout assign -z dc1 -c 1G $NODE_ID
docker exec garage /garage layout apply --version 1

docker exec garage /garage bucket create dockhand-backups
docker exec garage /garage key create dockhand-key
docker exec garage /garage bucket allow --read --write --owner dockhand-backups --key dockhand-key

The key create step prints the Access Key ID and Secret Access Key. Copy them - the secret is shown only once. Then in Dockhand, create an S3 destination with:

• Repository: s3:http://<garage-host>:3900/dockhand-backups
• AWS_ACCESS_KEY_ID: the key ID Garage printed (starts with GK)
• AWS_SECRET_ACCESS_KEY: the secret key Garage printed

How a backup runs across environments

Every backup uses the same primitive: Dockhand asks the target Docker daemon to start a small helper container from fnsys/dockhand-backup. The helper has the target's volumes bind-mounted read-only and runs restic backup inside itself. Restic pushes data directly from the helper to the backup destination repository - the bytes do not tunnel back through Dockhand. What changes between connection types is how Dockhand reaches the target Docker daemon to orchestrate, not the data path.

The helper runs where the data lives and pushes it straight to the repository - the bytes never pass through Dockhand. Only orchestration (start the helper, watch it) goes through Dockhand.

The connection type only changes the left half of that picture - how Dockhand reaches the target Docker daemon to start and watch the helper. The right half (helper → destination) is identical everywhere.

Local socket (Dockhand and Docker on the same host)

Dockhand reaches the Docker daemon through the shared docker.sock. The helper container starts on the same host, mounts the target's volumes read-only, and pushes data to the destination.

Volumes are mounted from the same host into the helper container, restic ships them to the repository.

Local destinations need the path bind-mounted into Dockhand

A Local filesystem destination (a host path like /mnt/backup/dockhand) is touched by two different containers at two different moments:

• Init, snapshot listing, and maintenance run inside the main Dockhand container.
• The backup itself runs in the helper container, which the daemon starts on the host and which sees the real host path. It looks for the repository at the host path - and doesn't find the one Dockhand created inside its container.

Mount the destination path into the Dockhand container at the same host path. Then init and backup both resolve to the same directory on the host, and restic no longer reports repository not found:

Mount the local destination into Dockhand at the same path (-v /mnt/backup:/mnt/backup) so init and backup both land on the one host directory. Without the mount, init writes inside the Dockhand container and the helper can't find it.

Direct TCP (Dockhand and Docker on different hosts)

Dockhand talks to the remote Docker daemon over tcp:// (optionally with mTLS). The helper container runs on the remote host where the volumes are, and streams data straight to the destination - the bytes never tunnel back through Dockhand.

Data path runs from the remote host directly to the repository, not back through Dockhand.

Hawser (Standard or Edge)

Dockhand reaches the remote Docker daemon by tunneling through the Hawser agent. In Standard mode Dockhand initiates the connection; in Edge mode the agent initiates it outbound. Either way, the helper container still runs on the remote host and uploads data directly to the destination.

Control flows through the agent; backup data still flows out from the remote host on its own connection.

Three things follow from this:

• Bandwidth between the target host and the destination matters more than between Dockhand and either. Dockhand only orchestrates; volume bytes travel directly from the target to the backup repo.
• Local repositories only work when Dockhand and the target are the same host. A remote helper can't see a path that exists only on Dockhand's filesystem. Use S3 or REST for any remote env.
• The Hawser agent doesn't carry backup data. It carries Docker API calls. The helper container on the target host opens its own outbound connection to the restic repo.

The backup helper image

By default the helper is fnsys/dockhand-backup pinned to the same version as Dockhand itself (e.g. running Dockhand v1.0.38 pulls fnsys/dockhand-backup:v1.0.38). Pinning to the running version keeps the helper's restic in lock-step with Dockhand - an upgrade never leaves you on a stale helper - and the baseline Dockhand build automatically uses the matching -baseline helper for old CPUs.

You can override it. In Settings > Backups the Backup helper image field sets the image for every backup - point it at your own registry mirror (air-gapped networks, a private pull-through cache, or a pinned digest for reproducibility). A custom value always wins over the built-in default. It must be a Dockhand backup helper image (it bundles restic and the expected entrypoint); an arbitrary image won't work.

Backup configs

A backup config ties a target (container or stack) to a destination, optionally on a schedule. Each config tracks:

• Target - container or stack name, plus the environment it lives in
• Volume selection - back up all attached volumes (default) or only specific ones
• Stop before backup - gracefully stops the target before snapshotting, restarts after. Optional; useful for databases that don't support hot backups
• Schedule - cron expression. Leave empty for manual-only backups
• Retention - keep-last/daily/weekly/monthly/yearly counts, applied automatically after each backup. This step only forgets old snapshots (a fast, metadata-only operation) so a backup always finishes quickly; the space they used is reclaimed later by the destination's separate prune schedule. If the policy would delete every snapshot for the target (typo'd keepLast: 0, for example), the step is refused with a warning in the run log; the backup itself still succeeds and existing snapshots are preserved.
• Options - compression level, upload/download bandwidth limits, exclude patterns, success/failure webhook URLs

Configs can be triggered manually with the Run now button regardless of whether a schedule is set. A running backup can be cancelled from the same button.

Every backup - scheduled or manual - streams its progress live in a log dialog. You see Dockhand's own steps (collecting metadata, stopping and restarting the target if configured, verifying the snapshot is readable, applying retention) interleaved with restic's own output: the per-file % done progress and the final Done: N new, N changed … MB added summary. Each line is tagged with its source (dockhand or restic) so you can tell exactly what is happening. You don't have to watch it - click Run in background to close the dialog and let the backup finish; it keeps running and the result lands in the target's History.

Volumes & bind mounts

Dockhand backs up both named volumes and bind mounts in the same snapshot. The contents are written under /volumes/<name>/ inside the restic repository, alongside a /metadata/ tree describing each container.

The two mount types differ in one important way at restore time:

• Named volumes - restoring creates a named volume on the target environment (its original name by default, or another you pick as the destination) and writes the snapshot contents into it. Portable across environments.
• Bind mounts - the snapshot captures the contents, but the destination is a path on a host. By default it's the original host path; if that path doesn't exist on the target host, Docker will silently create an empty directory and the service starts with no data - so edit the destination to a path that exists there (or a named volume).

A bind of a single file (for example ./config.yaml:/app/config.yaml) shows a file icon in the backup dialog and is restored as a file. Its destination is the path of the file itself. If the file is missing on the target host it is created; if an empty directory stands in its place (Docker creates one when a container starts with a missing bind source) it is replaced by the file; a directory that holds anything is left untouched and the restore stops with an error. A file restored into a named volume lands inside the volume.

Other mount types - tmpfs (RAM-only), Windows npipe, Swarm CSI cluster volumes, and anything new Docker adds in the future - are not backed up. Each skipped mount produces a SKIPPED <type> mount on <container> at <path> line in the backup's run log so you can see exactly what was left out.

The volume type is not fixed at backup time - you choose it at restore. In the restore dialog's What gets restored? step, each captured volume has a destination with a type dropdown: restore a named volume straight back into a named volume, or switch it to a host path (bind) - and vice versa, a captured bind can be restored into a named volume. This is how you make a bind mount portable: back it up on one host and restore it into a named volume on another, sidestepping the host-path problem entirely. One caveat when you redirect a name or type - the after-restore step still rebuilds the target from its stored config, so the mount change is yours to apply: see If you rename a volume or change its type.

Stack files (compose, .env, config)

A stack backup captures the stack's whole directory - the compose file, .env, and any config sidecars (an nginx.conf, a certs/ dir, include files) - so a restore can redeploy the stack exactly, even on a fresh host where nothing of the original remains.

The stack directory is captured the same way as the volume data: the helper container bind-mounts the stack folder read-only from the target host and restic reads it straight from disk. It lands in the snapshot under a reserved path (/volumes/__dockhand_stackdir__), alongside the volume data and a /metadata/ tree describing the container config. Nothing is copied through Dockhand and there is no size cap - the folder is read where it lives, so even a large stack directory backs up fine.

Because the folder is read from the host, the snapshot reflects the stack directory as it actually is on the host - if you drop a file into the stack folder outside Dockhand, it's in the next snapshot too.

The helper runs on the target host, next to the data. It bind-mounts the volumes and the stack folder read-only from that host and runs one restic backup - volume data and stack files reach the repository through the same helper, in one snapshot. Only orchestration (start the helper, watch it) goes through Dockhand; the bytes never flow Dockhand → destination directly.

Because the helper reads the stack folder from the host, Dockhand has to know where that folder is on the host. Where it looks depends on the environment type:

1. Local (socket)

Dockhand and the Docker daemon share a host, so Dockhand knows the stack folder's path directly - it deployed the stack there. No configuration needed.

2. Direct TCP to a remote host

Set a Remote stacks directory (or use matching paths) so the compose, .env, and config sidecars live in a folder on the remote host - Dockhand backs up the whole folder straight from there. Without it, a stack backup fails with a clear message telling you to set that path; Dockhand does not fall back to backing up its own local copy, so the snapshot always reflects what actually runs on the host. Volume and bind-mount data is always backed up regardless, read from where each mount lives on the remote host.

3. Hawser agent (standard or edge) Since 1.0.41

The agent keeps each stack's folder at <STACKS_DIR>/<stack> on its own host, defaulting to /data/stacks, and Dockhand reads the backup from there. This works out of the box for a standard agent - no configuration needed.

If a stack backup fails because the stack folder can't be found (the message names the path it looked in), set the correct path under Settings → Environments → (edit the environment) → Remote stack path (for backup). This only tells backup where the agent keeps files - it does not change how stacks deploy; the agent always uses its own STACKS_DIR. The create-backup dialog shows the resolved host path so you can confirm it before saving.

docker run -d --name hawser \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /opt/hawser-stacks:/opt/hawser-stacks \
  -e STACKS_DIR=/opt/hawser-stacks \
  ...

Because restic reads the folder locally on the agent's host, the file bytes never travel through Dockhand or over the agent connection - so even a large stack folder (many megabytes of config, or a node_modules a user dropped in) backs up fine, including on edge agents over a WebSocket tunnel.

stack/
├── compose.yaml
├── .env
├── config/   ← bind-mounted into the container
└── data/     ← bind-mounted into the container

Snapshots

Each successful backup produces a snapshot - a content-addressed point-in-time view of the target. Snapshots are tagged with metadata so they can be filtered later:

From the snapshots list you can:

• Browse - navigate the directory tree inside the snapshot
• Download - pull individual files or entire directories as tar archives
• Diff - compare two snapshots and see added/removed/modified files
• Restore - see the Restore section
• Delete - runs restic forget --prune, freeing the space

Opening a snapshot shows two tabs. Files is a read-only browser of the snapshot's contents - navigate with the breadcrumb, preview a file, or download any file or directory. Metadata shows what was captured alongside the data. Both target types share a Backup info summary (type, name, time, environment) and a Volumes & binds list showing each mount's source and destination - but from there the two diverge, because a container and a stack restore differently.

For a container, the Metadata tab adds the full recorded configuration - image, container ID, state at backup, command, entrypoint, exposed ports, restart policy, network mode, mounts, labels, and masked environment variables - so you can see exactly what the snapshot would recreate.

For a stack, there is no single container config; instead the tab records the compose file name and confirms the stack's files were captured, and adds a Stack files list of every file backed up from the stack directory - the compose file (badged) and any sibling files, each with its size. This is how you confirm a stack will restore 1:1: the original compose filename and all its accompanying files are in the snapshot.

How snapshots are stored, and why deleting one is safe

Snapshots are not full copies stacked on top of each other, and they're not a fragile incremental chain where deleting an old one breaks the newer ones. Under the hood restic deduplicates: every file is split into content-addressed blocks, each unique block is stored in the repository once, and a snapshot is just a manifest of pointers to the blocks that made up the target at that moment.

So when your second backup only changed a little, it stores just the few new blocks and points at the unchanged blocks the first snapshot already put there - that's why the run reports "0 new, 1 changed" and adds only kilobytes. The two snapshots share those blocks; neither owns them.

Deleting a snapshot never loses data from the ones you keep. Dockhand deletes with restic forget --prune, which does two things: forget drops the snapshot's manifest, and --prune then removes only the blocks that no remaining snapshot references. Delete the first snapshot and every block still used by the second (or any other) snapshot is kept - the survivors stay fully restorable. This holds for deleting any snapshot, not just the oldest: each one is a complete, independent point-in-time view, so there is no "base" that the others depend on.

The only way a block actually disappears is if every snapshot that referenced it is gone - which is exactly correct: if no snapshot you're keeping contains a file, that file is no longer in any backup. And retention won't strand you there by accident: Dockhand refuses to apply a policy that would delete every snapshot in a config's group, so a repository is never pruned empty in one step.

Comparing snapshots

The Diff action compares two snapshots of the same target and reports what changed between them: files added, removed, and modified, per volume. It's a quick way to see what a backup actually captured since the last one - useful for spotting unexpected churn (a log directory ballooning, a database rewriting its whole data dir) or confirming that a change you made is present in the newer snapshot. The diff reads the two snapshots' file trees from the repository; it doesn't touch the live target. There's also a metadata.json row that will often show as modified even when nothing meaningful changed - that's the capture timestamp and recorded container state inside it differing between backups, not a config change.

Restore

Restore operates on a single snapshot. Open the restore dialog from the snapshots list (per-snapshot menu) or from the target's edit modal Backups tab. A restore extracts the snapshot's volume data (a config-only snapshot has none - it restores the stored configuration instead); the mode you pick decides where that data lands and whether the live target is touched. Your data is restored point-in-time, but the container image is pulled fresh from the registry by the reference the snapshot recorded - see Container images are not stored in the snapshot for why to pin by digest.

Choose a restore mode

The dialog asks one question first - Where to restore - and it's a choice of destination, not of "safe versus destructive":

• To an environment default - pick a target environment (any one you can access, including a different host) and give each volume a destination on it. Then optionally bring the container/stack up there. What each destination points at decides the outcome - see below. Nothing on the source is touched.
• Overwrite live destructive - overwrites the live volume data of the existing target on its source environment. It is guarded: you must tick “I understand this replaces the live volume data” before the button enables, and the button turns red (Overwrite & restore).

The dialog walks three numbered steps - Where does it go?, What gets restored? (per-volume destinations), and Then what? (the post-restore action) - and a What will happen panel spells out the exact outcome before you commit. The panel changes with the mode, so you always see whether the source is safe or about to be overwritten.

Destinations decide the outcome (“To an environment”)

Each selected volume gets an editable destination, pre-filled to its original location (a 1:1 clone). You steer the restore by editing it:

• A named volume - Dockhand creates that volume on the target environment and fills it with the snapshot's data. When you then recreate/redeploy, the container mounts it with its data - a working clone. This is the portable choice.
• A host path - the data is written to that absolute path on the target environment's host (a bind). Use it when the target mounts a bind, or to place data somewhere specific.

What will happen

If you rename a volume or change its type

Restore puts the data wherever you point each volume - but the after-restore step (recreate a container, redeploy a stack) rebuilds the target from the snapshot's stored configuration, which still references the original mounts. So if you redirect a volume to a new name, or change a named volume to a host path (or the reverse), the data lands where you asked, but the target comes up mounted on the original volume - it won't see the restored data. Dockhand does not rewrite your container config or compose file for you; that change is yours to make.

When the restore dialog detects a redirected name or type, it shows a warning in What will happen and sets After restore to Do nothing (you can override it if your config already matches). Restore the data, then apply the matching mount change:

Restore options

• Volume selection - restore all volumes from the snapshot, or only some (tick the ones you want).
• Target environment - restore to any environment you can access, including a different host than the backup came from (see Cross-environment restore). “Overwrite live” always uses the source environment.
• Destination (“To an environment”) - a named volume or host path per volume, as described above.
• After restore - for a container: start (overwrite-live only), recreate, or do nothing. A stack is always redeployed from its stored compose files.

How volume restore works

Overwrite-live wipes the target volume's existing contents before extracting the snapshot; To an environment instead populates a fresh volume (or writes to the host path you chose) and touches nothing live. Either way a restore is point-in-time - what was in the snapshot is exactly what ends up on disk. If the snapshot's volume was empty, the restored volume is empty too.

If you ask for a volume that isn't in the snapshot, the restore fails fast with <name> not found in snapshot. Available: … - nothing is touched.

Cross-environment restore

Restoring a snapshot from environment A to environment B works for any combination of connection types (socket, direct TCP, Hawser standard, Hawser edge). The volume contents travel through the restic repository, so the source environment doesn't even need to be online. Pick the target environment in the To an environment mode; a named-volume destination gives you a clean, portable clone (see the Restore section).

What works cleanly cross-env:

• Named volumes - Dockhand creates the destination volume on the target and fills it with the snapshot's data (refusing if a volume of that name already exists there)
• Container metadata - env/labels/ports/restart policy reapplied when you recreate, from the stored inspect config. The image is not re-pulled: it must already be present on the target daemon, or the recreate fails (pull it first)
• Stack files (compose.yaml, .env, sibling configs) - restored from the snapshot and used to redeploy the stack on the target
• Networks - a recreated container connects to its networks by name; they must already exist on the target (a missing network is logged as a warning, not created). A stack redeploy creates its networks via docker compose up. Pre-create networks by name for container recreates.

What requires attention:

• Bind mounts - see the warning under Volumes & bind mounts. A host-path destination is resolved by the target's Docker daemon and must exist on that host. By default a bind is restored to the same host path it was backed up from; edit that volume's destination in the restore dialog to a path (or a named volume) that suits the target. For portable cross-host clones, prefer named-volume destinations.
• Network IDs - Docker generates fresh IDs for auto-created networks. Containers using networkMode: "container:<id>" won't translate automatically.

Crash safety

An in-place restore never overwrites the live volume directly. It extracts the restored data into a staging directory on the volume's own filesystem and commits it with an atomic rename, guarded by a small on-disk phase marker. The destructive window is a handful of same-filesystem renames - milliseconds, regardless of how much data is restored. If Dockhand (or the whole host) dies inside that window, the live data is left either fully-old or fully-new, never half-swapped.

Recovery needs nothing from you: the next time you run a restore for that volume, Dockhand reads the phase marker first and rolls back any interrupted prior swap before staging the new data, so a re-run always starts from a clean, consistent volume. If a backup or restore stopped a container for consistency and the process died before restarting it, the container is simply left stopped - start it again from the containers page.

Repository maintenance

Restic repositories accumulate garbage over time (orphaned data blobs from deleted snapshots, stale locks from interrupted operations, index drift). Dockhand exposes the standard maintenance operations from the destination's row in Settings > Backups. Each row lists the repository's type, name, URL, usage, and status, and ends in a per-row action toolbar - browse snapshots, stats, check, verify data, unlock, prune, repair, rotate password, test connection, edit, and delete:

Rotate repository password

The key-icon button on the destination row opens the Rotate password dialog. Enter the current password (required so the change can be authenticated against the repository) and the new password twice. Dockhand runs restic key passwd against the repository, then writes the new password back to the destination's encrypted DB row. From that moment forward all backup, restore, and maintenance operations use the new password - no further action required.

Schedules

Both backup configs and repository maintenance tasks can run on cron schedules. They all show up in the unified Schedules view alongside the destination and backup config rows that own them.

What gets registered when

Schedule creation is driven by the options you toggle when configuring destinations and backup configs - Dockhand never creates a cron entry you didn't ask for, and never silently keeps one for a config you disabled. The full conditional matrix:

The default maintenance cron is 0 0 1 * * (the 1st of every month at 00:00). Each schedule can be edited - cron expression, enabled/disabled, and the data-subset percentage for verify - via the destination's Policies dialog.

Execution history

Every scheduled run records an execution row with status, duration, line-by-line log, and (for backups) statistics like files added and bytes processed. View execution history on the Schedules page - expand any backup or maintenance row to its run history - or from the target's edit modal Backups tab under the History sub-tab.

Stack secrets & backups

For compose stacks, Dockhand separates non-secret env vars (written to the on-disk .env file) from secrets (stored encrypted in the Dockhand database and injected via shell at deploy time). Both are captured in a stack backup:

• The snapshot's stack files include the .env file as it exists on disk - so non-secret values are in the backup
• Secrets are carried in the snapshot too, stored as ciphertext - encrypted with this Dockhand instance's encryption key. Their plain values are never written to the backup
• Restoring a stack brings back the compose file, .env, and the secrets - so the stack comes up working, even if the original stack was deleted entirely. On the restore screen you can turn Restore secrets from this backup off to bring the stack up without them and set them by hand

Backups of git-managed stacks

A git-managed stack is conceptually two things: a working copy of the repo on Dockhand's filesystem, and the running containers Docker built from it. Backups operate on the working copy in place - Dockhand does not read commits, branches, or remotes during a backup.

What that means in practice:

• The snapshot is a frozen copy of the files on disk at backup time, including any uncommitted local edits, the working tree's current branch state, and the rendered .env.dockhand. There's no pointer back to the git commit.
• The .git directory itself is excluded from the stack-files capture - only the compose file, .env, and other sibling files are stored. The snapshot is enough to redeploy the stack but not to recover its git history.
• Restoring a git stack restores files, not the git binding. The recovered stack is an internal stack with the original compose and config files; it is no longer linked to the source repository. There is currently no flow to re-attach a restored stack to its git origin - if you need the stack to keep tracking the repo, delete the restored stack and add it again as a git stack from Stacks > New stack > Git, then restore the volume data on top of the fresh deployment.
• Secrets are captured in the snapshot (encrypted) - see Stack secrets & backups. This works the same whether the stack is internal or git-managed.

Known limits

• External stacks can't be backed up - a stack that is running in Docker but has not been adopted into Dockhand has no known compose file path. Creating a backup config for such a stack is rejected, and a manual run fails with the same error. Adopt the stack first (Stacks > Import) so Dockhand knows where its compose and .env files live.
• Targets that don't exist are rejected - if the backup target has zero containers at run time (the container or the whole stack was deleted, so nothing matches its name), the run fails fast so an empty run can't get the retention policy applied and prune the previous good snapshots. Recreate the target and retry. A stopped container or stack is not rejected - as long as it still exists it backs up normally (its volumes still hold data worth capturing). A target with no volumes or binds also backs up fine - as a config-only snapshot.
• Bind mounts aren't portable by default - see Volumes & bind mounts. The data is captured in the snapshot, but a bind's host path won't exist on another host unless you put it there. At restore you can edit its destination to any absolute host path on the target (or to a named volume) to make it portable. The path you type (any absolute path, no ..) is exactly where the data is written on the target daemon's host - Dockhand doesn't restrict which directory, so a host-path destination can point anywhere on that host and the write happens with the daemon's privileges. Only users with backup management access can run a restore; choose destinations deliberately, and prefer named volumes when you don't specifically need a host path.
• Stack compose files with relative bind mounts (./html:/web) deploy against the path on Dockhand's filesystem, not the target host's. For Hawser-managed stacks, file transfer is automatic; for direct-TCP environments, the bind effectively maps to a path that may not exist on the remote daemon.
• One operation per target's data at a time - a run is rejected outright (not queued) while another backup or restore is already touching the same target's volumes/binds. (This is keyed on the data, so two different configs backing up the same volumes also collide.) Operations on different data run concurrently - except that anything sharing one restic repository is serialized (restic locks the repo exclusively while writing), so they queue behind each other. Serialization keys on the repository itself, so two destinations pointing at the same repo queue together.
• Container images are not stored in the snapshot - a snapshot captures your data (volume and bind-mount contents) plus the container/stack configuration, but not the image itself. On restore, Dockhand recreates the container (or redeploys the stack) using the image reference it recorded, and Docker pulls that reference from the registry. If the reference is a moving tag like myapp:latest, the restore brings back your data from backup time but the current image behind that tag - which may be newer than the one that was running when the backup was taken. Your volume data is always point-in-time; the image is only as point-in-time as the reference you pinned.
  
  To get a true point-in-time restore of the image too, pin by digest so the reference is immutable:
  • Containers - run them from a digest, e.g. myapp@sha256:<digest> rather than myapp:latest. A digest always resolves to exactly one image.
  • Compose stacks - pin each service's image: to a digest in the compose file (image: myapp@sha256:<digest>). Because the restore redeploys from the compose file it backed up, a pinned digest there is redeployed verbatim.
  A digest is only pullable while the registry still holds it, so for anything you must be able to restore long-term, back the image up independently (e.g. push it to a registry you control, or docker save it) - Dockhand's snapshots deliberately do not carry image layers.
• Networks are matched by name, IDs aren't translated - a recreated container connects to its networks by name (they must exist on the target; a stack redeploy creates them via compose). Containers that reference a specific network ID (e.g. networkMode: "container:<id>") can't be translated automatically and need manual remapping.

Backup & restore via the API

Everything the Backups UI does is a plain HTTP call, so you can script the whole lifecycle. The long-running steps (run, restore) follow Dockhand's job pattern for long-running operations: send Accept: application/json and the request runs synchronously and returns the final result - no polling needed, ideal for curl. Below is a complete flow against a container named postgres. Replace the host, and add your auth header (-H "Authorization: Bearer dh_…") if authentication is enabled.

1. Create a destination (where snapshots are stored). Returns the destination id.

curl -sf -X POST "https://dockhand.example.com/api/backup/destinations" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "backblaze",
    "repository": "b2:my-bucket:dockhand",
    "password": "a-strong-restic-repo-password",
    "envVars": { "B2_ACCOUNT_ID": "…", "B2_ACCOUNT_KEY": "…" }
  }'
# → { "id": 25, "name": "backblaze", "repository": "b2:my-bucket:dockhand", ... }

The password encrypts the restic repository - keep it, it can't be recovered. envVars carries the backend credentials (S3/B2/Azure/GCS keys); omit it for a local or unauthenticated REST repo. Initialise the repo once (safe to re-run):

curl -sf -X POST "https://dockhand.example.com/api/backup/destinations/25/init"

For a stack target, Dockhand can list the stack folder as it exists on the Docker host, so you can see exactly what will be captured and deselect entries you don't want (the compose file and .env are always kept). The folder is probed by mounting it read-only in a short-lived helper on the target daemon.

curl -sf "https://dockhand.example.com/api/backup/stack-dir-listing?target=immich&env=26"
# → { "kind": "listed", "hostPath": "/opt/immich",
#     "entries": [ { "name": "database", "type": "dir", "size": 4096 }, ... ] }
# → { "kind": "unknown", "reason": "..." }  when the folder can't be located on the host

Deselected entries are saved on the config as options.excludedStackFiles; the backup excludes them from the stack-folder capture.

2. Create a backup config - ties a target (container or stack) to a destination. environmentId is the env the target lives in (from GET /api/environments). An optional schedule (cron) makes it run automatically; omit it for manual-only. Returns the config id.

curl -sf -X POST "https://dockhand.example.com/api/backup/configs" \
  -H "Content-Type: application/json" \
  -d '{
    "targetName": "postgres",
    "type": "container",
    "destinationId": 25,
    "environmentId": 26,
    "schedule": "0 3 * * *",
    "retention": { "keepLast": 7 }
  }'
# → { "id": 1719, "targetName": "postgres", "type": "container", "destinationId": 25, ... }

3. Run a backup now - synchronous with Accept: application/json. This is where the initial snapshot (and every later incremental one) is written. The response carries the new snapshot id and a summary.

curl -sf -X POST "https://dockhand.example.com/api/backup/configs/1719/run" \
  -H "Accept: application/json"
# → {
#     "status": "success",
#     "executionId": 18041,
#     "snapshotId": "1b9017739d10e952529550b7631220dfe280fcc72f083c9b6f8bd09bb710dd8d",
#     "summary": { "filesNew": 2, "filesChanged": 0, "dataAdded": 8602, "totalFilesProcessed": 2 },
#     "retention": "applied"
#   }

4. List snapshots for the config. Each has a full id and a short shortId; use the full id for restore.

curl -sf "https://dockhand.example.com/api/backup/snapshots?configId=1719"
# → [ {
#     "id": "1b9017739d10e952529550b7631220dfe280fcc72f083c9b6f8bd09bb710dd8d",
#     "shortId": "1b901773",
#     "time": "2026-07-24T07:13:12Z",
#     "tags": [ "dockhand:configid=1719", "dockhand:name=postgres", "dockhand:type=container", … ],
#     "paths": [ "/metadata", "/volumes" ]
#   }, … ]

Optional - inspect what a snapshot holds before restoring: its metadata (GET /api/backup/snapshots/{id}/metadata?destinationId=25), a file listing (…/browse), or a dry-run restore preview (lists the volumes it will restore):

curl -sf -X POST "https://dockhand.example.com/api/backup/restore/preview" \
  -H "Content-Type: application/json" \
  -d '{ "destinationId": 25, "snapshotId": "1b9017739d10…" }'
# → { "volumes": [ "postgres-data" ], "volumeTypes": { "postgres-data": "volume" },
#     "backupTime": "…", "sourceEnvironmentId": 26, "hasMetadata": true }

Add a restore mode (and a target environment / destinations) to also get the exact host paths the restore will write to - resolved by the same logic the real restore uses - and a probe of whether each already holds data. helperOk: false means the backup helper cannot run on the target, so the restore would fail:

curl -sf -X POST "https://dockhand.example.com/api/backup/restore/preview" \
  -H "Content-Type: application/json" \
  -d '{ "destinationId": 25, "snapshotId": "1b9017739d10…", "mode": "new-location",
        "environmentId": 26, "targetType": "stack", "targetName": "blog",
        "volumeDestinations": [ { "volume": "html", "kind": "path", "target": "/srv/blog/html" } ] }'
# → { …, "targets": { "helperOk": true,
#       "volumes": [ { "key": "html", "type": "bind", "target": "/srv/blog/html", "hasData": "empty" } ],
#       "stackFiles": { "targetDir": "/app/data/stacks/prod/blog", "willWrite": true, "hasData": "has-data" },
#       "unresolved": [] } }

5. Restore a snapshot. Two modes - new-location (non-destructive: extracts the volume data to a fresh directory, nothing live is touched) and in-place (destructive: swaps the live volume's data). A new-location restore requires a targetPath - an absolute path on the target daemon's host where the data is extracted. This example does the safe, non-destructive restore:

curl -sf -X POST "https://dockhand.example.com/api/backup/restore" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "destinationId": 25,
    "snapshotId": "1b9017739d10…",
    "targetName": "postgres",
    "environmentId": 26,
    "mode": "new-location",
    "targetPath": "/tmp/postgres-restore"
  }'
# → { "status": "success", "executionId": 18042,
#     "restoredVolumes": [ "postgres-data" ], "targetPath": "/tmp/postgres-restore" }

For an in-place restore use "mode": "in-place" and "confirmOverwrite": true (no targetPath - it restores onto the live volume's own filesystem), plus a postRestore action (start | recreate for a container, redeploy for a stack, or none). The live target is stopped, its data is atomically swapped for the snapshot's, and the post-restore action brings it back.

For a stack restore the snapshot's secrets (stored encrypted) are restored to the target by default. Add "restoreSecrets": false to bring the stack up without them and set them by hand. Restoring secrets onto a different Dockhand instance requires that instance to have the same encryption key - see Stack secrets & backups.

A new-location stack restore also lands the captured compose and config alongside the volume data at targetPath, so you get a redeployable stack directory. Two options tune this:

• "skipStackFiles": true - restore the volume data only, leaving out the captured compose/config (useful when you already have the compose and just want the data back).
• Otherwise (default), the captured compose and config are restored and Dockhand registers the restored stack as managed - so you can edit and redeploy it. This always happens (it is not optional); for a remote environment the compose would otherwise live only on the remote host, leaving Dockhand nothing to manage.

To delete a snapshot: DELETE /api/backup/snapshots/{id}?destinationId=25. This runs restic forget --prune - safe to remove any snapshot without affecting the ones you keep (see How snapshots are stored).

Hawser remote agent

Hawser is a lightweight Go agent that enables Dockhand to manage Docker hosts in various network configurations, including hosts behind NAT, firewalls, or with dynamic IPs.

Connection modes

Hawser supports two operational modes:

Installation

Quick install script

The recommended way to install Hawser on Linux:

curl -fsSL https://raw.githubusercontent.com/Finsys/hawser/main/scripts/install.sh | bash

This script:

• Detects OS and architecture (Linux amd64/arm64)
• Downloads the latest release from GitHub
• Installs to /usr/local/bin/hawser
• Creates config directory at /etc/hawser/
• Installs systemd service (or OpenRC on Alpine)

Docker installation

Standard mode:

docker run -d \
  --name hawser \
  --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /opt/hawser-stacks:/opt/hawser-stacks \
  -e STACKS_DIR=/opt/hawser-stacks \
  -p 2376:2376 \
  -e TOKEN=your-secret-token \
  ghcr.io/finsys/hawser:latest

Edge mode:

docker run -d \
  --name hawser \
  --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /opt/hawser-stacks:/opt/hawser-stacks \
  -e STACKS_DIR=/opt/hawser-stacks \
  -e DOCKHAND_SERVER_URL=wss://your-dockhand.example.com/api/hawser/connect \
  -e TOKEN=your-agent-token \
  -e AGENT_NAME=my-server \
  ghcr.io/finsys/hawser:latest

Systemd service

Create /etc/systemd/system/hawser.service:

[Unit]
Description=Hawser - Remote Docker Agent for Dockhand
After=network-online.target docker.service
Wants=network-online.target
Requires=docker.service

[Service]
Type=simple
ExecStart=/usr/local/bin/hawser
Restart=always
RestartSec=10
EnvironmentFile=/etc/hawser/config

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable --now hawser

On Tailscale, WireGuard, or any dynamic-IP network, see Troubleshooting → Common issues for an important systemd-dependency caveat.

Configuration

Configure Hawser using environment variables or a config file at /etc/hawser/config:

Standard mode config

# Standard Mode Configuration
DOCKER_SOCKET=/var/run/docker.sock
PORT=2376
TOKEN=your-secret-token
AGENT_NAME=my-server
LOG_LEVEL=info

# Optional TLS
# TLS_CERT=/etc/hawser/server.crt
# TLS_KEY=/etc/hawser/server.key

Edge mode config

# Edge Mode Configuration
DOCKER_SOCKET=/var/run/docker.sock
DOCKHAND_SERVER_URL=wss://your-dockhand.example.com/api/hawser/connect
TOKEN=your-agent-token-from-dockhand
AGENT_NAME=my-server
LOG_LEVEL=info

# Connection settings
HEARTBEAT_INTERVAL=30
RECONNECT_DELAY=1
MAX_RECONNECT_DELAY=60

Environment variables reference

Global variables for stacks

Variables you set in the Hawser agent container's environment: (for example global folder paths like APP_DATA or LIB_GALLERY) are not visible to ${VAR} substitution when the agent runs your stacks. The agent runs docker compose with a clean environment on purpose - so a stray host or agent variable can never silently override a stack's value. Only the variables Dockhand sends for that stack are used.

So setting them on the agent has no effect - the stack sees nothing for ${APP_DATA}:

# Hawser agent compose (does NOT feed stack interpolation)
services:
  hawser:
    image: ghcr.io/finsys/hawser:latest
    environment:
      - APP_DATA=/srv/app        # invisible to your stacks

Instead, define those variables on the stack in Dockhand (the env panel or the stack's env file) - those reach compose interpolation on the agent:

# Stack env file in Dockhand
APP_DATA=/srv/app
LIB_GALLERY=/srv/pictures

Use absolute paths in these values. Compose does not re-expand a ${VAR} that appears inside another env-file value, so APP_DATA=${HOME}/app is taken literally and the deploy fails with refers to undefined volume ${HOME}/app. If you need a shell variable like ${HOME}, reference it directly in the compose file (- ${HOME}/app:/data), where the agent resolves it at deploy time.

TLS configuration

TLS certificate handling differs based on which side initiates the connection:

Standard mode TLS

When Hawser uses a self-signed TLS certificate, configure the CA certificate in Dockhand:

1. Go to Settings > Environments
2. Edit the Hawser Standard environment
3. Set protocol to HTTPS
4. Paste the CA certificate in the CA certificate field
5. Optionally enable Skip TLS verification for testing (insecure)

Edge mode TLS

When Dockhand uses a self-signed TLS certificate, configure the CA certificate on the Hawser agent:

# Edge mode with self-signed Dockhand certificate
DOCKHAND_SERVER_URL=wss://your-dockhand.example.com/api/hawser/connect
TOKEN=your-agent-token
CA_CERT=/etc/hawser/dockhand-ca.pem

# Or skip verification (insecure, for testing only)
# TLS_SKIP_VERIFY=true

Token management

Edge mode requires tokens generated in Dockhand:

1. Go to Settings > Environments
2. Create or edit an environment with "Hawser - Edge" connection type
3. Click Generate Token
4. Copy the token immediately (shown only once)
5. Configure Hawser on your Docker host with this token

Troubleshooting

Common issues