@mplex/runner
v0.4.0
Published
mplexd: the runner daemon (worktrees, job execution, agent adapters, log/event streaming).
Readme
mplex runner and adapters
mplexd runs mplex's agent sessions on your own machines: a laptop, a VM or a Kubernetes cluster.
- One command: in the mplex web app, add a runner from the Runners section of the Jobs page (or while setting up
a repository). The walkthrough creates a runner token and gives one command that installs
mplexdand runs it as a service. - By hand:
npm install -g @mplex/runner, thenmplexd --help.mplexd checktests the token, agents, git and repository access. - Updating:
mplexd updatereinstalls the latest release from npm wheremplexdis installed and restarts its runner services (--version <x.y.z>picks a release). mplexd logs a notice when the server runs a newer release. - Containers and Kubernetes: the runner image is
ghcr.io/mplex-ai/mplex-runner:<version>(:latestis the newest stable release). It holdsmplexd, git, the language toolchains and the agent CLIs. Sample manifests:https://mplex.ai/install/kubernetes-runner.yaml(one pod) andhttps://mplex.ai/install/kubernetes-launcher.yaml(one pod per session).
Agents run with your own Claude Code or Codex login or API key, which stays on the runner.
Building from source
Requires Node >=22.12. Git is required by runner worktrees. The source checkout uses pnpm 9.10.0 and package-local TypeScript/Vitest configs. No control-plane package is required to build or test this package. Connecting to a control-plane service uses its separately licensed API, not its source code.
From an open-only workspace containing core, ledger, mcp and runner:
pnpm install --offline
# Build dependencies first: core, then ledger and mcp, then runner.
cd packages/runner
pnpm build
pnpm typecheck
pnpm test
pnpm pack --pack-destination /tmp/mplex-artifactsPacked artifacts expose the public package root as ESM JS and declarations;
checkout imports retain TypeScript source resolution. Package-local production
builds use the mplex-production export condition. Released versions are on npm
under @mplex/*, all five packages at one version (MPLEX_VERSION in @mplex/core).
Original package code, documentation and local fixtures are licensed under Apache-2.0. The canonical LICENSE and Apache-2.0 package metadata are included in each archive under DEC-01M4AEH45WXNXDWTTYHQE7TG20. Third-party components retain their own terms; user-authored records and data do not inherit a software license. npm publication is authorized by DEC-01M7NCE2CQZ3BVTS41YDSWQER4.
import { getAdapter, registerAdapter, listAdapters } from "@mplex/runner";
const fake = getAdapter("fake");
registerAdapter("my-fake", () => fake); // real plugins implement AgentAdapter
console.log(listAdapters());mplexd --help lists daemon commands. mplexd service install <mplexd start flags>
runs the runner as a LaunchAgent (macOS) or systemd user service (Linux), one per runner
name (ai.mplex.mplexd.<name>, mplexd@<name>.service), with the token in a 0600
~/.mplex/runners/<name>/mplexd.env and the data dir ~/.mplex/runners/<name>;
mplexd service list shows the runners on the machine, and
mplexd service uninstall|status|start|stop [--name <name>] manage one. mplex's runner setup screen generates a one-line command that installs
this package from npm into ~/.mplex/npm (at the release the server runs) and runs service install. Built-ins are claude-code, codex,
generic and fake. Install the
Claude Code/Codex executables and credentials separately when using those
adapters; generic needs its configured executable/template. Browser demo capture
needs a separately installed compatible browser for playwright-core. Container
isolation requires Docker and a configured image. Fake tests call no real LLM.
The runner negotiates core's RUNNER_PROTOCOL_VERSION on hello/welcome. Use a control plane implementing the corresponding core REST/ws contract. The default agent MCP child resolves the installed @mplex/mcp binary, not a sibling checkout.
Inline build verification
The runner advertises inline_verify: true by default. Builds with
context.inline_verify: { max_fix_attempts } run applicable context.verify_commands
after committing agent changes and dropping generated ledger files. Failed commands
are sent as bounded, fenced data to the same adapter session; its resume token is
reused for at most max_fix_attempts fixes. Adapters without a token start with the
failure instructions instead. The runner commits each fix, verifies again, and
pushes once at the end. Only the final head gets verification evidence and
BuildResult.self_verify; attempt summaries record intermediate heads without
posting evidence for them.
budget.per_session_minutes and budget.per_session_usd cover the agent and its
fixes. Inline verification command time is runner work, so it does not count toward
the session time budget. The usage the runner reports still includes it. budget.per_session_verify_minutes caps cumulative inline
command time instead, including retries and baseline checks; without it, the cap is
the session minutes. Hitting that cap pushes the build and omits self_verify.
The server can then schedule standalone verification of the commands the
runner's evidence does not already cover on that head.
Configure this cap in the runner config or with
--budget-session-verify-minutes <min>.
A command runs only if its predicted window fits the remaining verification budget. Predictions use the receipts of earlier runs:
- An exact-identity sample gives a tight window.
- Otherwise the p90 (+25%) of the 20 most recent completed runs with the same
command and project set decides admission. The project set is the nearest
package.jsondirectories of the changed paths. The run keeps the full bounded window. - With no sample, the command's configured ceiling must fit.
Set inline_verify: false in the runner config or use --no-inline-verify to opt
out. Builds without
the inline policy retain their existing behavior. Standalone
verify jobs, including stale-head re-verification, are unchanged.
The persisted self_verify phase re-runs verification after a restart. Fix counts,
last failures, attempt summaries and accumulated command time survive restarts;
a restart during a fix resumes the agent phase. Pausing or interrupting a command
stops it and re-runs it on resume. Cancellation uses the existing session termination behavior. Exhausting the whole
session budget during an inline build or fix commits and pushes the available work
and omits self_verify, as required by D-206. It starts no further agents or commands.
Verification concurrency
Ordinary automatic and agent-launched correctness checks run without a runner-wide permit or quiet-window wait. Keep the existing test selection, coverage flags and configured session limits. The runner owns final configured inline verification and resumes the same agent for fixes; evidence and current-head CI/review gates remain required. Other active test processes alone are not a blocker or passing evidence.
Local build agents and runner verification receive MPLEX_TEST_MAX_WORKERS after
static agent/adapter environment settings. For N active local build/command sessions
(at least one), the cap is max(1, min(floor(cpu_limit / max(N, ceil(max_sessions / 2))),
floor(memory_available_bytes / N / 1 GiB))). CPU sizing reserves capacity for later
launches using at least half the configured session capacity (rounded up). Memory
uses actual contention and at least 1 GiB per worker, except when the mandatory
minimum one exceeds available headroom. CPU quota is
capped by host parallelism. Unlimited cgroup memory uses host free memory; finite
limits use the smaller of host free memory and unused cgroup memory. An absent
cpu.max/memory.max (a plain host or root cgroup, as on the runner VMs) falls back to
host CPUs and free memory. Malformed probes select one worker, as does zero available memory.
The runner recomputes before agent starts/resumes/fixes and verification commands.
Equal observations yield equal allocations; existing child environments retain their
launch snapshot when contention changes. Held, terminal and inactive/restored sessions
do not count. This is sizing, not a reservation: on 16 CPUs
with max_sessions=4, two early runs can each retain 8 workers, then a third
launch gets 5 (21 total). The formula alone does not guarantee an aggregate bound;
simultaneous live worker totals must be observed after deployment on gce-3/gce-4.
test:affected honors the variable; arbitrary
shell commands must honor it themselves. Runner config should omit a static cap:
agent_env:
NODE_ENV: development
# MPLEX_TEST_MAX_WORKERS is supplied dynamically by the runner.