Installation

dockmesh runs as a single binary on any Linux host with Docker installed. No external dependencies required.

Platform support

Component	Linux	macOS	Windows
Server (dockmesh)	amd64 / arm64	amd64 / arm64	roadmap
Agent (dockmesh-agent)	amd64 / arm64	amd64 / arm64	roadmap
CLI (dmctl)	amd64 / arm64	amd64 / arm64	via WSL or go install

All four release tarballs (dockmesh_linux_amd64, dockmesh_linux_arm64, dockmesh_darwin_amd64, dockmesh_darwin_arm64) bundle the server, agent, and dmctl together — one download covers every binary you need. The one-line installer detects the host OS and wires up the right service manager — systemd on Linux, launchd on macOS. Data directory follows platform convention: /var/lib/dockmesh on Linux, /usr/local/var/dockmesh on macOS (Homebrew-style).

Docker connectivity uses the standard platform socket — /var/run/docker.sock on Linux, Docker Desktop’s socket on macOS. No config needed if Docker/Docker Desktop is already running.

Native Windows server and agent support is on the roadmap. There is no prebuilt Windows binary for dmctl today either — Windows operators either run it under WSL, or build from source with go install github.com/dockmesh/dockmesh/cmd/dmctl@latest.

macOS-specific notes

• Enable the default Docker socket. Recent Docker Desktop releases don’t expose /var/run/docker.sock out of the box — it lives in ~/.docker/run/docker.sock until you enable it. Open Docker Desktop → Settings → Advanced → “Allow the default Docker socket to be used” before running dockmesh init. Without it, the server can’t connect to the daemon and the service will crash-loop on first start.
• First launch will trigger a firewall prompt. dockmesh binds to 0.0.0.0:8080 by default, so macOS’ Application Firewall will ask once whether to allow incoming connections. Click Allow — LAN access to the UI depends on it.
• Gatekeeper quarantine (manual downloads only). The one-line installer (curl | sudo bash) is not affected. But if you download a release tarball via Safari/Chrome and install manually, Gatekeeper may block the binary with “cannot verify developer.” Clear it once with sudo xattr -d com.apple.quarantine /usr/local/bin/dockmesh. Proper Developer-ID signing + notarization is on the v0.1.x roadmap.
• Agent enrollment from a macOS server targets Linux hosts. The one-line enroll installer is Linux-only (systemd, useradd, /var/lib/dockmesh). Enrolling a macOS host as an agent is not yet supported via the one-liner — build dockmesh-agent from source and drive it manually if you need Mac-to-Mac today.

Requirements

Everything below the line is what the installer checks (and either auto-handles or tells you exactly how to fix).

Must already be on the host

• Docker Engine (Linux) or Docker Desktop (macOS), with the daemon running
  • Debian/Ubuntu: sudo apt install -y docker.io
  • Fedora/RHEL: sudo dnf install -y docker-ce && sudo systemctl enable --now docker
  • Alpine: sudo apk add docker && sudo service docker start
  • Arch: sudo pacman -S --noconfirm docker && sudo systemctl enable --now docker
  • macOS: Docker Desktop or brew install --cask docker
• curl — to pipe the installer
• tar, sha256sum (from coreutils) — on virtually every default Linux install; on very minimal Debian: sudo apt install -y coreutils
• sudo access on the host (the installer writes to /usr/local/bin, /etc/systemd/system, and creates a dockmesh system user)
• Ports 8080 (HTTP UI + API) and 8443 (agent mTLS listener) free, or reassigned during dockmesh init

Installer checks and auto-handles

• OS + CPU architecture detection (Linux amd64/arm64, macOS amd64/arm64)
• Distribution-aware install hints (apt/dnf/apk/pacman/zypper/brew) for anything missing
• Creates the dockmesh service user, adds it to the docker group
• Drops the binary + agent assets under /usr/local/bin/dockmesh + /usr/local/share/dockmesh/
• Writes a hardened systemd unit (launchd plist on macOS), enables + starts it
• Rewrites existing installs if you upgrade from v0.1.3 or earlier (root → non-root service account migration)

What it does NOT touch

• Docker itself — we point at the right command for your distro but don’t auto-install. Docker is a 300MB install with strong platform-specific preferences (Docker CE vs Docker Desktop vs Colima vs Podman); installing it silently on the operator’s behalf would be hostile.
• Firewall — if you want 8080 exposed externally, open it yourself. We listen on 0.0.0.0 by default so LAN access works out of the box.
• TLS for the UI — the default HTTP listener is plaintext. Run behind Caddy (built-in) or your own reverse proxy for HTTPS.
• Your existing containers — dockmesh doesn’t touch anything running on the host until you explicitly tell it to.

Network

Port	Purpose	Direction	Required?
8080	HTTP UI + REST API	inbound on server	yes (configurable)
8443	Agent mTLS listener	inbound on server	only when enrolling remote agents

Remote agents need outbound 443 / agent-port to the server. Servers never open inbound connections to agents — everything runs through the agent’s outbound WebSocket.

Quick install (recommended)

curl -fsSL https://get.dockmesh.dev | sudo bash

This one-liner:

1. Detects OS + architecture (Linux/macOS, amd64/arm64)
2. Downloads the latest signed release tarball and verifies its SHA-256 against checksums.txt
3. Drops binaries into /usr/local/bin/ — dockmesh, dockmesh-agent, dmctl
4. Creates a non-root dockmesh service user and adds it to the docker group
5. Lays out the data directory (/var/lib/dockmesh on Linux, /usr/local/var/dockmesh on macOS) with the right ownership + permissions
6. Writes a hardened systemd unit (launchd plist on macOS), enables and starts it
7. Generates dockmesh.env with DOCKMESH_SETUP_FORCE=true so the Setup Wizard takes over on first boot

After the installer finishes

Open http://your-server:8080 in a browser. Because the installer flagged the server into setup mode, you land on the Setup Wizard instead of the login page. The wizard collects four things:

• Data directory — where DB, stacks, and keys live (pre-filled with the platform default)
• Service user — the OS user the server runs as: either reuse an existing one or have the wizard create one and add it to the docker group
• Admin user — username, password, optional email
• Public URL — the address the dashboard is reachable on (used for OIDC callbacks + agent enrolment links)

On submit the wizard creates the admin user, writes the chosen public URL into the settings table, scrubs DOCKMESH_SETUP_FORCE from the env file, and drops you on the dashboard. From this point everything else — proxy, scanner, backups, alerts, SSO — lives in the UI.

Manual install

1. Download and extract the release tarball

Releases are published as tar.gz archives that bundle dockmesh, dockmesh-agent, and dmctl. Pick the file that matches your OS + architecture:

# AMD64 (most servers)
curl -fsSL https://github.com/dockmesh/dockmesh/releases/latest/download/dockmesh_linux_amd64.tar.gz \
  | sudo tar -xz -C /usr/local/bin dockmesh dockmesh-agent dmctl

# ARM64 (Raspberry Pi, Ampere, Apple Silicon Linux VMs)
curl -fsSL https://github.com/dockmesh/dockmesh/releases/latest/download/dockmesh_linux_arm64.tar.gz \
  | sudo tar -xz -C /usr/local/bin dockmesh dockmesh-agent dmctl

Verify the checksum against checksums.txt from the same release if you skip the one-line installer (which does this automatically).

2. Create a systemd service

/etc/systemd/system/dockmesh.service

[Unit]
Description=dockmesh Container Management
After=network-online.target docker.service
Requires=docker.service

[Service]
Type=simple
User=dockmesh
Group=docker
EnvironmentFile=/var/lib/dockmesh/dockmesh.env
ExecStart=/usr/local/bin/dockmesh serve
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

This matches the unit dockmesh init lays down on the one-line installer. The server reads its configuration from /var/lib/dockmesh/dockmesh.env; generate that file by running dockmesh init once or populate it by hand (see Environment Variables Reference).

3. Start

useradd --system --home /var/lib/dockmesh --shell /usr/sbin/nologin dockmesh
usermod -aG docker dockmesh
mkdir -p /var/lib/dockmesh/data /var/lib/dockmesh/stacks
chown -R dockmesh:docker /var/lib/dockmesh
chmod 750 /var/lib/dockmesh
dockmesh init --data-dir /var/lib/dockmesh   # writes dockmesh.env + initial paths
systemctl daemon-reload
systemctl enable --now dockmesh

4. Open the UI

Navigate to http://your-server:8080. The admin user is created on first boot — check the service logs for the initial password:

journalctl -u dockmesh | grep "bootstrap"

Docker install

A Dockerfile ships in the repository and you can build the image locally, but there is no official ghcr.io/dockmesh/dockmesh image published yet — the release pipeline only builds tarballs. Operators who want a container-based install today should build the image themselves:

git clone https://github.com/dockmesh/dockmesh.git
cd dockmesh
docker build -t dockmesh:local .

docker run -d \
  --name dockmesh \
  -p 8080:8080 -p 8443:8443 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v dockmesh-data:/var/lib/dockmesh \
  dockmesh:local

Publishing a signed image to ghcr.io is on the roadmap.

Resource footprint

• Disk: ~50 MB for the binary + data (the SQLite DB stays well under 50 MB for typical homelab fleets)
• Memory: ~30 MB at idle, scales with the container count being polled
• Network: 8080/tcp for the UI + API, 8443/tcp only when enrolling remote agents

What’s next?

• Quick Start — deploy your first stack
• Configuration — environment variables and settings
• Multi-Host — add remote Docker hosts
• Uninstall — clean removal (interactive wizard or --purge)