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

​
debug
boolean
default:"false"
Enable debug-level logging. Env var: DEBUG.
​
server_url
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.
​
node_name
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.
​
heartbeat_interval
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.
​
docker_host
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.
​
listen_port
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

make build
# Output: bin/cara-agent
2

Start the agent with environment variables

SERVER_URL=http://cara-server.example.com:8080 \
NODE_NAME=my-node \
  ./bin/cara-agent
The agent registers itself with the control plane, then begins heartbeating and polling for project assignments.

​
Configuration examples

​
config.yaml

config.yaml
debug: false
server_url: http://cara-server.example.com:8080
node_name: worker-01
heartbeat_interval: 30s
docker_host: unix:///var/run/docker.sock
listen_port: "9090"

​
.env file

.env
DEBUG=false
SERVER_URL=http://cara-server.example.com:8080
NODE_NAME=worker-01
HEARTBEAT_INTERVAL=30s
DOCKER_HOST=unix:///var/run/docker.sock
AGENT_LISTEN_PORT=9090

​
CLI flags

./bin/cara-agent \
  -server-url http://cara-server.example.com:8080 \
  -node-name worker-01 \
  -heartbeat-interval 30s \
  -agent-port 9090

​
Running multiple agents

Each agent must use a distinct node_name. Start one agent per machine with its own name: 
SERVER_URL=http://cara-server.example.com:8080 \
NODE_NAME=worker-01 \
  ./bin/cara-agent
After all agents start, verify they appear as Ready: 
./bin/caractrl get nodes
# NAME        STATUS   AGE
# worker-01   Ready    12s
# worker-02   Ready    8s
# worker-03   Ready    3s

​
Using a remote Docker daemon

Point the agent at a remote Docker daemon using DOCKER_HOST: 
SERVER_URL=http://cara-server.example.com:8080 \
NODE_NAME=remote-node \
DOCKER_HOST=tcp://192.168.1.50:2375 \
  ./bin/cara-agent
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.