Docs / dflux Runner
ContactGet started

Agent mode

Agent mode attaches dflux Runner to the control plane as a stateless worker. The agent dials out, registers, executes jobs in memory, streams the report back, and holds nothing between jobs. Use this for a continuous test plane; use run-flow / run-suite for CI one-shots.

Stateless by design
The runner binary does not open a listen port for the admin API, does not embed a web UI, and does not keep a local catalog database. Durable state lives in the control plane. For CI, prefer run-flow / run-suite — no control plane required.

Starting the agent

Bash

The agent dials the control plane's ControlPlane endpoint, registers (id defaults to the hostname), and waits for jobs. It has no listen address — it dials out, which is NAT-friendly.

Flags

FlagDefaultPurpose
-console <host:port>requiredControl plane address
-token <t>—Join token presented at Register
-id <id>hostnameRunner agent id
-labels k=v,...—Scheduler labels (e.g. region=eu,env=lab)
-allow-cmd-actionsoffDANGEROUS. Lets console-dispatched flows run type: cmd, executing local programs on this host. Off by default; only set it for a console you fully trust.
-debug, -trace, -json, -logfile, -log-caller—Logging knobs

How jobs run

  1. The control plane owns the catalog, schedules, subscribers, and report history.
  2. When a run is due, it dispatches a job to a free agent that matches labels.
  3. The agent materializes the flow/suite, environment, and subscriber set in memory (subscribers are inline on the job, capped per job).
  4. The same engine as the CLI executes the job, streams events, and returns the report.
  5. The agent holds nothing after the job completes — ready for the next dispatch.

One job at a time per runner agent; scale out with more agents. See Architecture for the full model.

When to use which

GoalUse
Gate a PR / CI pipelined3x-run run-flow / run-suite with exit code + JSON/JUnit
Continuous lab test planed3x-run daemon -console … + control plane
Probe transports before a rund3x-run check -c lab.yaml
Terminate GTP-U for user-plane testsd3x-run server uspace (or dpdk)

Troubleshooting

Agent never receives jobs — confirm the console address is reachable from the agent host, the join token is valid, and labels match what the scheduler expects.

Job fails immediately on transport — the environment on the job must still reach the NFs under test from the agent host. Use d3x-run check from that host with an equivalent config to probe connectivity.

Need a local report without the control plane — use CLI one-shot with -output json -output-file report.json.

Where to go next