simpleorch/agent repository overview

⁠SimpleOrch Agent

The SimpleOrch node agent — connects your Docker Swarm nodes to the SimpleOrch control plane.

This image runs on every node in your Docker Swarm cluster and acts as the communication layer between your infrastructure and the SimpleOrch control plane. A single image handles both manager and worker node roles, differentiated by a single environment variable.

⁠How It Works

SimpleOrch Control Plane
        │
        │  WebSocket (with polling fallback)
        │
   ┌────┴────┐
   │  Agent  │  NODE_ROLE=manager     ← You install this manually on manager nodes
   │(manager)│  Full Swarm API access
   └────┬────┘
        │  Docker Swarm Global Service (automatic)
        │
   ┌────┴────┐
   │  Agent  │  NODE_ROLE=worker      ← Deployed automatically on all worker nodes
   │ (worker)│  Metrics + execution
   └─────────┘

The manager agent has access to the Docker socket and can issue Swarm commands — deploying services, scaling, restarting containers, and pushing NGINX configuration updates. The worker agent collects node metrics and reports them back through the manager to the control plane.

⁠Quick Start — Manager Node Installation

Do this on each Docker Swarm manager node. Get the registration command from the SimpleOrch control plane dashboard under Clusters → your cluster → Add Manager Node.

⁠Linux

docker run -d \
  --name simpleorch-agent \
  --restart unless-stopped \
  -e CONTROL_PLANE_URL=https://<your-control-plane-ip> \
  -e CLUSTER_ID=<your-cluster-id> \
  -e REGISTRATION_TOKEN=<token-from-dashboard> \
  -e NODE_ROLE=manager \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v simpleorch-agent-data:/data \
  simpleorch/agent:latest

⁠Windows Server (PowerShell)

docker run -d `
  --name simpleorch-agent `
  --restart unless-stopped `
  -e CONTROL_PLANE_URL=https://<your-control-plane-ip> `
  -e CLUSTER_ID=<your-cluster-id> `
  -e REGISTRATION_TOKEN=<token-from-dashboard> `
  -e NODE_ROLE=manager `
  -v //./pipe/docker_engine://./pipe/docker_engine `
  -v simpleorch-agent-data:/data `
  simpleorch/agent:latest

The agent will register with the control plane, appear in your dashboard, and automatically deploy worker agents across all Swarm worker nodes.

⁠Environment Variables

⁠Required

⁠Optional

⁠Volumes

⁠Node Roles

⁠Manager Role (NODE_ROLE=manager)

• Establishes and maintains the WebSocket connection to the control plane
• Mounts the Docker socket for full Swarm API access
• Executes deployment, scale, stop, and restart instructions from the control plane
• Pushes NGINX ingress configuration updates
• Reports its own metrics and coordinates worker node metric collection
• Does not count toward your SimpleOrch license node limit

⁠Worker Role (NODE_ROLE=worker)

• Deployed automatically as a Docker Swarm global service — one instance per worker node
• Reports node-level metrics (CPU, memory, disk, running containers) every 30 seconds
• Receives and executes container-level instructions
• Counts toward your SimpleOrch license node limit

⁠Combined Manager + Worker

A node running both roles (common in smaller clusters where Swarm managers also run workloads) requires two agent containers — one with NODE_ROLE=manager and one with NODE_ROLE=worker. The control plane detects both are on the same host and counts it as one licensed node, not two.

⁠Communication

The agent communicates with the control plane over HTTPS. Only outbound connections are made from the agent to the control plane — no inbound ports need to be opened on your Swarm nodes.

Connection behavior:

1. On startup the agent attempts a WebSocket connection to the control plane
2. If the WebSocket connection drops, the agent automatically falls back to REST polling (heartbeat every 30 seconds)
3. Reconnection uses exponential backoff: 5s → 15s → 30s → 60s (cap), retrying indefinitely
4. When the control plane becomes reachable again the agent upgrades back to WebSocket automatically

⁠Platform Support

Mixed Windows and Linux nodes in the same Swarm cluster are fully supported.

⁠Upgrading

Worker node agents are upgraded automatically by the SimpleOrch control plane when a new version is available — the global Swarm service is updated and Docker Swarm rolls out the new image across all worker nodes without manual intervention.

Manager node agents must be updated manually:

docker pull simpleorch/agent:latest
docker stop simpleorch-agent
docker rm simpleorch-agent
# Re-run the original docker run command with the new image

The node UUID persists in the simpleorch-agent-data volume so the node re-registers automatically using its existing identity — no new registration token needed.

⁠Troubleshooting

Agent is not appearing in the dashboard after running the join command:

• Verify CONTROL_PLANE_URL is reachable from the node: curl -k https://<control-plane-ip>
• Check that the registration token has not expired (tokens are valid for 60 minutes)
• View agent logs: docker logs simpleorch-agent

Node shows as Disconnected in the dashboard:

• Check network connectivity between the node and the control plane
• View agent logs for WebSocket or polling errors: docker logs simpleorch-agent --tail 50
• The agent will reconnect automatically — Disconnected status resolves once the connection is restored

Worker agents not appearing after manager registration:

• Confirm the manager node has Docker socket access: the -v /var/run/docker.sock:/var/run/docker.sock mount must be present
• On Windows, confirm the named pipe mount is correct: -v //./pipe/docker_engine://./pipe/docker_engine
• Check the Swarm service was created: docker service ls | grep simpleorch

⁠Security

• The registration token is single-use and expires after 60 minutes
• After registration, all communication uses a node-specific certificate signed by the control plane CA
• The Docker socket is mounted read-write on manager nodes — restrict access to the simpleorch-agent container using Docker's standard security mechanisms appropriate for your environment
• No inbound network ports are required on Swarm nodes

⁠Source & Support

• Website: simpleorch.io⁠
• Documentation: simpleorch.io/docs⁠
• Support: [email protected]⁠
• Community: simpleorch.io/community⁠

SimpleOrch is a product of MW Consulting.