Install the Agent on Linux

This guide walks you through installing the Clank agent on a Linux server. Once installed, the agent connects outbound to the Clank control plane over gRPC, allowing you to deploy containers to the server from the dashboard or CLI.

Prerequisites

Before you begin, make sure your server meets these requirements:

• Linux — Any modern distribution (Ubuntu 20.04+, Debian 11+, RHEL 8+, etc.)
• Docker Engine 24+ — The agent manages containers through the Docker API. Install Docker from docs.docker.com if you haven’t already.
• Root or sudo access — The installer creates a system user, installs a systemd service, and configures Docker group membership.
• Outbound network access — The agent connects outward on HTTPS (443) and gRPC (configurable port). No inbound ports need to be opened.

Step 1: Get the install command

You can register a new server from the web dashboard or the CLI. Both produce a one-liner install command with an enrollment token baked in.

From the web dashboard:

1. Go to Servers in the sidebar.
2. Click Add Server.
3. Enter a name for the server.
4. Copy the install command that appears.

From the CLI:

clank servers add my-server

The CLI prints the install command to your terminal.

Either method produces a command like this:

curl -fsSL https://your-instance/install.sh | CLANK_ENROLL_TOKEN=<token> CLANK_ENROLL_SERVER=<host:port> sh

Step 2: Run the installer

SSH into your target server and paste the install command:

curl -fsSL https://your-instance/install.sh | CLANK_ENROLL_TOKEN=<token> CLANK_ENROLL_SERVER=<host:port> sh

The installer performs the following:

1. Creates a clank system user and adds it to the docker group.
2. Downloads the agent binary for your platform and architecture.
3. Enrolls with the control plane using the token, receiving mTLS certificates.
4. Installs and starts a systemd service (clank-agent.service).

The enrollment token is single-use and expires after 1 hour.

Step 3: Verify the installation

Run the status command to confirm the agent is running and connected:

clank-agent status

You should see the agent reporting as connected with a valid server ID.

For a deeper health check, run the built-in diagnostic tool:

clank-agent doctor

The doctor command runs the following checks:

Check	What it verifies
Docker connectivity	Agent can reach the Docker daemon
Docker version	Docker Engine meets the minimum version (24+)
gRPC connection	Agent can reach the control plane
mTLS certificates	Certificates are valid and not expired
Disk space	Sufficient free disk for image pulls and builds
DNS resolution	Server can resolve external hostnames

All checks should show a passing status. If any fail, the output includes a description of the problem and a suggested fix.

Upgrading the agent

The agent supports automatic self-updates triggered from the control plane. You can also upgrade manually by re-running the install script on the server. The installer detects the existing installation and performs an in-place upgrade, preserving configuration and certificates.

Tip

You can check the running agent version at any time with clank-agent status. The dashboard also shows each server’s agent version on the Servers page.

Uninstalling

To remove the agent from a server:

sudo systemctl stop clank-agent
sudo systemctl disable clank-agent
sudo rm /etc/systemd/system/clank-agent.service
sudo rm -rf /opt/clank
sudo userdel clank
sudo systemctl daemon-reload

This stops the service, removes the binary and configuration, and deletes the system user. Containers already deployed on the server are not affected — they continue running but will no longer be managed by Clank.

Next steps

• Set Up a Custom Domain — point your own domain at a deployed service
• Manage Environment Variables — configure secrets and env vars for your services