Dockhand User Manual

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.

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 an error is logged (and the process exits) if the 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

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.

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.

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). 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

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)

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

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.

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

  # 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 — defaults to order 0, sorted alphabetically among other 0s

  # 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.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 default to 0. Negative values are allowed to appear before unlabeled containers. 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 two 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.

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.

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.

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).

Three 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.

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.

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.

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:

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}

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

Important: Docker restart behavior

This affects only secrets — regular variables stored in .env files are read by Docker Compose and baked into the container configuration at deploy time, so they survive restarts.

Workarounds

1. Redeploy from Dockhand after a restart. Open the stack in Dockhand and click Deploy. Secrets are re-injected automatically during the deployment process.
2. Use scheduled deployments. Configure a Git stack auto-sync or a container auto-update schedule. This ensures stacks are periodically redeployed with fresh secrets, even after unattended restarts.
3. Minimize secret usage. Only mark truly sensitive values (passwords, tokens, private keys) as secrets. Configuration values that are not sensitive (ports, log levels, feature flags) should remain as regular variables in the .env file, where they survive Docker restarts.

Why this happens

Docker Compose stores container configuration (image, ports, volumes, networks) in Docker's internal state — but not the shell environment used during docker compose up. When Docker restarts a container, it uses the stored configuration, which includes variables from .env files (these were resolved at deploy time) but not the transient shell environment where secrets were injected.

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 the Docker restart caveat.

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:

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"

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.

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

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.

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, enable/disable, run one now, or delete. This is also where you set the cron schedule, retention, and volume selection.
• 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.

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 with the credentials embedded in the URL:

• Repository: rest:http://dockhand-user:a-strong-password@<rest-host>:8000/my-backups

The last path segment (my-backups) is the repository name — restic creates it on init. Use rest: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. Two free, open-source options that run as a single container are MinIO and Garage. Pick whichever fits your topology.

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).

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

[Unit]
After=network-online.target docker.service
Wants=network-online.target
Requires=docker.service
# Do NOT use Requires= or BindsTo= for network targets

[Service]
Restart=always
RestartSec=5

sudo systemctl daemon-reload
sudo systemctl restart hawser

Debug mode

Enable detailed logging:

LOG_LEVEL=debug hawser

Check logs

# Systemd
sudo journalctl -u hawser -f

# Docker
docker logs -f hawser

Settings

Configure Dockhand behavior, environments, authentication, and integrations.

General settings

Theme and appearance Since 1.0.4

Customize the look and feel of Dockhand:

• Theme - Choose between light and dark themes. The theme toggle is also available in the header for quick switching
• Font family - Select a font for the interface (Inter, System, Monospace)
• Grid font size - Adjust the font size in data tables (Small, Medium, Large)

Navigation Since 1.0.41

Choose where Dockhand starts and where environment tiles lead:

• Open the app on - the page Dockhand lands on when you open it (Dashboard, Compose stacks, Containers, and any other sidebar page). Environment-scoped pages open on your last-used environment.
• Environment click - the page a click on an environment tile on the Dashboard navigates to (e.g. Compose stacks or Containers).

Set these globally under Settings → General → Navigation, and override them per-user under Profile → Navigation (each dropdown offers a Use global default option). The dropdowns only list pages you can actually reach - in Enterprise, environment-scoped RBAC and disabled features are respected, and a landing page pointing at an environment outside your scope falls back to an accessible one or the Dashboard.

Editor indentation guides Since 1.0.42

Toggles vertical indentation guides in the compose / YAML editor to make nested blocks easier to follow. Off by default; find it under Settings → General.

Column customization Since 1.0.4

Data grids throughout Dockhand support column customization:

• Resize columns - Drag column borders to adjust width
• Show/hide columns - Click the columns button to toggle visibility
• Reorder columns - Drag columns up/down in the settings popover
• Reset to defaults - Restore original column configuration

Column preferences are saved per user (when authenticated) or globally (when auth is disabled).

Display preferences

Timezone handling

Dockhand runs scheduled tasks (container auto-updates, Git stack syncs) using cron expressions. Each environment can have its own timezone setting, which affects:

• Schedule execution - A "daily at 3:00 AM" schedule runs at 3:00 AM in the environment's local timezone, not the server's timezone
• Next run display - The "Next run" time shown in the Schedules page is calculated in the environment's timezone and displayed correctly
• Multi-region deployments - If you manage Docker hosts across different timezones, each environment can have updates scheduled for their local maintenance windows

Vulnerability scanner defaults

Configure default CLI arguments for vulnerability scanners. These settings allow you to adjust scanner behavior if Trivy or Grype CLI options change in future versions, or to add custom flags for your environment:

• Grype CLI args - Default: -o json -v {image}
• Trivy CLI args - Default: image --format json {image}

The {image} placeholder is replaced with the actual image name at scan time.

Cleanup jobs

Configure automatic cleanup of old data to prevent database growth:

Each cleanup job can be enabled/disabled independently with configurable retention periods (1-365 days). Jobs run automatically on a daily schedule.

Honor reverse-proxy labels Since 1.0.34

When enabled (the default), Dockhand reads labels written by Traefik, Pangolin, and caddy-docker-proxy and surfaces the resulting public URL as a clickable pill next to a container's ports. No network call, no extra configuration — the parser runs client-side on labels Docker already gives us. Turn the toggle off to hide all proxy-derived URLs; only explicit dockhand.url labels (see Container labels) will be shown.

Supported label vocabularies:

• Traefik — parses traefik.http.routers.<name>.rule for Host() entries, with PathPrefix() appended where present. Multiple Host() entries combined with || produce multiple URLs. Scheme is inferred from traefik.http.routers.<name>.tls=true or the entrypoints label (websecure/https → https, web/http → http; defaults to https). Rules using HostRegexp() are skipped.
• Pangolin — parses pangolin.proxy-resources.<name>.full-domain and .protocol. The display label comes from the optional .name field. Internal target ports (targets[N].port) are ignored — Pangolin terminates at the public host. See the Pangolin Blueprints docs.
• caddy-docker-proxy — parses the site-address value of the bare caddy label (or caddy_<N> for isolated groups). A comma-separated value produces multiple URLs; a path in the address (example.com/api/*) is kept. Directive labels (caddy.reverse_proxy, caddy_0.tls, ...) carry a dot after the prefix and are ignored. Scheme is https unless the address specifies http://.

Precedence: the explicit dockhand.url label always wins over both Traefik and Pangolin parsing — set it when you want a specific URL or display name regardless of what the proxy labels say. Per-port overrides via dockhand.port.<hostPort>.url apply only to that specific port badge.

Example showing both vocabularies on a stack:

services:
  grafana:
    image: grafana/grafana
    labels:
      # Pangolin blueprint
      - "pangolin.proxy-resources.grafana.name=Grafana"
      - "pangolin.proxy-resources.grafana.full-domain=grafana.example.com"
      - "pangolin.proxy-resources.grafana.protocol=https"

  whoami:
    image: traefik/whoami
    labels:
      # Traefik router
      - "traefik.http.routers.whoami.rule=Host(`whoami.example.com`)"
      - "traefik.http.routers.whoami.entrypoints=websecure"
      - "traefik.http.routers.whoami.tls=true"

  blog:
    image: ghost
    labels:
      # caddy-docker-proxy site address
      - "caddy=blog.example.com"

Show changelog links Since 1.0.34

When enabled (the default), Dockhand surfaces a release-notes icon next to an image name whenever an update is available. Clicking it opens the project's changelog in a new tab. The link is resolved client-side from image metadata you already have — no network call, no extra configuration on Dockhand's side. Turn the toggle off to hide the icon everywhere.

Resolution priority:

1. The dockhand.changelog.url label, if set on the container (see Container labels). Wins over the automatic tiers below.
2. The OCI standard org.opencontainers.image.source label, when it points at github.com. The release page is <source>/releases.
3. The GHCR heuristic — ghcr.io/<owner>/<repo> images map to github.com/<owner>/<repo>/releases.

If none of the tiers resolves a URL (e.g. nginx:latest from Docker Hub with no labels), no icon is rendered. Add a dockhand.changelog.url label at container runtime to force a specific URL:

services:
  myapp:
    image: nginx:latest
    labels:
      - "dockhand.changelog.url=https://nginx.org/en/CHANGES"

Since 1.0.43 The label may contain a {{version}} (or {{tag}}) placeholder, replaced with the newer version tag so the link points at that exact release. This is handy for monorepos that publish an image under a prefixed release stream:

services:
  bifrost:
    image: maximhq/bifrost:1.6.11
    labels:
      - "dockhand.changelog.url=https://github.com/maximhq/bifrost/releases/tag/transports/{{version}}"

Appearance

Customize the look and feel of Dockhand:

Environments

Manage Docker environment connections.

Connection types

Where stack files live, per connection type

When you deploy a compose stack, Dockhand keeps the stack's files (the compose file, .env, and any relative-bind sources like ./nginx.conf or ./data) in a stack directory. A relative bind resolves against that directory, so Docker can only mount it if the files are on the same host as the daemon. How that works depends on the connection type:

Environment options

• Name - Display name for the environment
• Remote stacks directory Since 1.0.41 (Direct environments only) - absolute path on the remote host where Dockhand stages compose and relative-bind files before deploying, so stacks with ./config / ./data binds work. See Where stack files live. Leave empty to require named volumes or absolute paths.
• Icon - Custom icon from icon library
• Labels - Tags for filtering (with colors)
• Public IP - IP address or hostname for clickable port links. When set, port badges on containers become clickable links that open services in your browser (e.g., http://192.168.1.100:8080)
• Timezone - Local timezone for this environment (e.g., Europe/Warsaw, America/New_York). Used for scheduling auto-updates and displaying "Next run" times correctly. See General settings for more details on timezone handling
• Default environment - Selected by default on page load
• Collect metrics - Enable CPU/memory monitoring
• Collect activity - Track container events
• Highlight changes - Visual indicators for stat changes

Renaming or deleting an environment

Every environment owns two directories on the Dockhand host, both named after the env:

• $DATA_DIR/stacks/<envName>/ — the in-app editor source for every stack on this env (and for socket/direct envs, the actual deploy directory)
• $DATA_DIR/git-repos/<envName>/ — the local clone cache for every git stack on this env

This affects what you can safely do on rename and delete.

Renaming

When you change the name in the edit modal, Dockhand atomically moves both directories from the old name to the new name before updating the database. If either rename fails (target directory already exists, cross-filesystem move, permission error), the database stays at the old name and an error is shown — you never end up with a database that points at directories that don't exist.

You'll see a confirmation dialog listing the exact paths that will be moved and a count of the stacks tracked on this env. For socket and direct environments the dialog also warns that each stack must be redeployed after the rename. The reason: running containers carry the old absolute path in their compose project labels (com.docker.compose.project.working_dir). They keep running until they restart, then the old path is gone and compose can't find them. Redeploying recreates the containers with the new path baked in.

For Hawser standard and Hawser edge environments the deploy directory lives on the agent host and doesn't include the env name — running containers there don't care about the rename, only the Dockhand-side editor source and git clone cache move.

Deleting

Deleting an environment shows a confirmation dialog listing the same two directories that will be permanently removed plus the count of stacks tracked. Containers running on the Docker or Hawser host are not stopped — only the Dockhand-side records and on-disk staging directories are wiped. Stop or remove those containers separately before or after the delete if you want them gone too.

Activity collection mode Since 1.0.7

When activity collection is enabled, you can choose how Dockhand receives container events:

Event poll interval - When using Poll mode, how often Dockhand queries for new container events. Default 60 seconds; selectable values are 30 / 60 / 120 / 300 seconds. Lower values mean faster event detection but higher CPU usage. (Ignored in Stream mode, where events arrive instantly.)

Metrics collection interval - A separate setting for how often CPU and memory metrics are collected. Default 30 seconds; selectable values are 10 / 30 / 60 / 120 seconds.

Updates tab

Configure scheduled update checks for all containers in the environment:

• Scheduled update check - Enable periodic checks for image updates
• Schedule - When to check (daily, weekly, or custom cron)
• Auto-update - Automatically deploy updates when found
• Vulnerability criteria - Block updates based on scan results (when scanning is enabled)
• Timezone - Local timezone for scheduling (affects when cron jobs run)

Vulnerability scanning

Per-environment scanner configuration:

• Scanner - None, Grype, Trivy, or Both

Scanner CLI arguments are configured globally in Settings > General > Vulnerability scanner defaults.

Registries

Configure Docker registries for image operations.

• Name - Display name
• URL - Registry endpoint
• Username/Password - Authentication credentials
• Default - Set as default for pull operations

Git

Manage Git credentials and repositories for stack deployment.

Credentials

• SSH keys - For SSH authentication
• HTTPS credentials - Username/password or token

Repositories

• URL - Git repository URL
• Branch - Default branch to track
• Credential - Link to saved credential

Config sets

Config sets are reusable configuration templates that can be applied when creating containers. They help maintain consistency and save time when deploying multiple containers with similar configurations.

What's included in a config set

• Environment variables - Predefined key-value pairs
• Labels - Container labels for organization and filtering
• Port mappings - Common port configurations
• Volume mounts - Standard volume configurations
• Network mode - Network settings (bridge, host, etc.)
• Restart policy - Container restart behavior

Using config sets

1. Go to Settings > Config sets
2. Click Add config set
3. Enter a name and configure the desired options
4. Save the config set
5. When creating a new container, select the config set from the dropdown to pre-fill values

Notifications

Configure notification channels for alerts.

Channel types

• SMTP — Email notifications via SMTP server
• Webhooks — One or more webhook URLs per channel. Supports Discord, Slack, Mattermost, Telegram, ntfy, Gotify, Pushover, MQTT, Bark, Signal, Apprise (passthrough to any caronc/apprise-supported provider), Microsoft Teams (via Workflows), Zabbix (via history.push), and generic JSON.

Webhook URL formats

A webhook channel takes one or more URLs (one per line). The URL scheme picks the provider Dockhand talks to:

Bark options Since 1.0.33

Bark URLs accept these optional query parameters (e.g. bark://host/key?sound=minuet&level=critical&group=dockhand):

Event types

Each event below is an individual toggle. Environment-scoped events are configured per environment (Settings → Environments → the environment's Notifications), so different environments can notify on different channels. System-scoped events are not tied to an environment and are configured on the notification channel itself.

Authentication

Configure user authentication and access control.

General settings

• Enable authentication - Toggle auth for the application
• Session timeout - Session expiration (1 hour to 7 days), or toggle "Never expire" to keep sessions signed in until logout

Local users

Create and manage local user accounts:

• Username, display name, email
• Password (Argon2id hashed)
• Admin role toggle
• Avatar upload
• Enable/disable account

OIDC/SSO

Configure Single Sign-On with OpenID Connect providers.

Supported providers

• Google
• Microsoft Azure AD
• Okta
• Keycloak
• Auth0
• Any OIDC-compliant provider

Configuration

• Name - Provider display name
• Issuer URL - OIDC discovery endpoint
• Client ID - OAuth client ID
• Client secret - OAuth client secret
• Scopes - OAuth scopes (default: openid profile email)

LDAP/Active Directory Enterprise

Connect to LDAP or Active Directory for user authentication.

Connection settings

• Server URL - LDAP server (e.g., ldap://ldap.example.com:389)
• Bind DN - Service account DN for searching
• Bind password - Service account password
• Base DN - Search base (e.g., dc=example,dc=com)

User search

• User filter - LDAP filter template
  • OpenLDAP: (uid={{username}})
  • Active Directory: (sAMAccountName={{username}})
• Username attribute - Attribute for username (uid, sAMAccountName)
• Email attribute - Attribute for email (mail)
• Display name attribute - Attribute for display name (cn)

Group settings

• Group base DN - Where to search for groups
• Admin group - Group DN for admin access
• Member filter - Filter to find user's groups

TLS settings

• Enable TLS - Use LDAPS or StartTLS
• CA certificate - Custom CA for verification

Roles (RBAC) Enterprise

Configure role-based access control for granular permissions.

System roles

• Admin - Full access to everything
• Operator - Manage containers, images, stacks
• Viewer - Read-only access

Custom roles

Create roles with granular permissions:

• Containers - view, create, edit, start/stop, remove, exec, logs
• Images - view, pull, remove
• Volumes - view, create, remove, browse
• Networks - view, create, remove
• Stacks - view, create, edit, deploy, remove
• And more...

Environment scoping

Custom roles can be scoped to specific environments:

• All environments - Role applies everywhere
• Specific environments - Role only applies to selected environments

License

Activate and manage your Enterprise license.

Enterprise features

An Enterprise license unlocks:

• Role-based access control (RBAC)
• LDAP/Active Directory integration
• Audit logging
• Priority support

Activation

1. Enter your license name (customer name)
2. Enter your license key
3. Click Activate

The license is validated against:

• Customer name
• Hostname (or wildcard)
• Expiration date
• Cryptographic signature

Enterprise features

Enterprise edition adds advanced security and compliance features for organizations.

Role-based access control

RBAC provides fine-grained control over who can access what:

• Users can be assigned multiple roles
• Roles define permissions for resources and actions
• Environment scoping limits role access to specific environments

Free vs Enterprise

Audit logging

Track all user actions for compliance and security auditing.

Audit logs capture:

• Who performed the action (user)
• What action was performed (create, update, delete, start, stop, etc.)
• What resource was affected (container, image, stack, etc.)
• When the action occurred (timestamp)
• Additional context (IP address, user agent)

Multi-factor authentication

Add an extra layer of security with TOTP-based MFA. This feature is available in both free and enterprise editions for local user accounts.

Compatible authenticator apps

Any TOTP-compatible authenticator app works with Dockhand:

• Google Authenticator (iOS, Android)
• Microsoft Authenticator (iOS, Android)
• Authy (iOS, Android, Desktop)
• 1Password, Bitwarden, and other password managers with TOTP support

Setup process

1. Go to your Profile page (click your avatar in the header)
2. Click Enable MFA in the Security section
3. Scan the QR code with your authenticator app, or manually enter the secret key
4. Enter the 6-digit verification code from your app to confirm setup
5. Important: Save the backup codes displayed - these are your recovery codes

Logging in with MFA

After entering your username and password, you'll be prompted for the 6-digit code from your authenticator app. Codes refresh every 30 seconds.

Recovery options

• Backup codes - Each backup code can be used once to bypass MFA
• Admin reset - Administrators can disable MFA for a user in Settings → Auth → Users
• Emergency script - Use /app/scripts/reset-mfa.sh username if locked out (see Emergency scripts)

Disabling MFA

To disable MFA on your account:

1. Go to your Profile page
2. Click Disable MFA
3. Enter your current password to confirm

Keyboard shortcuts

Global

Terminal

Troubleshooting

Dockhand won't start

• Check Docker socket is accessible: docker ps
• Verify port 3000 is not in use
• Check container logs: docker logs dockhand

Can't connect to environment

• Verify Docker is running on the target host
• Check firewall rules allow connection
• For Hawser: verify agent is running and token is correct

Terminal / live updates don't work behind a reverse proxy

The container terminal, container logs, real-time dashboard updates, and the Hawser Edge connection all rely on WebSocket and server-sent-event upgrades. If the page loads but the terminal never connects, logs don't stream, or tiles never refresh, the reverse proxy in front of Dockhand is almost certainly dropping the connection upgrade.

The proxy must forward the Upgrade and Connection headers and speak HTTP/1.1 to the upstream. See the Nginx reverse proxy example for the full location / block. The three lines that matter:

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

If a static Connection "upgrade" still doesn't fix it (some setups need the header to vary per request), use the canonical Nginx WebSocket map instead — define it once in the http { } block and reference it in the location:

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

location / {
    proxy_pass http://dockhand:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade    $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_set_header Host       $host;
}

A proxy missing these headers lets the UI load over plain HTTP while silently blocking every WebSocket/SSE feature, so the symptom looks like a broken terminal or frozen dashboard rather than a connection error. Traefik and Caddy handle the upgrade automatically; Nginx and Apache need it configured explicitly.

Environment offline after Docker engine update

After updating the Docker engine on the host, Dockhand may show the local environment as offline and report ECONNREFUSED errors — even though docker ps works fine on the host.

Why this happens: This is a Linux kernel limitation, not a Dockhand issue. When the Docker engine restarts, it creates a new Unix socket (/var/run/docker.sock) with a new inode. However, the bind mount inside the Dockhand container still references the old inode — Linux provides no way to rebind or refresh a changed inode inside an existing mount namespace. The container is left holding a stale file descriptor, and all connections to the socket fail. This affects any containerized application that mounts the Docker socket.

Solution: Restart the Dockhand container to get a fresh mount of the new socket:

docker restart dockhand

There is no data loss — Dockhand picks up right where it left off after restart.