@cooplux/plux

The CoopLux Agent Interface — orchestration and routing for the DCoop constellation.

Plux scaffolds agent projects, checks constellation service health, routes tasks through MANGOS and a BigBrain-style broker, estimates costs through LiteLLM, and mines reusable control-plane patterns from a codebase.

Install and use

npx @cooplux/plux init my-agent
# or
npm install --global @cooplux/plux
plux --help

Node.js 20 or newer is required. init --hybrid also requires Python 3 and installs its example substrate from public PyPI into an isolated .plux-env virtual environment.

Commands

• plux init [dir] creates an agent project. The ordinary scaffold requires no service configuration or network access. --hybrid additionally creates the Python environment.
• plux doctor reports the resolved Broker, MANGOS, and LiteLLM URL and source, prints only SHA-256 credential fingerprints (first 10 hexadecimal characters), and probes each service independently.
• plux status reports package and broker status and checks broker authentication when both credentials are configured.
• plux route TASK classifies through MANGOS, then submits once to the broker when both broker credentials are present. With incomplete credentials it creates a clearly labelled simulation. Use --no-mangos to skip all MANGOS configuration and network work, --poll to poll an accepted task, and --out DIR to select the artifact directory. The default is ./.plux.
• plux route TASK --dry-run prints a sanitized POST preview and performs no network requests or file writes.
• plux mine [targets...] [--out DIR] [--json] [--cross-analysis] scans explicit targets, PLUX_MINER_TARGETS, or the nearest ancestor containing .git (including worktree .git files). Outside a Git repository it scans the current directory. Dependency, build, report, and Git metadata directories are pruned.
• plux estimate PROJECT [--traffic-data PATH] [--past-bills PATH] creates a Markdown cost report through the configured LiteLLM endpoint.

Successful and simulated routes write both plux-receipt.json and plux-warchest-sample.json under the selected output directory. A failed HTTP response creates no artifacts. An interrupted or ambiguous broker submission tells you that it may have been accepted and must not be retried blindly.

Configuration

Every value is resolved lazily and independently when a command needs it. Precedence is:

1. command-line flag;
2. environment variable;
3. .pluxrc.json in the current working directory;
4. ~/.config/plux/config.json.

All configured values must be non-empty strings. Missing files are ignored. Malformed JSON, non-object config files, and non-string values produce a source-specific error without exposing file contents. Endpoint URLs allow HTTP or HTTPS and reject user information, query strings, and fragments. There are no endpoint defaults.

| Config key | Environment variable | Global CLI flag | Used by | | --- | --- | --- | --- | | brokerUrl | BROKER_URL | --broker-url URL | route, status, doctor | | mangosUrl | MANGOS_URL | --mangos-url URL | route, doctor | | litellmUrl | LITELLM_URL | --litellm-url URL | estimate, doctor | | brokerApiKey | BROKER_API_KEY | --broker-api-key KEY | broker X-API-Key | | internalApiToken | INTERNAL_API_TOKEN | --internal-api-token TOKEN | broker/MANGOS bearer auth | | litellmMasterKey | LITELLM_MASTER_KEY | --litellm-master-key KEY | LiteLLM bearer auth |

Global flags may appear before or after the command. Credential flags have the highest precedence, but environment variables are preferable for interactive use because command arguments can be visible to other local processes.

Example project configuration:

{
  "brokerUrl": "http://127.0.0.1:3111",
  "mangosUrl": "http://127.0.0.1:3151",
  "litellmUrl": "http://127.0.0.1:4002"
}

These are example local bindings rather than defaults. Credentials are optional: route uses simulation until both broker credentials are present, and health checks still work without them.

Health checks

Doctor sends timeout-bounded GET requests without following redirects:

| Service | Health path | | --- | --- | | Broker | /api/health | | MANGOS | /health | | LiteLLM | /health/liveliness |

Only a 2xx response is healthy. Each service is reported even if another service is missing or unreachable, and response bodies and credential values are never printed.

License

MIT © Dane Anthony Cooper