Skip to main content
cara-agent runs on every node in your cluster. It registers the node with cara-server, sends periodic heartbeats to signal liveness, polls for assigned projects, and reconciles the desired container state against the local Docker daemon. Each agent manages one node. Like cara-server, the agent merges configuration from four sources in order: config.yaml → .env → environment variables → CLI flags. Later sources override earlier ones.

​
Configuration reference

​
boolean
default:"false"
Enable debug-level logging. Env var: DEBUG.
​
string
default:"http://localhost:8080"
HTTP address of cara-server. The agent dials this URL to register, send heartbeats, and fetch project assignments. Env var: SERVER_URL.
​
string
Name the agent registers under in the control plane. Must be unique across the cluster. Env var: NODE_NAME.
When node_name is not set, the agent uses the machine’s OS hostname returned by os.Hostname(). Set it explicitly when multiple agents share the same hostname (for example, inside containers or VMs with default names), or when you want a stable, human-readable name independent of the hostname.
​
duration
default:"30s"
How often the agent sends a heartbeat to cara-server. Accepts Go duration strings: 30s, 1m, 2m30s. Env var: HEARTBEAT_INTERVAL.
If cara-server does not receive a heartbeat within the expected interval, it marks the node as NotReady. The scheduler will not assign new projects to a NotReady node. Keep this value well below any network timeout between agent and server.
​
string
default:"unix:///var/run/docker.sock"
Endpoint of the Docker daemon the agent manages. Env var: DOCKER_HOST.
Use a tcp:// URL to connect to a remote Docker daemon — for example, tcp://192.168.1.50:2375. Ensure the daemon is secured with TLS when exposed over a network.
​
string
default:"9090"
TCP port for the agent’s own HTTP server, which exposes the port-forward WebSocket endpoint and a health probe. Env var: AGENT_LISTEN_PORT.

​
Starting the agent

1

Build the binary

2

Start the agent with environment variables

The agent registers itself with the control plane, then begins heartbeating and polling for project assignments.

​
Configuration examples

​
config.yaml

config.yaml

​
.env file

.env

​
CLI flags

​
Running multiple agents

Each agent must use a distinct node_name. Start one agent per machine with its own name:
After all agents start, verify they appear as Ready:

​
Using a remote Docker daemon

Point the agent at a remote Docker daemon using DOCKER_HOST:
A Docker daemon exposed over TCP without TLS allows unauthenticated access to the host. Always secure remote Docker endpoints with mutual TLS in production environments.