miabi/agent repository overview

⁠Miabi Agent

The node-side runtime for Miabi multi-node. It runs on each worker node, dials the Miabi control plane over an outbound WebSocket, and exposes the node's local Docker engine through a multiplexed tunnel.

All orchestration logic lives on the control plane — the agent is a thin, dumb Docker proxy. It needs no database or Redis access, only:

• outbound HTTPS/WSS to the control plane (NAT/firewall friendly), and
• the local Docker socket.

⁠How it works

control plane (Miabi)  ──WS+yamux──►  agent  ──►  /var/run/docker.sock
        (opens a stream per Docker request)        (pipes each stream to Docker)

The control plane drives the node's Docker via the standard Docker API over the tunnel; the agent just copies bytes between each tunnel stream and the socket.

⁠Configuration (environment)

The control plane reconnect is automatic with exponential backoff.

⁠Run

⁠Install script

Checks that Docker is present and running (it does not install Docker), then starts the agent and verifies it stayed up:

curl -fsSL https://get.miabi.io/agent | \
  MIABI_CONTROL_URL=https://miabi.example.com MIABI_NODE_TOKEN=mbn_xxxxxxxx bash

⁠Docker

docker run -d --name miabi-agent --restart unless-stopped \
  -e MIABI_CONTROL_URL=https://miabi.example.com \
  -e MIABI_NODE_TOKEN=mbn_xxxxxxxx \
  -v /var/run/docker.sock:/var/run/docker.sock \
  miabi/agent:latest

⁠Binary

Via environment, or the equivalent flags (--control-url, --token, --insecure) — each flag defaults to its env var and wins when both are set:

MIABI_CONTROL_URL=https://miabi.example.com \
MIABI_NODE_TOKEN=mbn_xxxxxxxx \
./miabi-agent

# or
./miabi-agent --control-url https://miabi.example.com --token mbn_xxxxxxxx

⁠Build

go build -ldflags "-X main.version=$(git describe --tags --always)" -o miabi-agent .
# or
docker build --build-arg VERSION=$(git describe --tags --always) -t ghcr.io/miabi-io/agent .

⁠Security

The agent grants the control plane access to the node's Docker socket — treat the node as fully managed by the control plane. The join token authenticates the tunnel and is stored hashed on the control plane; rotate it from the node's page if leaked.

⁠License

AGPL-3.0-or-later — see LICENSE⁠. A commercial license is available for uses that don't fit the AGPL; see the Miabi⁠ project's licensing.