Installation

HeroCtl runs on any Linux server with Docker. The binary is single and contains the three execution modes: server, agent, and CLI. You decide the machine's role via flag, not via package.

Prerequisites

Before installing, confirm the environment. The list is short and firm.

Note: Docker must be running before install. Check with docker info. If the output shows a socket error, fix permissions before proceeding.

Install command

One command delivers the binary, configures the service, and generates the default configuration file.

curl -sSL https://get.heroctl.com/install.sh | sh

The script runs four steps, in order:

1. Downloads the latest binary to /usr/local/bin/heroctl.
2. Creates the heroctl system user and the /etc/heroctl/ and /var/lib/heroctl/ directories.
3. Registers a systemd service (heroctl.service) without enabling auto-start.
4. Generates /etc/heroctl/server.yaml with safe defaults (bind on 127.0.0.1, no TLS).

No surprises. The script does not touch anything outside those paths and does not start processes.

Post-install verification

After the script finishes, two commands confirm the binary responds.

heroctl version
# heroctl 1.0.0 (commit abc123, build 2026-04-20)

heroctl status
# binary: ok
# config: /etc/heroctl/server.yaml
# docker: connected (24.0.7)
# service: inactive (não iniciado)

If docker: connected shows an error, the binary cannot talk to the socket. Add the heroctl user to the docker group and restart the service.

sudo usermod -aG docker heroctl
sudo systemctl restart heroctl

The three modes of the binary

The same executable changes role via the initial flag. There is no separate package.

In production, 3 nodes run server + agent. Extra workers run agent only. CLI mode is stateless and can run from the operator's laptop.

Initial bootstrap

The first node needs to initialize the cluster state. This step is unique and only happens once in the install's life.

sudo heroctl server --bootstrap --advertise 10.0.0.1

The --advertise flag is the IP that other nodes will use to connect. In a test environment, it can be 127.0.0.1. In production, it is the machine's private IP.

After bootstrap, the service stays running in the background. Confirm with:

heroctl cluster status
# nodes:    1
# leader:   self
# applied:  42
# health:   ok

To bring up additional nodes and form a real cluster, head over to Bring up a 3-node cluster.

Common problems

Port 8080 in use

HeroCtl reserves 8080 for the HTTP API. If another process already occupies it, edit /etc/heroctl/server.yaml before bootstrap.

api:
  bind: 0.0.0.0
  port: 9080

Restart the service with sudo systemctl restart heroctl.

Docker permission denied

The message permission denied while trying to connect to the Docker daemon appears when the heroctl user is not in the docker group. Fix with the usermod shown above and restart the service.

Firewall blocking the cluster

On providers like DigitalOcean or Hetzner, the external firewall blocks 8080–8082 by default. Open the three ports between node IPs before trying to form a cluster. For external API access, keep 8080 open only for administrative IPs.

Binary not found after install

The script installs to /usr/local/bin/. If the current session's PATH does not include that directory, open a new shell or run hash -r.

Uninstall

Reversal is symmetric. Removes service, binary, and data, in that order.

sudo systemctl stop heroctl && sudo systemctl disable heroctl
sudo rm /etc/systemd/system/heroctl.service
sudo rm /usr/local/bin/heroctl
sudo rm -rf /etc/heroctl /var/lib/heroctl
sudo userdel heroctl

Warning: the /var/lib/heroctl/ directory contains the cluster state. Deleting it means losing deploy history and job definitions. Take a snapshot first if there is any chance you will reinstall.

Next step: form a 3-node cluster.