npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@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 mplexd and runs it as a service.
  • By hand: npm install -g @mplex/runner, then mplexd --help. mplexd check tests the token, agents, git and repository access.
  • Updating: mplexd update reinstalls the latest release from npm where mplexd is 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> (:latest is the newest stable release). It holds mplexd, git, the language toolchains and the agent CLIs. Sample manifests: https://mplex.ai/install/kubernetes-runner.yaml (one pod) and https://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-artifacts

Packed 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.json directories 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.