husarion/agent repository overview

⁠husarion/agent

Host-control daemon for Husarion⁠ robots — the backend the Cockpit's Manage tab talks to (Caddy → Unix socket). It exposes the robot's configuration as real files (.env + DDS/Zenoh profiles) that propagate git-style across a multi-agent chain, plus panels for node-local observability and actions (Health, Robot Info, Logs, Zenoh-router). Config edits fire a per-concern hook that bridges into whatever the robot actually wants — snap set, docker compose restart, systemctl reload, a custom shell script.

The same daemon serves Panther, Lynx, ROSbot, and any future Husarion robot. Robot-specific behaviour is data, not code: a config-seed (agent.yaml / follow.yaml / config/ / hooks/ / manifests/) plus panels.d/*.yaml, dropped under the agent's config root.

Multi-arch: linux/amd64 + linux/arm64.

⁠Production deploys: prefer the native binary

Production cockpit stacks (e.g. for Lynx, ROSbot XL — see the public release index at https://github.com/husarion/husarion-cockpit-releases⁠) do NOT run this image. They install the daemon natively as a systemd unit via the static binary published on the same release index (https://github.com/husarion/husarion-cockpit-releases/releases⁠). Native install gives the daemon direct access to host tools (snap, docker compose, etc.) without privileged-container gymnastics.

This Docker image is for dev stacks that still keep the agent in compose for iteration speed. The customer-facing per-robot install scripts always pull the native binary, not this image.

⁠Tags

• husarion/agent:X.Y.Z — pinned production tag
• husarion/agent:latest — tracks the most recent release

See the Tags tab above for all available versions; or the public binary index for the same versions as native-install artefacts: https://github.com/husarion/husarion-cockpit-releases/releases?q=husarion-agent/v⁠.

⁠Quick start (in-compose, dev)

services:
  husarion-agent:
    image: husarion/agent:1.5.0
    network_mode: host
    command:
      - --socket=/run/husarion-agent/agent.sock
      - --state-dir=/var/lib/husarion-agent
      - --config-root=/var/lib/husarion-agent
      - --panels-default=/usr/share/husarion-agent/panels.d
      - --panels-overrides=/etc/husarion-agent/panels.d
    volumes:
      - agent-socket:/run/husarion-agent
      - ./husarion-agent-data:/var/lib/husarion-agent
      # robot-specific panel drop-ins (optional; same `name` overrides a shipped panel):
      - ./panels.d:/etc/husarion-agent/panels.d:ro
    restart: unless-stopped

volumes:
  agent-socket: {}

The config-root (--config-root, defaults to --state-dir) holds the files-first config tree: agent.yaml (this node's role — source / relay / leaf — listen, and what it publishes), follow.yaml (which upstream it pulls and which paths), config/<concern>/{shared.env,local.env}, hooks/<concern>, and manifests/<concern>.yaml. Seed it from your robot's bundle on first boot; the agent reconciles it against the chain thereafter.

The webserver service of husarion/webui⁠ mounts the same agent-socket volume read-only and proxies /api/agent/* through Caddy.

⁠The two surfaces

• Config (/api/agent/v1/config/*) — real files grouped into concerns (network, rmw, drive, …). An owner publishes a concern; followers pull only their declared paths and reconcile master-wins-unless-locally-edited. Each concern applies atomically through one hook (hooks/<concern>, with HUSARION_AGENT_<KEY> injected for every *.env key). Apply is observable — every node reports its last_applied up the chain so the WebUI shows propagation live.
• Panels (/api/agent/v1/panels/*) — node-local probes / log streams / actions declared in panels.d/*.yaml. Non-propagating; drives the Health / Robot Info / Logs / Zenoh-router cards.

The pre-bundled per-robot install scripts on https://github.com/husarion/husarion-cockpit-releases⁠ ship the ROSbot + Lynx config-seeds + panels ready to drop into the agent's config root.

⁠About

Built and maintained by Husarion⁠ — robotics research + commercial UGV platforms.

• Static binaries (for native install on a fresh robot): https://github.com/husarion/husarion-cockpit-releases/releases?q=husarion-agent/v⁠
• Per-robot install scripts (compose stack + native agent + config-seed bundles, all pinned together): https://github.com/husarion/husarion-cockpit-releases⁠

License: Apache-2.0.