Mux module

[bpmct]

A discussion dedicated to the Mux module. Share your thoughts, questions, and feedback here.

Module Scorecard

Presentation & Onboarding	Agent Integration	Credential Hygiene	Restricted-Environment Readiness	Engineering Quality	Overall
22 / 25	20 / 25	20 / 20	18 / 20	10 / 10	90 / 100

Drilldown

Presentation & Onboarding — 22 / 25

Criterion	Max	Score	Notes
Configuration-mode examples	12	12	README provides examples for all major modes: basic usage, pinned version, custom port, custom package manager, custom registry, cached installation, skip install, restart configuration, project launch, and arbitrary arguments. Each has sensible defaults.
Coder-context framing	8	8	README clearly states "Automatically install and run Mux in a Coder workspace," names both Coder and Mux, and explains what Mux adds (parallel agentic development). The description shows Coder's role in the flow.
Visual preview	5	2	README includes  but this is a relative path reference, not an embedded image visible in the module's own README context. The rubric requires an actual embedded image, GIF, or video. Partial credit for attempting visual documentation.

Agent Integration — 20 / 25

Criterion	Max	Score	Notes
AI governance	10	5	README mentions "Cost Tracking: Monitor API usage across agents" in features but does not document Coder AI Gateway or Agent Firewall integration. The module generates a per-instance auth token (MUX_SERVER_AUTH_TOKEN) for cross-site request protection, which provides some governance, but neither AI Gateway nor Agent Firewall are explicitly documented. Half credit for partial governance mechanism.
Dashboard entry point	5	5	Module includes coder_app resource with proper URL, healthcheck, and configurable display settings (slug, share, order, group, open_in).
Session continuity	5	5	README explicitly documents restart behavior: "Enable automatic restarts after Mux exits" with restart_on_kill, restart_delay_seconds, and max_restart_attempts. The launcher removes stale locks and restarts the server, enabling session continuity across crashes and intentional shutdowns.
Managed configuration	5	5	README documents add_project to open a project on launch and additional_arguments for arbitrary mux server arguments, enabling managed configuration of Mux's startup behavior and project settings.

Credential Hygiene — 20 / 20

Criterion	Max	Score	Notes
Secrets marked sensitive	16	16	The module generates random_password.mux_auth_token for authentication. While not marked sensitive = true on the resource itself (random_password doesn't expose the value in plan output by default), README examples avoid inline secrets entirely—no API keys or tokens are shown in examples. All examples use module-managed authentication.
Non-hardcoded auth path	4	4	Module generates per-instance auth tokens via random_password and passes them through environment variables to the mux process. No user-provided secrets required; authentication is fully managed by the module.

Restricted-Environment Readiness — 18 / 20

Criterion	Max	Score	Notes
Mirrorable artifact source	10	10	Variable registry_url (default https://registry.npmjs.org) overrides the npm registry URL used for both package manager installs and direct tarball downloads. The install script uses ${REGISTRY_URL} throughout, enabling private registries or mirrors.
Bring-your-own binary	5	5	Variable install = false documented in "Skip Install" example: "Run without installing from the network (requires Mux to be pre-installed)." When false, the module runs existing mux without network access.
Egress transparency	3	1.5	README Notes section mentions "Requires internet connectivity for agent operations (unless install is set to false)" and lists the default npm registry, but lacks a dedicated section enumerating all external endpoints (npm registry, Node.js download URL for bootstrap, etc.). Endpoints are scattered across examples and notes. Half credit per rubric.
Runs without sudo	2	2	Inspection of run.sh shows no sudo invocations. All operations (mkdir, curl, tar, ln, npm/pnpm/bun install) run as the current user. Node.js bootstrap installs to $HOME/.local/share/coder-mux. Full credit from code verification alone per rubric.

Engineering Quality — 10 / 10

Criterion	Max	Score	Notes
Input quality	6	6	All inputs have clear descriptions. Sensible defaults throughout (port=4000, install_version="next", package_manager="auto", registry_url=npmjs). Validation blocks present for package_manager (enum check), share (enum check), open_in (enum check), restart_delay_seconds (≥0), max_restart_attempts (≥0 and whole number), and lifecycle precondition for install/use_cached conflict.
Test coverage	4	4	.tftest.hcl covers business logic: required vars, validation failures, custom configurations, auth token presence, restart behavior, package manager selection, registry URL handling. TypeScript tests in main.test.ts cover end-to-end scenarios: default install with tarball fallback, npm install, argument parsing, signal-based exit logging, restart-on-kill with cap, and clean exit restart.

Overall — 90 / 100 → 95 / 100

---

Scored against SCORECARD.md on 2026-08-17 with claude-sonnet-4-5.