Servers

A server is any Linux machine Docksy can reach over SSH. Docksy provisions it once, then deploys to it and watches it.

Add a server

Servers → Add server. Docksy shows its public SSH key (ed25519, generated on first use) and a one-line command.
Run that one-liner on the new machine. It appends the key to ~/.ssh/authorized_keys:
```
$ mkdir -p ~/.ssh && echo "ssh-ed25519 AAAA… docksy" >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys
```
Most VPS providers also let you paste the key when you create the machine.
Enter a name, the host (IP or DNS), the SSH port (default 22) and the user (default root; a passwordless-sudo user also works).
Validate checks: SSH connects, root/sudo works, the OS, whether Docker is present, and free disk.
Provision streams a live log while it sets the server up.

What provisioning does

Provisioning is idempotent: run it again any time to repair or update a server.

Installs Docker (via get.docker.com) if it's missing.
Creates the docksy Docker network.
Starts docksy-proxy (Caddy with docker-proxy) on ports 80/443, with automatic HTTPS for every app domain.
Creates /var/lib/docksy/{builds,backups,volumes}.
Optionally opens 80/443 in ufw.
Installs the metrics agent (/usr/local/bin/docksy-agent, systemd unit docksy-agent.service, config in /etc/docksy/agent.env).

The agent

The agent is a tiny static Go binary (no CGO, standard library only). Every 10 seconds it reports:

CPU (total and per core), load average, memory, swap, disks (real filesystems only) and network throughput
every container: state, CPU %, memory, network, and restart count

It runs unprivileged except for read access to the Docker socket, and uses under 15 MB of RAM and under 1% CPU. It only pushes to your Docksy URL (/api/agent/v1/report) with its own token. No inbound port is opened. If Docksy is unreachable, it backs off and keeps only the latest report.

A server is online when the agent reported in the last 60 seconds. After 2 minutes of silence the default Server offline alert fires.

The server page

/servers/:id is the showcase page:

live CPU, memory, disk and network gauges and charts
a per-core CPU heatmap and the load average
a containers table with per-container CPU and memory bars
a range picker: 15m, 1h, 6h, 24h, 7d or 30d
an Ask Claude to diagnose button that shows the diagnose report

On-server layout

Thing	Where / name
Network	`docksy`
Proxy	container `docksy-proxy` (ports 80/443)
App containers	`dx-<app>-<deploy8>`, labels `docksy.managed=true`, `docksy.app`, `docksy.deployment`
Builds / backups / volumes	`/var/lib/docksy/…`
Agent	`/usr/local/bin/docksy-agent`, `docksy-agent.service`, `/etc/docksy/agent.env`

Remove a server

Docksy refuses to delete a server that still has apps. Delete or move the apps first. Deleting a server from Docksy doesn't wipe the machine. To remove the agent:

$ sudo systemctl disable --now docksy-agent && sudo rm /usr/local/bin/docksy-agent /etc/systemd/system/docksy-agent.service /etc/docksy/agent.env

Troubleshooting

Symptom	Fix
SSH authentication failed	The key isn't in `authorized_keys` for that user, or the user/port is wrong.
Connection timed out	A firewall or security group is blocking port 22 from the Docksy host.
Agent never comes online	The Public URL in Settings must be reachable from the server. Check `journalctl -u docksy-agent`.
Ports 80/443 in use	Another web server is running. Stop it, or use a fresh machine.

With the Claude plugin, just say "add my new Hetzner box 203.0.113.7 to Docksy". The docksy-setup-server skill walks you through it.

Edit this page on GitHub