cmdcenter

cmdcenter is a lightweight Go orchestrator where a central controller enforces deterministic workflow order and agents only execute commands and report events.

• v1. HTTP POST /poll and /event from agent to controller. Single session only.

Execution model

• Allow only one active session.

• Outbound-only agents.

• Agents use HTTP long-polling transport (POST /poll, held up to 15s).

• Experiment sequences and commands are called steps defined in rules file.

• Run agent with -1 to exit after session becomes terminal.

• Start test session when designated agent sends POST /event with kind=init.

• init is accepted only when all agents declared in agents: are online.

• Rule file must contain exactly one action: init step, first and dependency-free.

• Agent process stays alive after session completion by default.

• On graceful agent shutdown (for example SIGTERM), agent sends kind=agent_exit.

Rule grammar (hard-break)

See rules/demo.yaml.

Supported actions:

• init: required exactly once, first step, single agent, no command/handle.
• start: requires handle and command.program. Non-blocking.
• wait: requires handle and for in any_started|success|failed|stopped|any.
• stop: requires handle.
• exit: optional cleanup command.

Agent events reporting:

• kind=handle_update terminal status reports command completion.
• kind=step_finished reports step completion.
• kind=agent_exit reports agent exit.

Session lifecycle

1. Agents register while controller is idle.
2. Initiator agent sends kind=init event with vars (experiment parameters).
3. Controller creates one active session only if all required agents are online, then schedules steps deterministically.
4. When all steps reach terminal (success or failed), session closes.
5. New experiment requires a new kind=init event.

If any agent calls /register while session is active, controller returns 409 Conflict.

Quick start

Build

go build -o central ./cmd/controller
go build -o agent ./cmd/agent

Build for Android Termux

Most Termux phones are arm64, and the agent builds cleanly with pure Go:

GOOS=android GOARCH=arm64 CGO_ENABLED=0 go build -o agent-android ./cmd/agent

On the Termux device:

chmod +x agent-android
./agent-android -id=server -central=http://<controller-ip>:8443 -run_name=demo -token=server_secret -init

Notes:

• GOARCH=arm64 is the recommended target for modern Android devices.
• GOARCH=arm (32-bit) requires cgo/external linking toolchain and will not build with CGO_ENABLED=0.

Start executable agents

./central -rule=rules/demo.yaml -listen=:8443

./agent -id=server -central=http://127.0.0.1:8443 -run_name=demo -token=server_secret -init -payload="port=5201,run_id=run-001"

./agent -id=client -central=http://127.0.0.1:8443 -run_name=demo -token=client_secret

Start another experiment later by sending another init event (or restart initiator with -init again when controller is idle).

APIs

• POST /register: register agent identity while idle.
• POST /poll: fetch next command (noop when idle/no command).
• POST /event: report init, step_finished, handle_update, agent_exit.
• GET /session: inspect active session, or last terminal session snapshot.

When init is sent before all required agents are online, controller returns 409 with:

{
  "status": "not_ready",
  "message": "required agents offline",
  "missing_agents": ["client"]
}