Servers and the Clank Agent

A server in Clank is any Linux machine you want to deploy containers to. The Clank agent is a Go binary that runs on each server, maintaining a persistent connection back to the control plane. The agent receives deploy commands, manages containers, streams logs, reports metrics, and updates itself — all without opening any inbound ports on your server.

The agent

The Clank agent is a single static Go binary. It runs as a systemd service, starts on boot, and reconnects automatically if the connection drops. There is no runtime dependency beyond Docker.

The agent handles:

• Container deployment: Pulling images, creating containers with the correct resource limits, environment variables, volume mounts, and Traefik labels.
• Health checks: Verifying containers respond on their configured health check path before reporting a deployment as active.
• Log streaming: Forwarding container stdout/stderr back to the control plane in real time.
• Metrics collection: Reporting CPU, memory, disk, and network usage for each container.
• Endpoint management: Configuring Traefik routing rules, TLS certificates, and Cloudflare Tunnels based on the endpoint access mode.
• Self-update: Downloading new agent versions, verifying cryptographic signatures, swapping the binary, and rolling back if the new version fails to start.

How it connects

The agent initiates an outbound gRPC connection to the control plane. Traffic flows from the agent to the control plane, never the other way around. This means your server does not need any open inbound ports, firewall rules, or port forwarding.

Two connection modes are supported:

• Direct (mTLS): The agent connects to the control plane’s gRPC endpoint using mutual TLS. Both sides present certificates. This is the default mode when your control plane has a reachable address (e.g., a public IP or Tailscale).
• Tunnel (Cloudflare): The agent connects through a Cloudflare Tunnel. Authentication uses a JWT token instead of client certificates, because Cloudflare’s gRPC proxy terminates TLS at the edge. This mode works when the control plane is behind a Cloudflare Tunnel with no direct network path.

In both modes, the agent maintains a bidirectional gRPC stream. It sends heartbeats every 30 seconds. If the connection drops, the agent uses exponential backoff to reconnect. Running containers are not affected by connection loss — they keep running independently.

Note

The agent connects outbound. It does not listen on any ports. Your server’s firewall only needs to allow outgoing HTTPS traffic (port 443).

Server profiles

When a server enrolls, Clank asks you to identify its network profile. This determines which endpoint access modes are available:

Profile	Description	Example
Public	Server has a public IP address. Reachable from the internet.	A VPS from Hetzner, DigitalOcean, or AWS EC2.
Local	Server is behind NAT on a private network. Not directly reachable from the internet.	A homelab machine, Proxmox VM, or Raspberry Pi.
Unknown	Not yet classified.	Default until you set it.

Public servers can use PUBLIC_DIRECT endpoints (Let’s Encrypt certs via HTTP-01 challenge). Local servers typically use PUBLIC_TUNNEL_CLOUDFLARE, PRIVATE_TAILSCALE_HTTPS, or LAN_ONLY. See Endpoint Access Modes for details.

Enrollment

Enrollment is the process of registering a new server with the control plane and establishing trust. Here is the sequence:

1. Create the server in the Clank dashboard. Clank generates a one-time enrollment token (displayed in the UI and in the install command) and records the server as pending.

2. Run the install script on your server. The script downloads the agent binary, verifies its checksum, installs it to /opt/clank/bin/, and creates a systemd service.

3. The agent enrolls. Using the one-time token, the agent sends an enrollment request to the control plane along with system information (hostname, OS, architecture, CPU count, memory, Docker version). The control plane validates the token, issues mTLS client certificates (or a JWT for tunnel mode), and returns them.

4. Certificates are stored locally. The agent saves its client certificate, private key, and CA certificate to its config directory (/etc/clank-agent/ or ~/.clank-agent/). A config.yaml file records the server ID, gRPC endpoint, auth mode, and cert directory.

5. The agent starts its main loop. It establishes the gRPC connection, sends its first heartbeat (which includes system information, network IPs, Tailscale status, and agent version), and begins listening for commands.

The enrollment token is single-use. Once consumed, it is invalidated. If enrollment fails, you can generate a new token from the dashboard.

Caution

The enrollment token has an expiration time. If you wait too long between creating the server and running the install script, the token will expire. Generate a new one from the server’s settings page.

System information

After enrollment, the agent’s heartbeat populates the server record with hardware and network details:

• Hardware: hostname, OS, architecture (amd64/arm64), CPU core count, total memory, Docker version.
• Network: LAN IPs (all detected local addresses), public IP (via external lookup), Tailscale IP and hostname (if Tailscale is installed), preferred IP.
• Agent: current agent version, update status.

This information is visible on the server detail page in the dashboard and is used by the control plane to determine available endpoint modes and monitor server health.

The doctor command

The agent includes a built-in diagnostic tool. Run it on the server to verify everything is configured correctly:

clank-agent doctor

It checks:

Check	What it verifies
docker	Docker daemon is installed and responsive.
docker_socket	The Docker socket (/var/run/docker.sock) is accessible.
docker_group	The agent user is in the docker group.
disk_space	Sufficient free disk space is available.
config	The agent config file exists and is readable.
certificates	mTLS certificates are present and not expired.
grpc	The agent can reach the control plane’s gRPC endpoint.
systemd	The clank-agent systemd service is installed and active.
tailscale	Tailscale is installed and connected (warning, not error, if missing).

Each check reports OK, WARN, or FAIL with a suggested fix. Use --json for machine-readable output or --quiet for a silent exit-code-only check (0 = all OK, 1 = errors).

Server states in the dashboard

Status	Meaning
Pending	Server created, enrollment token issued, agent not yet connected.
Online	Agent is connected and sending heartbeats.
Offline	No heartbeat received within the timeout window. Running containers are unaffected — the agent is unreachable, not the containers.

Self-update

The control plane can push agent updates. When a new version is available:

1. The control plane sends an update command with the download URL and expected checksum.
2. The agent downloads the new binary to a temporary location, verifies the checksum, and validates the cryptographic signature against its embedded signing public key.
3. The agent backs up the current binary (stored next to the binary at /opt/clank/bin/), replaces it with the new one, and restarts the systemd service.
4. If the new binary fails to start (crashes within the first few seconds), the agent rolls back to the backup automatically.

Caution

Agents reject unsigned binaries. The signing key is embedded at build time. If you build a custom agent binary without the signing key, it will not be able to auto-update from the control plane’s release artifacts.

Next steps

• Endpoint Access Modes — Configure how traffic reaches your services.
• Projects and Services — Understand the deployment model.