Installation

Install Homelab Hand with Docker, run it behind HTTPS, and configure it.

Homelab Hand runs as a single Docker container with an SQLite database inside a Docker volume. You can try it on your laptop in a minute, then install it on a server that can reach the machines you want to manage.

Requirements

Option 1: try it locally

From the project folder on a machine with Docker:

./start.sh

The script:

• creates .env with a random HUB_SECRET_KEY;
• builds the image and starts the hub at http://localhost:8080 (use HUB_PORT=9090 ./start.sh to pick another port);
• mounts your Docker socket and adds it as an environment named after your machine, so there's something to look at straight away.

Stop it with ./stop.sh. To wipe the test data completely:

docker compose -f docker-compose.local.yml down -v

Without Docker, ./run-without-docker.sh creates .venv, installs the dependencies and keeps data in ./data.

Option 2: install on a server

1. Copy the project to the serverfor example to /opt/htech-hub.
2. Create the configuration

   cd /opt/htech-hub
   cp .env.example .env
   openssl rand -hex 32      # paste the output into .env as HUB_SECRET_KEY

   Then set HUB_ORIGIN (the address you'll browse to) and HUB_RP_ID (just its hostname). See environment variables.
3. Start it

   docker compose up -d --build

4. Optional: manage this server's own Dockeruncomment the Docker socket mount and group_add in docker-compose.yml, then run docker compose up -d again.
5. Open itand create the first admin account (see First steps).

Install and update with deploy.sh

From your workstation, deploy.sh does all of the above over SSH and handles every later update with the same command:

DEPLOY_HOST=root@192.168.1.20 ./deploy.sh

It copies the code, creates .env with a secret on the first run only, writes a server compose file (port 8756, Docker socket, auto-registered local environment), builds, starts and waits for the health check. The update swaps the new code in atomically. See Operations for the one-time key setup and options.

HTTPS and reverse proxy

Use HTTPS for anything beyond a quick test. Passkeys require it, and it protects your session cookie, agent tokens and terminal traffic. Any reverse proxy works (Nginx Proxy Manager, Traefik, Caddy or a Cloudflare Tunnel) as long as it:

• forwards WebSockets (terminals, agents, Hawser Edge, live camera video, the live map);
• passes X-Forwarded-For and X-Forwarded-Proto;
• doesn't buffer long responses (log tails and job output stream).

Caddy example:

hub.example.com {
    reverse_proxy hub:8080
}

Then set, in .env:

HUB_ORIGIN=https://hub.example.com
HUB_RP_ID=hub.example.com
HUB_TRUSTED_PROXIES=172.18.0.5      # your proxy / tunnel connector's IP

Using Cloudflare? Follow Cloudflare Tunnel and Cloudflare Access. The iOS app supports Access service tokens.

Environment variables

In-app settings

Most behaviour is set in the UI, under Alerts & Activity → Alert settings and Settings → General:

Updating

With deploy.sh, run the same command again. Otherwise pull or copy the new code and run docker compose up -d --build. Database changes are applied automatically at start-up. Downgrades aren't supported, so take a configuration backup before big jumps.