Docker & Containers

Goodbye Portainer: Deploy Dockhand for Modern Multi-Server Docker Management

Dockhand Docker management interface showing multi-server container control and Hawser agent connections
Dockhand running as a modern web-based Docker management dashboard with remote Hawser agent nodes and zero commercial licensing walls.

For nearly a decade, Portainer was the default web UI for anyone building a home lab or managing containerized workloads on bare-metal servers. It simplified container creation, network bridging, volume management, and image pulls for millions of self-hosters. However, recent commercial pivots have changed that reality.

Portainer officially froze its open-source Community Edition (CE) at version 2.45. Moving forward, Portainer 3.0 transitioned to a closed-source Business Edition architecture. To run version 3.0, users are required to sign up for an enterprise account, paste a commercial license key, and accept strict licensing limitations that restrict free installations to three nodes before billing per environment.

For homelabbers running three Proxmox nodes, a secondary storage host, and a handful of remote virtual machines, that 3-node wall is an immediate dead end. Fortunately, an open-source tool named Dockhand has arrived to solve this problem cleanly. Dockhand provides unlimited free node management, runs with zero telemetry, includes a built-in container file browser and editor, and features native Trivy and Grype vulnerability scanning.

Why Homelab Users Are Switching Away from Portainer

1. Licensing Walls: Portainer 3.0 mandates commercial registration and caps free management at 3 environments.
2. Telemetry & Account Binding: Version 3.0 requires persistent phone-home validation for license checks.
3. Heavy Overhead: Dockhand starts instantly, maintains a streamlined footprint, and does not require complex RBAC databases just to inspect a local stack.

What Is Dockhand?

Dockhand is an open-source, web-based management layer for Docker written specifically for speed, simplicity, and self-hosted privacy. It connects directly to the local Docker socket on your primary host and communicates with remote servers via a dedicated daemon called Hawser.

Unlike monolithic enterprise dashboards, Dockhand focuses on the exact day-to-day operations homelabbers and DevOps engineers care about:

  • Zero Telemetry: No tracking scripts, no cloud logins, and no external registration gates.
  • Unlimited Free Environments: Connect two, ten, or fifty Docker hosts across your network without encountering license upgrade prompts.
  • Integrated File Explorer: Browse, download, and edit configuration files directly inside container filesystems without launching an interactive terminal shell.
  • Real-Time Web Terminal & Logs: Instant shell access and streaming stdout/stderr log output with ANSI color support.
  • Docker Compose Stack Inspection: View running stacks, inspect underlying Compose definitions, and validate configuration syntax.
  • Built-In Security Auditing: Run automated Trivy or Grype CVE vulnerability checks on your container images.
  • Gotify & Webhook Alerts: Route container health notifications and backup statuses to your self-hosted notification relays.

Step 1: Deploying Dockhand with Docker Compose

Dockhand runs as a single container image distributed via Docker Hub as fnsys/dockhand:latest. To deploy it on your primary server, create a dedicated directory and write a docker-compose.yml file.

mkdir -p /opt/dockhand
cd /opt/dockhand
nano docker-compose.yml

Paste the following Compose configuration. This sets up persistent storage in a local Docker volume, maps port 3000 to the host, and binds the host Docker socket into the container so Dockhand can control local workloads:

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

volumes:
  dockhand_data:
    driver: local

Save the file and start the container in detached mode:

docker compose up -d

Once started, open your web browser and navigate to http://<your-server-ip>:3000.

Dockhand initial setup dashboard showing local Docker socket environment connected
Dockhand's primary dashboard showing active containers, memory utilization, and local Docker socket connectivity.

Critical First Step: Initial User Creation & Authentication

When you first access Dockhand, authentication is not locked down by default to allow smooth initial provisioning. Do not skip creating your administrator account.

Click the Settings gear icon in the left-hand navigation pane, navigate to the Users tab, and click Add User. Create your username and assign a strong passphrase.

Important: Do Not Enable Auth Toggle Before User Creation

In the general settings tab, there is a global toggle to enforce authentication. Never turn this toggle on before you have explicitly created and tested an administrator account in the Users menu. If you enable the toggle first with an empty user database, you will lock yourself out of the web interface and will need to wipe the dockhand_data volume to recover.

Connecting the Local Host Environment

After securing user credentials, navigate to Settings → Environments. Click Add Environment, label the host as Localhost, and select the local Unix socket radio option (/var/run/docker.sock). Save the environment. You can now return to the main dashboard to view all containers currently executing on your primary machine.

Step 2: Connecting Remote Nodes with the Hawser Agent

Managing a single host is convenient, but the real power of Dockhand lies in multi-server administration without license restrictions. Rather than exposing insecure, unauthenticated TCP Docker sockets across your network, Dockhand relies on Hawser.

Hawser is a lightweight, compiled Go agent designed to run as a systemd background service on remote Linux hosts. It listens on port 2376 and enforces pre-shared secret token authentication.

Dockhand multi-server environment view displaying containers running across a remote CouchDB host
Inspecting containers across a remote secondary server (an Obsidian CouchDB node) connected through the Hawser agent.

Installing Hawser on Remote Linux Hosts

SSH into your remote server (for example, a secondary Proxmox VM or a dedicated storage host). The Dockhand project provides an automated installation script that registers the systemd daemon:

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

The installer sets up the Hawser binary at /usr/local/bin/hawser and writes a default configuration file at /etc/hawser/config. Open this configuration file in your editor:

sudo nano /etc/hawser/config

Ensure the port is set to 2376 and define a secure secret token:

port: 2376
token: "YOUR_SUPER_SECRET_AUTHENTICATION_KEY_HERE"
docker_socket: "/var/run/docker.sock"

Restart and enable the Hawser systemd service so it boots automatically:

sudo systemctl restart hawser
sudo systemctl enable hawser
sudo systemctl status hawser

Registering the Remote Host in Dockhand

Return to the Dockhand web interface on your primary server:

  1. Click Settings → Environments → Add Environment.
  2. Enter an identifiable name (for instance, Obsidian-CouchDB-Host).
  3. Select the Hawser Agent connection type.
  4. Enter the remote server IP address (e.g., 192.168.1.150:2376).
  5. Paste the exact shared secret token you defined in /etc/hawser/config.
  6. Click Save Environment.

Dockhand will perform a handshake with the remote Hawser daemon. Within two seconds, the new host will appear in the environment dropdown menu on your dashboard. You can switch between your primary host and remote nodes instantly with a single mouse click.

Step 3: In-Container File Editing and Terminal Access

One of Dockhand's standout features compared to Portainer and Dockge is its live filesystem explorer. In traditional managers, if you need to modify an Nginx configuration file, a JSON database file, or an application secret inside a container volume, you have to execute an interactive shell or SSH into the host and locate the volume mount path.

Inside Dockhand, click any container in your list and select the Files tab. You are presented with a file tree representing the live container filesystem. You can navigate directories, upload assets, download logs, and click any text file to open an integrated code editor. After making adjustments, clicking Save commits the file changes directly into the container storage layer.

If you need raw command-line access, click the Terminal tab. Dockhand attaches a responsive WebSocket shell using /bin/sh or /bin/bash, complete with tab completion and standard terminal shortcuts.

Step 4: Vulnerability Scanning & Gotify Notifications

Keeping container infrastructure patched against zero-day exploits requires ongoing awareness. Dockhand integrates security auditing directly into container views using standard scanners like Trivy and Grype.

Dockhand security tab showing Trivy vulnerability scan results and CVE breakdown for container images
Trivy vulnerability scan results inside Dockhand displaying package versions, CVE identifiers, and severity ratings.

Running an Image CVE Scan

From the container inspection view, switch to the Security tab. Click Run Vulnerability Scan. Dockhand dispatches a scan request against the image layers, comparing installed libraries against updated vulnerability databases.

The output breaks down findings by severity (Critical, High, Medium, Low), displaying the affected Debian or Alpine package name, the patched version required, and direct hyperlinks to the National Vulnerability Database (NVD) CVE entry.

Setting Up Gotify Webhook Notifications

To receive real-time push alerts on your phone or desktop when containers unexpectedly crash or fail health checks, you can pair Dockhand with a self-hosted Gotify notification server:

  1. Open Settings → Notifications.
  2. Select Gotify from the provider list.
  3. Enter your Gotify instance URL (e.g., https://gotify.yourdomain.com).
  4. Enter your Gotify application token.
  5. Select event triggers: container status change, failed health checks, and scheduled scan alerts.

Click Send Test Notification to verify network connectivity. For a detailed guide on standing up your own lightweight push relay, check our tutorial on setting up self-hosted push notifications with Gotify.

Dockhand vs. Portainer vs. Dockge: Technical Comparison

Choosing the right Docker manager depends on the scope of your home lab and whether you manage single or multiple hosts. Here is how Dockhand stacks up against Portainer CE and Dockge:

Feature Dockhand Portainer CE / 3.0 Dockge
License Model 100% Free & Open Source CE Frozen at 2.45; 3.0 Commercial (3 Node Limit) 100% Free & Open Source
Telemetry Zero (Completely Private) Mandatory License Calls in 3.0 Zero
Multi-Host Management Native via Hawser Agent (Unlimited) Native via Portainer Agent (Capped in 3.0) Host-to-host agent links
In-Container File Editor Yes (Integrated web file tree) No (Terminal exec only) No (Compose YAML only)
CVE Vulnerability Scanning Yes (Trivy & Grype built-in) Requires Business Edition No
Compose Management Stack viewer & validator Custom Stacks & Templates Native Compose-centric UI
Resource Footprint Lightweight (~60MB RAM) Medium (~120MB+ RAM) Very Low (~35MB RAM)

If your primary focus is purely creating Compose files in markdown with reactive live updating on a single node, you might also consider exploring Docker vs Podman architectures. However, if you need a true Portainer replacement that can control multiple servers, audit container security, browse files, and provide centralized management without enterprise licensing fees, Dockhand is the clear winner.

Common Pitfalls & Troubleshooting

  • Docker Socket Permission Denied (Error 13): If Dockhand fails to display containers on the local host, verify that the user running the Docker daemon has write permissions on the socket with sudo usermod -aG docker $USER. Confirm that the socket is mounted into the container as /var/run/docker.sock:/var/run/docker.sock in your Compose YAML.
  • Hawser Agent Connection Timeout on Port 2376: If Dockhand cannot connect to a remote Hawser node, check your remote firewall rules (UFW or firewalld). Port 2376 must be open to your primary Dockhand host: sudo ufw allow from 192.168.1.100 to any port 2376 proto tcp.
  • Token Mismatch Errors: If Dockhand returns an authentication failure when adding a remote host, verify there are no trailing whitespace characters or unescaped quotes in /etc/hawser/config on the remote server. Restart the service after making edits.

Frequently Asked Questions

Can I run Dockhand alongside Portainer while migrating?

Yes. Because Docker containers and the Docker engine are decoupled from web management dashboards, you can run both Dockhand and Portainer simultaneously on the same host without conflict, provided they are bound to different host ports (e.g., Dockhand on port 3000 and Portainer on port 9443).

Does Dockhand support Docker Swarm clusters?

Dockhand is currently optimized for standalone Docker engines and multi-node standalone hosts connected via Hawser. If you require advanced Swarm service scheduling and overlay network configuration, tools like Arcane or legacy Portainer CE 2.45 remain options for Swarm-specific deployments.

How are Dockhand container backups handled?

Dockhand stores all its internal database state, environment records, and user authentication tables inside the mapped /app/data volume. To back up your Dockhand instance, simply create a snapshot or tar archive of the dockhand_data volume while the container is paused or stopped.

Key Takeaways & Next Steps

Deploying Dockhand with the Hawser agent restores unrestricted, multi-server Docker management to your home lab. With an in-container file tree, built-in vulnerability auditing, zero telemetry, and no commercial licensing caps, you can build out your container infrastructure with complete peace of mind.

Explore our companion guides and web utilities to build out your homelab:

Written by Tech Simpld

MCSA Certified Systems Engineer • 20+ Years Enterprise IT

Tech Simpld is maintained by a Systems Engineer managing virtual machines and enterprise storage architecture across five data centers. Every tutorial and configuration on this site is tested first-hand in our physical Proxmox VE home lab and daily production vaults.