Dockhand by JigSawFr

Dockhand packaged cleanly for Home Assistant OS / Supervisor.
Docker management through Home Assistant Ingress, with persistent data, beta channel, and multi-arch GHCR images.

---

Why this add-on?

Dockhand is a modern, lightweight Docker management UI — a cleaner Portainer-style experience for day-to-day container operations.

This repository wraps Dockhand as a Home Assistant add-on with:

• Home Assistant Ingress as the default access path.
• Persistent /data storage for Dockhand database and app data.
• Multi-arch images for aarch64 and amd64.
• Stable + beta channels so risky wrapper changes can be tested first.
• Explicit security documentation for Docker socket access.

Community project: this add-on is not affiliated with Dockhand, Finsys, or Home Assistant.

Install

Stable channel

Best for normal use.

Manual repository URL:

https://github.com/JigSawFr/dockhand-ha-addon

Repository name in Home Assistant:

Dockhand by JigSawFr

Beta channel

Best for testing wrapper changes before stable promotion.

Add this repository URL manually:

https://github.com/JigSawFr/dockhand-ha-addon#dev

Repository name in Home Assistant:

Dockhand Beta by JigSawFr

Beta versions look like 1.0.41.2-beta.1 and publish GHCR tags beta plus the exact version. See Release channels.

First start

1. Install Dockhand from the selected repository.
2. Open the add-on page.
3. Disable Protection Mode.
4. Start the add-on.
5. Open Dockhand from the Home Assistant sidebar or Ingress button.
6. The add-on creates a default Home Assistant Docker environment automatically when no equivalent /var/run/docker.sock environment exists.

Useful Dockhand setting: enable automatic image pruning under environment Updates to reduce image buildup.

Security, plainly

Dockhand manages Docker. This add-on therefore needs access to the Docker socket and requires Protection Mode disabled.

That is powerful access. Treat it like Portainer:

• install it only on Home Assistant systems you administer;
• keep access through Home Assistant Ingress where possible;
• do not expose the optional direct port to the public internet;
• read the Security model before sharing access with other users.

Defense-in-depth included by the wrapper:

• Home Assistant's admin-only panel default;
• dedicated direct proxy endpoint on 3001/tcp, denied without a configured proxy token and with host publication disabled by default;
• Dockhand itself kept on loopback-only 127.0.0.1:3000;
• Docker HEALTHCHECK using the packaged healthcheck helper;
• Ingress streaming support for long-lived UI flows;
• packaged AppArmor profile validation on beta before stable promotion;
• Home Assistant backup hooks for the SQLite database;
• safe support bundle generation with redaction tests;
• release dry-run, SBOM/provenance, and image signing for release automation.

Channels at a glance

Channel	Home Assistant repository	Branch	Current version	Versions	GHCR tags
Stable	Dockhand by JigSawFr	main	1.0.48.1	X.Y.Z, X.Y.Z.N	<version>, latest
Beta	Dockhand Beta by JigSawFr	dev	1.0.48.1-beta.2	X.Y.Z.N-beta.M	<version>, beta

Stable users do not receive beta builds unless they explicitly add the #dev repository URL.

Add-on options

Option	Default	Purpose
seed_home_assistant_environment	true	Create a default Home Assistant Docker environment for /var/run/docker.sock when no equivalent environment exists.
auto_backup_on_start	true	Create a lightweight SQLite backup during startup.
backup_retention	5	Keep the newest local startup backups.

Versioning

The add-on version stays anchored to the bundled Dockhand version.

Example:

Surface	Example
Bundled Dockhand image	fnsys/dockhand:v1.0.43
Beta preview of the new upstream	1.0.43.1-beta.1
Stable release of that preview	1.0.43.1
Stable wrapper-only fix on top	1.0.43.2

Wrapper-only stable updates use numeric revisions (X.Y.Z.N) so Home Assistant can sort them as updates from X.Y.Z. A beta must carry a revision (X.Y.Z.N-beta.M), so an upstream bump validated through beta lands on X.Y.Z.1 rather than a bare X.Y.Z.

Documentation

• Installation
• Release channels
• Security model
• Architecture
• Migration
• Backup and restore
• Support bundle
• Supply-chain posture
• Troubleshooting
• Release process

Attribution

This project is based on the Apache-2.0 licensed work from alexschwantes/home-assistant-dockhand-app, adapted for independent community maintenance.

Dockhand itself is developed by Finsys. This repository packages the upstream application; it does not replace upstream Dockhand licensing, privacy, or support terms.

Resolved / mitigated issues

• Authentication enable flow: the Home Assistant ingress shim now redirects to Dockhand login automatically after authentication is enabled successfully.
• Ingress stream disconnect noise: ingress_stream: true and unbuffered stream proxying are enabled. A one-off stream close while navigating away from live views can still be benign.