CLI, SDK, and configuration reference¶
Muxlio lets you build multi-step workflows across AI agents — Antigravity, Claude, Codex, Cursor, Kiro — and command tools, then run them durably on a coordinator that survives client disconnects. Submit a plan tonight and check the results in the morning.
Workflows are defined in TypeScript, compiled to a canonical Plan IR JSON document, and interpreted by a Go coordinator. No JavaScript reaches the runtime: the IR is the contract between authoring and execution. Plans are immutable and content-addressed (SHA-256 digest), so a run always executes the exact bytes that were submitted.
How it works¶
flowchart TB
subgraph author["Build the workflow"]
direction LR
A["Assistant or TypeScript SDK"] --> B["Validated Plan IR<br/>Immutable JSON + digest"]
end
subgraph execute["Run the plan"]
direction LR
C["Coordinator<br/>State, scheduling, recovery"] --> D["Workers + adapters<br/>Agent and tool execution"]
end
subgraph follow["Inspect the results"]
direction LR
E["Saved outputs<br/>Logs, attempts, artifacts"] --> F["Web UI or assistant<br/>Inspect and control the run"]
end
author -->|start run| execute
execute -->|results| follow
classDef main fill:#173a33,stroke:#78e3d7,color:#e4fff6,stroke-width:2px;
classDef step fill:#152024,stroke:#486363,color:#e6eeee;
class A,B,D,E,F step;
class C main;
style author fill:#10191c,stroke:#304b48,color:#a5d9cf
style execute fill:#10191c,stroke:#304b48,color:#a5d9cf
style follow fill:#10191c,stroke:#304b48,color:#a5d9cf
The plan defines the work. The coordinator saves state and assigns steps to workers; adapters run the selected agents and tools. You inspect the same run through the UI or your assistant.
Key features¶
- Compiled, content-addressed plans — Workflows compile to a stable Plan IR (v1.0) with a SHA-256 digest. A run pins immutable plan JSON; recovery verifies those bytes, never a latest definition.
- Fan-out and control flow —
mapfor bounded-concurrency fan-out,branchfor conditionals,loopwith finite iteration bounds,waitfor external signals,joinfor aggregation,childfor nested sub-runs. - Durable execution — SQLite-backed state, event-sourced history, and explicit recovery. Queued work is eligible for reassignment; effects that may have already happened are held for manual reconciliation rather than silently replayed.
- Retry and fallback — Per-step retry policies (
maxAttempts, bounded backoff) and fallback executors. Effect policies control whether repeating an operation is safe. - Agent adapters — Ship adapters for
agent/a2a,agent/acp,agent/antigravity,agent/claude,agent/codex,agent/cursor,agent/kiro, andcommand. Custom adapter scripts plug in with no coordinator changes. - Observability UI — A web dashboard for run search, activation/scope graphs, event timelines, logs, artifacts, attempt history, worker status, a Live view that streams attempt logs, and a signal form for waiting runs.
- MCP server — Exposes coordinator operations as MCP tools so any MCP-capable assistant (Codex, Cursor, Claude Code, Kiro) can build, check, submit, and inspect runs from its own chat.
- Fake executor for testing — Validate plans and dataflow end to end without invoking real model calls. Fake outputs are keyed by node ID or executor name.
- Remote access over SSH — The coordinator binds to loopback; forward over SSH for secure remote use without exposing an unauthenticated HTTP API.
Quick start¶
Prerequisites¶
- Go 1.26+ (to build the coordinator, CLI, and adapters)
- Node.js 22.13+ (for the full TypeScript build and UI)
- Agent provider CLIs on
PATHfor whichever executors you intend to use (e.g.agy,claude,codex,kiro)
Build from source¶
npm ci # installs the pinned workspace dependencies
npm run setup # builds release prefix under ~/.muxlio and muxlio init
npm run release # build CLI, adapters, and UI into ~/.muxlio (no init)
npm run setup runs scripts/setup.sh: scripts/build-release.sh (Go CLI, eight adapters, UI assets), copies the CLI to .bin/muxlio for this checkout, and runs muxlio init to create ~/.muxlio/config.json with a coordinator bearer token. Fresh setup uses this checkout as the workspace; repeated setup preserves the configured workspace. Set MUXLIO_WORKSPACE=/absolute/path/to/project during setup or use muxlio init --workspace /absolute/path/to/project afterward to select another workspace. Authoring workflows from this checkout still requires npm run build once to compile the TypeScript workspaces (muxlio-sdk, muxlio-compiler, muxlio-testing). Override the runtime root with MUXLIO_HOME.
npm run release runs the same scripts/build-release.sh install into ~/.muxlio (or MUXLIO_HOME) without muxlio init, SDK workspace builds, or copying the CLI into this checkout’s .bin/muxlio. Use it to refresh binaries and UI assets in an existing runtime.
For a custom install prefix without the npm wrapper:
bash scripts/build-release.sh "$HOME/.local/muxlio"
export PATH="$HOME/.local/muxlio/bin:$PATH"
muxlio init --data-dir "$HOME/.local/muxlio" --workspace /absolute/path/to/project
Initialize runtime¶
Before muxlio service start, point the service at an authorized workspace and the executor capabilities the local worker should advertise:
# Example: choose a project workspace and install Antigravity authoring instructions
muxlio init --data-dir ~/.muxlio --workspace /absolute/path/to/project --agent antigravity
# Creates ~/.muxlio/{data,logs,work,artifacts,bin,skills,libexec/muxlio/adapters,share/muxlio/ui}
# and ~/.muxlio/config.json (workspace, capabilities, addr, attemptTimeoutSeconds)
# A coordinator bearer token is generated and stored in config.json.
# --starter writes a sample workflow; --client (or --agent) installs the complete skill bundle for that client.
Fresh configs enable the bundled executors, including command for build checks
and Git. Repeated initialization preserves explicit policies. Use
muxlio init --allow-command to re-enable command execution in an existing config.
muxlio service start also starts the configured MCP listener, so an installed
service can build and start workflows through your assistant.
Default capabilities match the shipped adapters: agent/a2a, agent/acp, agent/antigravity, agent/claude, agent/codex, agent/cursor, agent/kiro, and command. Edit capabilities in config to restrict what the service will run.
Homebrew installation¶
The HEAD formula builds the main branch using scripts/build-release.sh and
installs the same runtime assets as a source release. To prepare a stable tagged
formula release, maintainers run scripts/release-formula.sh <version>, review
the generated archive checksum and formula, then publish the formula update.
Author a workflow¶
Workflows are authored with the TypeScript SDK and compile to Plan IR at build time. The high-level API — workflow, task, artifact, step, each, repeatUntil — uses symbolic typed references and Zod schemas; the lower-level defineWorkflow builder remains available for advanced cases.
import { workflow, task, artifact } from '@muxlio/sdk';
import { z } from 'zod';
const input = z.object({
items: z.array(z.object({ id: z.string(), title: z.string() })).min(1).max(100),
});
const gather = task({
executor: 'agent/antigravity',
task: 'Investigate the topic and write findings to findings.md.',
outputs: { findings: artifact.markdown('findings.md') },
});
const transform = task({
executor: 'agent/claude',
task: 'Read the findings and produce result.md.',
outputs: { result: artifact.markdown('result.md') },
});
export default workflow('batch', {
input,
build: ({ input, step, each }) => {
const results = each(input.items, {
key: i => i.id,
concurrency: 5,
}, item => {
const gathered = step('gather', gather, { item });
const transformed = step('transform', transform, {
findings: gathered.findings,
});
return { id: item.id, result: transformed.result };
});
return { results };
},
});
The build callback runs once at compile time. step, each, and repeatUntil return symbolic proxies — gathered.findings, item.id, and transformed.result are typed references compiled into the plan, not runtime values. Two compilations of the same workflow yield identical content-addressed (SHA-256) digests. repeatUntil compiles to a durable loop: run an attempt, evaluate until against its outputs, run otherwise (a fix) on failure, and onExhausted: 'pause' makes the run resumable. See recipes/implement-features/workflow.ts for a full prepare → implement → review → verify/fix loop → commit recipe.
Compile it (TypeScript → Plan IR):
muxlio build examples/batch.workflow.ts --out examples/batch.plan.json
# or validate/compile in one step:
muxlio check examples/batch.workflow.ts
muxlio build, check, test, and run use the same workflow loading path for .ts, .js, and .mjs files. The CLI executes the module with explicitly installed, project-local tsx 4.23.15 from the workflow file's directory; it never invokes npx or downloads dependencies. All workflow code and its side effects run during compilation with host filesystem and network access. Use JSON Plan IR for untrusted or agent-generated submissions; see compilation security. The module must default-export an object with a plan property or a plan-shaped object. Pass an existing .json file to skip workflow execution. muxlio build validates and prints canonical Plan IR on stdout by default; use --out to write it and --json for a structured summary. For reviewed source, install the pinned dependencies with npm ci in a trusted environment before compiling.
Validate and fake-run¶
muxlio check examples/batch.plan.json
muxlio test examples/batch.plan.json --input examples/batch.input.json --json
# equivalent one-shot local run:
muxlio run examples/batch.plan.json examples/batch.input.json --json
With no --adapters, run uses the fake executor, which generates placeholder artifact references for declared output ports. This exercises the full execution engine and dataflow without invoking agents. Supply --fake-config to control fake outputs by node ID or executor name.
A small local authoring loop¶
examples/acp.workflow.ts and examples/a2a.workflow.ts are minimal ACP and A2A
workflows with fake-config dry runs; see Which adapter should I use?.
examples/local.workflow.ts mixes an inline command task with an inline agent
summary task. From a built checkout, check the bindings, fake-run the same plan,
and inspect its persisted result:
muxlio check examples/local.workflow.ts --json
muxlio build examples/local.workflow.ts --out /tmp/local.plan.json --json
muxlio test /tmp/local.plan.json --input examples/local.input.json --fake-config examples/local.fake.json --json
muxlio run /tmp/local.plan.json examples/local.input.json --fake-config examples/local.fake.json --json
muxlio inspect RUN_ID --json
muxlio graph RUN_ID --json
muxlio artifacts RUN_ID --json
Replace RUN_ID with the runId from run. Fake execution needs no provider
credentials; local.fake.json supplies the command's typed process outputs.
Check/build validate binding shapes, node references (including
nested expressions), declared execute output ports, and dependency cycles before
execution starts. Warnings remain advisory for local and remote runs.
For real execution with a coordinator and one local worker, initialize your
workspace as above, authorize the command executor, and start muxlio service
start. Then use muxlio run examples/local.workflow.ts examples/local.input.json
--server http://127.0.0.1:7600 --json. This compiles locally and uses the same
worker assignment contract as distributed execution. Inspect the run in the UI
for its graph, queue reason, attempts, and artifacts. muxlio cancel RUN_ID
--server http://127.0.0.1:7600 cancels it; muxlio resume RUN_ID --server
http://127.0.0.1:7600 continues a paused run.
If the coordinator has multiple authorized workspaces, list them with
muxlio workspace list --server <profile-or-URL>, then pass
--workspace-id <id> on muxlio run. You can reuse the same TypeScript source
or compiled Plan IR for each authorized workspace when the plan leaves the
workspace unbound. See workspace configuration examples.
Run with real adapters¶
For a capability comparison, decision guide, and minimal ACP/A2A examples, see Which adapter should I use?. The subsections below are the authoritative reference for configuration and limitations.
After npm run setup or build-release.sh, adapters live under ~/.muxlio/libexec/muxlio/adapters (see muxlio env). Point run at that directory with an absolute workspace:
muxlio run examples/batch.plan.json examples/batch.input.json \
--adapters "$HOME/.muxlio/libexec/muxlio/adapters" \
--workspace /absolute/path/to/project \
--data-dir "$HOME/.muxlio" \
--json
Queued attempts and their activations remain queued until a worker claims the
assignment; a running workflow can therefore be waiting for admission without
an agent process executing. Every queued attempt defaults to a three-minute
(180-second) admission timeout,
including tasks without fallback executors. Omitting queueTimeoutSeconds or
setting it to zero uses this default. Set an explicit positive
queueTimeoutSeconds to override this window. An admission timeout proves the
attempt never reached a worker and can advance to retry/fallback within the task's
retry and effect policy. The timeout applies per attempt; exhausting the bounded
retry policy fails the step. For example, queueTimeoutSeconds: 300 allows five
minutes per queued attempt. Once a worker claims the attempt, the queue timeout
no longer applies. An execution timeout does not prove termination and
continues to require the existing cancellation/reconciliation handling.
Each executor maps to one executable file: replace / with - (e.g. agent/claude → agent-claude, command → command). The generic command executor passes program and args directly to the process without a shell. task({ executor: 'command', ... }) automatically provides typed process outputs, so success is available as result.passed, including in repeatUntil conditions; no outputs declaration is needed. With onNonZero: 'return', a nonzero exit produces passed: false so the workflow can run its fix step; onNonZero: 'fail' fails the step instead. Command details are also top-level outputs: exitCode, signal, stdout, stderr, and durationMs. Declare outputs only to add artifacts or customize a schema. signal is null unless the process was terminated by a signal, and stdout/stderr contain bounded previews. Declared files are collected from MUXLIO_OUTPUT_DIR.
agent/a2a executes a remote agent using params: { url: 'https://agent.example', stream: true, timeout: '30s' }. It discovers /.well-known/agent-card.json; cardUrl can select another card on the same origin. This adapter supports A2A 0.3.0 JSON-RPC, including an advertised alternate JSON-RPC interface. Other versions, required extensions, unsupported input modes, and unsupported authentication fail explicitly. Only HTTP bearer authentication is supported; supply A2A_TOKEN through the shared request secret mechanism, never in workflow parameters or URLs. HTTPS is required except on loopback; redirects and cross-origin card endpoints are rejected. Discovery and authentication are checked at invocation, not by the readiness probe.
Submissions use nonblocking message/send. The adapter publishes and returns the remote task ID, context ID and endpoint, allowing the worker process to exit while the task continues. Later polls use that reference without resubmitting. stream: true requires advertised streaming and uses tasks/resubscribe during polls, followed by a full tasks/get snapshot after disconnect or a bounded stream interval. The per-invocation timeout defaults to 30 seconds and cannot exceed one minute. Task and context identities must match on recovery. Configure effect: 'reconcile' and require remoteTask: '1' for durable remote execution. Known submissions reconcile through read-only task lookup; submissions without a task ID remain inconclusive, including when a task is not found. A2A message IDs do not promise deduplication, so this adapter does not advertise idempotency keys.
Remote agents receive the task, inline inputs, and requested output port names/MIME types. They must return artifacts named after output ports. Scalar ports accept JSON data or JSON text; file ports import text or inline base64 bytes into worker scratch for the generic artifact uploader. URI downloads are unsupported, and responses/artifacts are bounded to 4 MiB. Token usage remains unavailable. Input/auth-required states produce explicit unsupported follow-up errors and remain inconclusive during reconciliation, since the remote task can still resume. Local sessions, push notifications, native typed generation, and remote cancellation are unsupported. Stopping a local invocation does not cancel remote work.
agent/acp runs an ACP v1 agent over stdio using params: { program: '/absolute/path/to/agent', args: ['--acp'], timeout: '10m' }. Arguments are passed directly without a shell. The default executable is acp-agent; set MUXLIO_ACP_PROGRAM in the executor's configured environment to select another default (also used by the readiness probe). Explicitly authorize host execution with executors: { "agent/acp": { allow: true } }. Configure credentials through that executor's environment and authenticate the agent before running workflows. The probe verifies executable availability; ACP has no standard version or authentication-status command, so protocol and authentication errors are checked at invocation. Runner pins additionally require the configured executable to support --version.
The adapter negotiates protocol version 1 and agent capabilities before session/new, sends a text prompt with Muxlio result-port paths, and validates the files through the shared output collector. Agent text, tool activity, plans and other session updates appear in live logs. Interrupts send session/cancel, with bounded cleanup if the agent does not respond. Permission requests are denied with an explicit unsupported error. Client filesystem/terminal services, durable sessions, session loading, remote tasks and native typed generation are unsupported, even if an agent advertises session loading. ACP session IDs and progress never become durable Muxlio checkpoints. Token usage remains unavailable; context-window and cost updates are not token totals. Keep using a native adapter when its provider-specific capabilities are needed. See the ACP v1 initialization specification.
Executor permissions and environment values are configured per executor in ~/.muxlio/config.json. An adapter can declare requiresHostExecution in a descriptor beside its executable (<executable>.json). Workers apply that shared metadata when advertising and dispatching capabilities. Host execution requires explicit local authorization; workflow parameters cannot grant it. The bundled command adapter also checks the authorization in its runtime request, so missing metadata never enables it. Its execution.isolation: "sandbox" option fails closed because this release has no verified OCI command backend.
examples/command.workflow.ts shows two tasks using the same executor. Task output files live under the per-attempt artifact directory, exposed to child programs through MUXLIO_OUTPUT_DIR; executables must be installed and authorized on the selected worker. Host mode is intended for a self-hosted, single-owner worker. Required execution isolation is configured through the shared sandbox contract; see the execution security guide.
To authorize command tasks, configure the command executor and restart the service:
The executors map is optional and defaults to {}. Omitted entries use executor defaults; allow: false disables an executor, and allow: true explicitly authorizes it. Set timeoutSeconds on an executor entry to override the global adapter timeout for that capability (1–86400 seconds); an explicit workflow attempt timeout can still be shorter. The same configuration applies to service, standalone, and outbound workers. Environment values are scoped to the named executor and merged with configured shared worker values. Required isolation filters guest environment values through its execution contract. These entries replace the old top-level commandHostEnabled and sshAgentSocket settings.
The command adapter forwards the worker's scoped environment generically,
keeping its scratch HOME, TMPDIR, and output directory. Task params.env
can override forwarded values, except managed PATH, HOME, TMPDIR, LANG,
and MUXLIO_OUTPUT_DIR.
Implement-features recipe¶
recipes/implement-features/workflow.ts is a ready-to-use recipe: in the current git workspace, each feature runs implement → review → a verify/fix loop (repeatUntil, maxAttempts: 10, onExhausted: 'pause') → commit. Features run serially (concurrency: 1); the commit step is gated on a passed verification via { requiresPassed }. The recipe finishes with verified local commits; it does not push or require Git remote authentication.
Start the coordinator and a worker authorized for the target checkout before
submitting this recipe. Shared writes require durable coordinator admission,
which automatically serializes writes to the resolved workspace; direct
--adapters execution cannot enforce these reservations.
Review the commits in the worker's workspace and push manually when ready. With a Docker Sandbox worker in clone mode, fetch them from the host using its Git remote. See the Docker Sandbox walkthrough.
This example uses localhost as a workspace ID for a checkout registered to
the local worker. To run the same recipe in Docker, select sandbox instead.
muxlio check recipes/implement-features/workflow.ts
muxlio run recipes/implement-features/workflow.ts recipes/implement-features/input.example.json \
--server local --workspace-id localhost --json
The recipe splits task definitions into tasks.ts and Zod input schemas into schemas.ts, imported by workflow.ts — the same pattern to follow for your own multi-file workflows.
Submit tonight, check in the morning¶
The durable service pattern keeps work running after you disconnect:
# Requires muxlio init (or ~/.muxlio/config.json with absolute workspace + capabilities)
muxlio service start
# Background daemon: coordinator, outbound local worker (worker-id local), and bundled UI
# Default http://127.0.0.1:7600 — logs in ~/.muxlio/logs/service.log (service.pid / service.lock)
# Submit compiled Plan IR JSON (not .ts); CLI prints the coordinator response and exits
muxlio submit --server http://127.0.0.1:7600 plan.json input.json
# Loopback requests load the bearer token from ~/.muxlio/config.json automatically
# List IDs and aliases available on this coordinator. A single workspace from init is named default.
muxlio workspace list --server http://127.0.0.1:7600
muxlio preflight plan.ts input.json --server http://127.0.0.1:7600 --workspace-id default
muxlio run plan.ts input.json --server http://127.0.0.1:7600 --workspace-id default
# Check on it later
muxlio status --server http://127.0.0.1:7600
muxlio status --server http://127.0.0.1:7600 run_RETURNED_ID
# Graceful shutdown or reload config/process
muxlio service stop
muxlio service restart
muxlio run plan.ts input.json --server http://127.0.0.1:7600 compiles the workflow locally, submits it remotely, and blocks until a terminal state (like submit + poll). Add --workspace-id <id> to bind the run to a coordinator workspace identity without editing the workflow or plan file (same field as muxlio submit --workspace-id). Closing the client or SSH session does not cancel the coordinator's work. Pause takes effect at the next operation boundary; cancel stops local adapter processes when possible.
For remote access, forward over SSH instead of exposing the API (see muxlio-docs/service.md for details):
ssh -N -L 17600:127.0.0.1:7600 mac-mini
muxlio submit --server http://127.0.0.1:17600 plan.json input.json
Observability UI¶
With the supervised service, static UI assets are served from the coordinator address (same port as the API):
For a coordinator without the bundled UI, start the API and launch the UI helper on a second port:
muxlio server start --data-dir ~/.muxlio
muxlio ui --server http://127.0.0.1:7600 --port 7601
# Open http://127.0.0.1:7601/
To run the UI locally against a remote coordinator, point --server at the coordinator's reachable URL:
The UI helper binds to 127.0.0.1 by default and proxies API requests to the remote coordinator. It uses MUXLIO_TOKEN when set, otherwise the token in the local ~/.muxlio/config.json (including the default server profile). Make sure that token belongs to the coordinator you selected. From a development checkout, the equivalent is MUXLIO_API_URL=http://192.168.1.1:7600 npm --prefix muxlio-ui start.
If a UI is already running on port 7601, stop that process before starting it with a different coordinator URL; the CLI reuses an existing UI process.
The dashboard provides run search and state filters, input/output/error and timing details, the materialized activation/scope graph, logs, execution attempt history, a cursor-paginated event timeline, active worker assignments, a Live page for streaming attempt logs from running activations, and a send-signal form for waiting runs.
OpenTelemetry export¶
Local runs, coordinators and remote workers can export OTLP/HTTP traces and metrics. Set these variables on each process (including service child processes):
export OTEL_TRACES_EXPORTER=otlp
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
export OTEL_SERVICE_NAME=muxlio
Export is disabled by default; each signal accepts otlp or none.
Standard OTLP endpoint, TLS and header environment settings configure the HTTP
exporters. Command shutdown flushes pending telemetry with a five-second limit.
Run, activation, attempt, worker and adapter invocation spans share W3C trace
context carried in durable assignments. Muxlio IDs remain span attributes.
Activation and attempt IDs use sha256: followed by the SHA-256 hex digest of
the original ID, consistently across processes, because their scope paths can
contain input-derived map keys. Run IDs retain their generated values.
The shared adapter request includes a traceContext map containing W3C
traceparent and, when present, tracestate, so adapter-owned instrumentation
can continue the invocation span without receiving baggage.
Resumed coordinator executions start another trace segment; the run and attempt
IDs correlate those segments with previously dispatched work. Generic tool spans
use gen_ai.operation.name=execute_tool and gen_ai.tool.name; workflow spans
use invoke_workflow. Provider and model identity stay adapter-owned. Reported
token counts use gen_ai.usage.*; unavailable usage is absent and reported zero
remains zero. These attributes follow the
OpenTelemetry GenAI conventions.
Metrics use seconds for muxlio.queue.delay (enqueue to claim),
muxlio.execution.duration (executor invocation to return, excluding queue and
completion transport), muxlio.adapter.duration (local adapter invocation), and
muxlio.lease.age (time since claim or the last acknowledged renewal).
muxlio.worker.slots.used, muxlio.worker.slots.capacity and
muxlio.worker.slot_pressure expose heartbeat snapshots; pressure is occupied
slots divided by capacity. Metric dimensions use executor or worker identity,
without per-run IDs.
Prompt bodies, params, inputs, transcripts, artifact contents, secrets and error messages are excluded from this instrumentation. It propagates trace identity without baggage. Content capture is not enabled by any Muxlio setting.
Workers¶
- Local worker (service) —
muxlio service startregisters an outbound worker (worker-idlocal) that executes steps inconfig.jsonworkspaceusing adapters fromadapters(default~/.muxlio/libexec/muxlio/adapters). Only capabilities listed inconfig.jsonare advertised, even if more adapters exist on disk. - Remote worker — On another machine, connect with explicit identity and optional capacity:
muxlio worker start \
--coordinator http://127.0.0.1:7600 \
--worker-id mac-mini-1 \
--workspace /path/to/workspace \
--worker-token-file ~/.muxlio/worker-token \
--capacity 2
# Use MUXLIO_WORKER_TOKEN or --worker-token / --worker-token-file for remote worker authentication.
Omit --capabilities to auto-detect executable adapters in --adapters (default ~/.muxlio/adapters). For a release install, pass --adapters ~/.muxlio/libexec/muxlio/adapters; alternatively copy or symlink the adapters there. Pass a comma-separated list to advertise a subset. --capacity sets concurrent assignments (default 1; override with MUXLIO_WORKER_CAPACITY).
Supported first-party executors (one adapter binary each): agent/a2a, agent/acp, agent/antigravity, agent/claude, agent/codex, agent/cursor, agent/kiro, and command.
Local agent adapters run in the selected attempt workspace, including snapshots
without Git metadata. Each adapter supplies its CLI's headless workspace options
and access to the separate scratch directory for declared outputs. Antigravity and
Claude use the same workspace selection and output prompt as the other local
agents. ACP forwards the selected directory to its configured agent; that agent's
launch options remain in params.args. A2A runs remotely and does not use a local
agent workspace.
Antigravity uses the model configured in its CLI unless params.model overrides it.
Its readiness check recognizes ANTIGRAVITY_API_KEY and saved Antigravity API-key or Google login
credentials; credential validity is checked when the task runs.
MCP integration¶
The muxlio-mcp binary exposes coordinator operations as MCP tools over stdio or authenticated Streamable HTTP. Any MCP-capable assistant can call them to build, check, run, and inspect workflows without leaving its chat:
{
"mcpServers": {
"muxlio": {
"command": "muxlio-mcp",
"args": ["--server", "http://127.0.0.1:7600"]
}
}
}
muxlio init registers MCP HTTP at 127.0.0.1:7602 and prepares persistent
authentication tokens. The service starts and stops MCP with the coordinator.
For direct network access, run muxlio init --mcp-listen 0.0.0.0:7602 and
muxlio service restart on the server, then connect the client to
http://<server>:7602/mcp. HTTP requests
require the listener's bearer token (the coordinator token by default); optional
TLS is available with mcp.tlsCert and mcp.tlsKey. No SSH or local MCP process is
required for this connection. See the network setup.
Available tools include build, test, check_plan, start_run, list_runs, get_run, get_graph, get_events, get_activations, get_attempts, get_logs, get_snapshots, register_workflow_version, list_workflow_versions, get_input_requests, respond_input_request, read_artifact, get_artifact_metadata, cancel_run, pause_run, resume_run, retry_run, send_signal, get_workers, and server_health. Saved coordinator profiles and bearer authentication are supported; for example, use muxlio-mcp --server coordinator. See muxlio-docs/mcp.md for the full reference.
Testing with fakes¶
@muxlio/testing exports testWorkflow and fakeExecutor for validating workflows end to end without real model calls:
import { workflow, task, artifact } from '@muxlio/sdk';
import { z } from 'zod';
import { fakeExecutor, testWorkflow } from '@muxlio/testing';
const summarize = task({
executor: 'agent/codex',
task: 'Summarize the input.',
outputs: { summary: artifact.markdown('summary.md') },
});
const compiled = workflow('example', {
input: z.object({ text: z.string() }),
build: ({ input, step }) => {
const s = step('summarize', summarize, { text: input.text });
return { summary: s.summary };
},
});
const result = await testWorkflow(compiled, {
input: { text: 'Example' },
executors: fakeExecutor.byNode({
summarize: { outputs: { summary: { digest: 'sha256:fixture', mime: 'text/markdown' } } },
}),
});
if (result.state !== 'succeeded') throw new Error(`Run state: ${result.state}`);
Workflow evaluations¶
@muxlio/testing can compare compiled workflow versions over typed datasets.
Cases are normalized before any run starts; expected outputs are optional.
Unchanged datasets returned by defineDataset retain their normalized values
when reused, including values produced by transforming parsers. Scorers
run only after successful execution and output validation. A zero score or a
scorer error does not change execution success.
import { defineDataset, evaluateWorkflow } from '@muxlio/testing';
const dataset = defineDataset({
id: 'summaries/v1',
input: z.object({ text: z.string() }),
output: z.string(),
cases: [{
id: 'greeting',
input: { text: 'Hello world' },
expected: 'Hello',
}],
});
const report = await evaluateWorkflow({
dataset,
versions: [
{ id: 'baseline', workflow: baseline },
{ id: 'candidate', workflow: candidate },
],
concurrency: 4,
configuration: { executors: fakeExecutor.byExecutor({
summarize: { outputs: { summary: 'Hello' } },
}) },
scorers: [{
id: 'exact-match/v1',
score: ({ output, expected }) => Number(output === expected),
}],
});
The default runner uses the CLI with fake executors. For real experiments,
provide runner: { id: 'my-runner/v1', async run(workflow, options) { ... } }
that executes workflow.plan with options.input and returns the shared
EvaluationExecution shape (state, output, optional runId, error, and
accounting). Configuration is passed to each run. Give runners and scorers new
versioned IDs when their implementations change, and version the dataset ID
when its schema changes. Inputs, plans, expectations, and configuration must
be JSON serializable with finite numbers. Functions, symbols, bigint values,
and undefined array entries are rejected before execution.
The report includes ordered case/version results, execution duration, errors,
accounting, and named scores. Missing accounting is null; reported zero remains zero.
Accounting retains exact decimal strings, collected and estimated contributions,
fidelity and coverage without inferring tokens. The manifest contains copied plans, recomputed plan digests, a dataset
digest (including expected outputs), a configuration digest, runner/scorer IDs,
and a content-derived evaluation ID. Plans, cases, and configuration are copied
before execution so caller or runner mutations cannot change subsequent runs.
Returned execution output and accounting are also copied to isolate each result.
These identities pin the experiment specification; external model behavior and
services can still vary. Keep the dataset alongside the manifest for replay.
Forking and comparing runs¶
POST /v1/runs/:sourceId/fork creates a new run from a terminal run's original
inputs and pinned plan. The JSON body accepts an optional replacement input,
plan or registered planDigest, and reuseActivations containing successful
activation IDs from the source. For example:
The new run persists its source run and source plan digest. Creation does not
execute steps; use POST /v1/runs/:newId/start or request "start":true at
creation. Unstarted forks remain dormant across coordinator restarts.
Forks execute only steps explicitly declared retry.effect: "pure".
Steps with sessions, remote tasks, workspace state, or exclusive resources are
blocked even when labelled pure. Unsafe steps fail with a diagnostic before
any dispatch; external effects, attempts, signals, and session state are never
copied. The original history remains unchanged.
Selected outputs are reused only for steps declaring workspaceMode: "empty"
and only when the recorded dependency fingerprint matches. Steps using the
default workspace recompute because its source can change between runs.
Empty mode creates a private workspace without copying the worker checkout;
it does not restrict arbitrary host access by native code. This version fingerprints the full pinned plan, node contract,
resolved dependencies, inputs, and structural scope; any plan change disables
reuse. Legacy outputs without fingerprints are recomputed. File outputs require
content-addressed artifact references. Each reuse appends an
activation.output_reused event with the source run, source activation, and
fingerprint. Reuse creates no new execution attempt or copied charges.
GET /v1/runs/:sourceId/compare?other=:newId returns both plans, inputs, results,
and activation differences aligned by scope, node, and occurrence, along with
reuse references and both usage summaries. Observed and estimated costs remain
separate, and unavailable costs remain unavailable. Forking and comparisons
across runs require an administrator credential; run-scoped read credentials
cannot reveal another run through comparison.
Monorepo structure¶
| Path | Language | Description |
|---|---|---|
muxlio-core |
Go | Coordinator, muxlio CLI, muxlio-mcp server, Plan IR interpreter, SQLite state store |
muxlio-adapters |
Go | Executor adapter binaries (agent CLIs and command tools) |
muxlio-sdk |
TypeScript | @muxlio/sdk — plan builder and types for authoring workflows |
muxlio-compiler |
TypeScript | @muxlio/compiler — restricted TS frontend that lowers to Plan IR |
muxlio-testing |
TypeScript | @muxlio/testing — fake workers, fixtures, and test harness |
muxlio-ui |
JS/HTML | Observability web UI for the coordinator |
muxlio-skills |
Markdown | Workflow authoring guide |
muxlio-docs |
Markdown | Architecture, MCP, and service documentation |
examples |
TypeScript | Example workflows (batch fan-out, audit-coverage with branch/map) |
recipes |
TypeScript | Ready-to-use recipes (implement-features, package bug sweep) |
scripts |
Shell | Build, setup, start, upgrade, and install verification scripts |
CLI reference¶
muxlio init [--data-dir dir] [--workspace dir] [--agent name] [--starter]
Initialize runtime and optionally install agent skills/sample workflow
muxlio build <workflow.ts|plan.json> [--out file] Compile workflow to canonical Plan IR
muxlio check <workflow.ts|plan.json> Validate a workflow or plan
muxlio test <workflow.ts|plan.json> --input in.json Test run with fake executor
muxlio run <workflow.ts|plan.json> [input.json] Run a plan locally
muxlio run <workflow.ts|plan.json> [input.json] --server <profile|URL> [--workspace-id id] Run via a coordinator
muxlio preflight <workflow.ts|plan.json> [input.json] --server <profile|URL> --workspace-id <id> [--json]
Check coordinator feasibility without starting a run
muxlio graph <workflow.ts|plan.json|run-id> Display DAG visualization (ascii, json, mermaid)
muxlio inspect <workflow.ts|plan.json|run-id> Print plan structure or run status
muxlio events <run-id> [--since seq] [--limit N] Print run execution events
muxlio snapshots <run-id> [--current] Inspect intermediate artifact snapshots
muxlio gc [--apply TOKEN] Preview or apply offline retention cleanup
muxlio workspace add <id> <absolute-path> --worker-id <id> [--digest sha256:...] [--alias <alias>...]
muxlio workspace list [--json] List locally configured workspace bindings
muxlio workspace list --server <profile|URL> [--json] List the coordinator's workspace catalog
muxlio workspace show <id-or-alias> [--json] Show a locally configured binding
muxlio workspace remove <id-or-alias> Remove a binding from the local config
muxlio workspace digest <directory> Hash prepared workspace contents
muxlio artifacts <run-id> List artifacts generated by run
muxlio signal <run-id> --name <sig> [--data file] Deliver external signal to waiting run
muxlio runs [--state state] List runs in the local runtime (optionally filtered by state)
muxlio ui [--server URL] [--port port] [--open] Launch or open the Observability UI
muxlio env [--shell bash|zsh|fish] Display or export environment configuration
muxlio doctor [--server URL] Run installation and environment health checks
muxlio upgrade [--prefix dir] Upgrade Muxlio runtime from source repository
muxlio server start|install Start or install the coordinator server
muxlio worker start Connect an outbound remote worker (auto-detects capabilities)
muxlio service start [--config path] Start supervised coordinator, worker and UI (background)
muxlio service stop [--config path] Stop the running service
muxlio service restart [--config path] Stop then start the service (start if not running)
muxlio submit [--server URL] [--workspace-id id] plan.json input.json Submit a durable run
muxlio status [--server URL] [run-id] Query remote run status
muxlio pause|resume|cancel [--server URL] run-id Control a remote run
muxlio version Print version info
Global options: --json, --server <profile|URL>, --workspace-id <id>, --token <token>, --token-file <file>, --fake-config <file>, --adapters <dir>, --workspace <dir>, --data-dir <dir>, --addr <host:port>.
See workspace configuration examples for built-in and remote workers.
Development¶
# Build all TypeScript workspaces
npm run build
# Run tests
(cd muxlio-core && go test ./...)
(cd muxlio-adapters && go test ./...)
npm test
npm --prefix muxlio-ui run smoke
# Build a release prefix and verify it
bash scripts/build-release.sh /tmp/muxlio-install
bash scripts/verify-install.sh /tmp/muxlio-install
Run npm run build before Go tests to include the real async compiler regression. Tests use temporary runtimes, ephemeral loopback ports, and fake adapters — they do not install a service or control an existing coordinator.
Plan IR node kinds¶
| Kind | Purpose |
|---|---|
execute |
Run a single step through an executor (agent or command) |
map |
Fan out over an array with bounded concurrency and per-item keys |
branch |
Conditional execution with then / else subgraphs |
loop |
Iterate with a finite maxIterations bound |
join |
Aggregate results across fan-out branches |
wait |
Wait for a timer, signal, or durable input response |
child |
Invoke a nested subgraph with a bounded recursion depth |
project |
Reshape or extract values from bindings |
Security notes¶
- The UI supplies operator credentials to loopback peers and same-origin private-network peers using a private IP Host; cross-origin and cross-site browser requests fail closed. Other remote requests require an explicit Bearer token and retain its scope. Prefer loopback with SSH forwarding. For public web hosting, use TLS and an authenticated gateway that supplies a separate scoped credential for each user; see remote web and MCP access.
muxlio initcreates the administrator token in~/.muxlio/config.json. The CLI attaches it for loopback URLs; override withMUXLIO_TOKEN,--token, or--token-file./healthzstays public for liveness checks. - Any client that can reach the service with a valid token can submit plans that invoke advertised capabilities with your user permissions. Treat MCP and HTTP access as equivalent.
- The service runs as your login user, never as root. A workspace is an execution target, not a filesystem sandbox. Native child processes receive a minimal environment with
HOMEset to the operator's real home by default (reusing existing provider logins such as~/.codex,~/.cursor); set an explicitagentHometo use a dedicated credential directory instead. Required isolation (OCI/bwrap/VM) uses a scratch HOME and mounts no provider credentials. For Cursor on headless macOS, see muxlio-docs/service.md for the one-time credential store setup. - Remote workers may continue an operation already assigned to them after a run is cancelled, so external side effects can occur after cancellation. Recovery does not guarantee exactly-once execution for arbitrary external systems.
Configuration¶
The coordinator reads ~/.muxlio/config.json (override with --config PATH or MUXLIO_CONFIG). Key fields:
| Field | Description |
|---|---|
workspace |
Authorized execution workspace (absolute path; required for service start) |
capabilities |
Executor capabilities the local worker advertises (defaults created by muxlio init list the bundled capabilities; edit to restrict them) |
attemptTimeoutSeconds |
Per-attempt timeout (default 600) |
workerEnv |
Shared native executor environment; saved by init and overridden by per-executor env |
mcp |
Service-owned MCP HTTP listener: listen, optional tokenFile, tlsCert, tlsKey, allowOrigins; muxlio init registers loopback port 7602 |
runtimeDir |
Runtime data directory (default ~/.muxlio) |
addr |
Listen address (default 127.0.0.1:7600) |
adapters |
Adapter directory (default beside installed CLI: libexec/muxlio/adapters) |
ui |
Static UI assets (default share/muxlio/ui; served at / when using service start) |
agentHome |
Credential directory for native adapters (defaults to the operator's home) |
executors |
Per-executor operator policy: allow, env, secretEnv, and timeoutSeconds |
token |
Bearer token for API access (auto-generated by muxlio init if missing) |
defaultServer / servers / profiles |
Named coordinator URLs for --server (optional) |
Environment overrides: MUXLIO_HOME, MUXLIO_ADDR, MUXLIO_ADAPTERS, MUXLIO_UI, MUXLIO_WORKSPACE, MUXLIO_CAPABILITIES (comma-separated), MUXLIO_SERVER, MUXLIO_TOKEN, MUXLIO_CONFIG. Explicit environment values take precedence over config.
Runtime layout under ~/.muxlio: data/coordinator.db (SQLite), logs/ (including service.log), scratch work/, artifacts/, bin/, libexec/muxlio/adapters/, share/muxlio/ui/, service.pid, service.lock, config.json, env (shell exports).
License¶
Apache License 2.0. See LICENSE for details.
Durable input requests¶
A wait node with waitFor: "input" asks an authenticated human or agent for
information. Approvals use the same contract as other input. The coordinator
persists the request and enters waiting without dispatching a worker or holding
a worker slot. Restarting the coordinator resumes the same request.
{
"id": "review",
"kind": "wait",
"waitFor": "input",
"signalName": "release-review",
"requestSchema": {
"type": "object",
"required": ["approved"],
"properties": {"approved": {"type": "boolean"}},
"additionalProperties": false
},
"requestExpiresSeconds": 3600,
"requestPermissions": ["release:review"]
}
requestSchema, expiration and permissions are optional. Schemas must be
self-contained JSON Schema; remote references are disabled. Responses may be any
JSON value matching the schema. Zero or omitted expiration has no deadline.
An expired request fails the wait. A successful wait exposes the accepted value
on its response output port. Request IDs derive from activation identity, so
parallel map items with the same name remain individually addressable.
Use GET /v1/runs/:runId/input-requests to discover IDs, schemas, deadlines,
permissions and states. Submit a JSON response as the body of
POST /v1/runs/:runId/input-requests/:requestId, with an Idempotency-Key header.
Scoped credentials need inputs on that run plus every permission declared
by the request; listing accepts read or inputs. Operator credentials can
respond to all requests. The authenticated credential identity is recorded with
the accepted response; clients cannot choose the responder identity.
Delivery has at-most-once acceptance per request: the first response wins.
Retrying with the same nonempty key returns the original response and
accepted: false, without consuming another response, even after a restart.
A different key after fulfillment, an expired request, or a cancelled request
returns HTTP 409. Malformed JSON returns 400, schema mismatches 422, and missing
permissions 403. Retrying a response still requires authorization and valid JSON
matching the schema. Name-based signals cannot fulfill input requests.
muxlio signal RUN_ID --list-requests
muxlio signal RUN_ID --request-id REQUEST_ID --idempotency-key DELIVERY_ID --data '{"approved":true}'
MCP exposes get_input_requests and respond_input_request (arguments:
runId, requestId, idempotencyKey, response). The run workbench displays
each request with schema-driven controls and a JSON editor for complex schemas.
Existing waitFor: "signal" waits retain name-based delivery; CLI
--idempotency-key and MCP send_signal.idempotencyKey deduplicate retries.
Outbound lifecycle subscriptions¶
Subscriptions are optional and deliver persisted lifecycle events independently
of workflow execution. Create an immutable subscription with the administrator
credential using POST /v1/subscriptions:
{
"id": "workflow-notifications",
"target": "https://receiver.example.com/muxlio",
"secret": "replace-with-at-least-16-secret-bytes",
"eventTypes": ["run.succeeded", "run.failed", "run.waiting", "worker.*"],
"redactFields": ["input", "output"],
"maxRetries": 5
}
For metadata-only run notifications, add "payloadMode": "notification" and
select the events you want, for example:
{
"id": "run-notifications",
"target": "https://receiver.example.com/muxlio",
"secret": "replace-with-at-least-16-secret-bytes",
"payloadMode": "notification",
"eventTypes": ["run.succeeded", "run.failed", "input.required", "execution.reconciliation_required"],
"maxRetries": 5
}
Notification mode emits only these four event types, plus run.cancelled when
selected (including through * or run.*). Success and cancellation have kind
completion; failure has kind failure. The two attention events have kinds
input_required and reconciliation_required. Input events are committed with
each newly pending request, including requests renewed by explicit retry;
recreating the same request emits nothing. Reconciliation events are committed
when an attempt first enters reconciliation or acquires an unresolved reason; repeated
updates during that wait emit nothing. Each distinct wait has its own source
event ID. These events do not depend on a connected MCP client.
The usual signed envelope retains the source event's eventId, eventType,
runId, seq, timestamp, and subjectId. Its payload is exactly:
{
"version": 1,
"source": "muxlio.run-event",
"kind": "completion",
"links": {
"run": "/runs/<escaped-run-id>",
"status": "/v1/runs/<escaped-run-id>/summary"
}
}
Links are relative to the coordinator, use normal authentication, and contain
no bearer tokens. The run link opens the web UI; the status link returns the
same summary exposed by MCP get_run_summary. Notification payloads exclude
workflow names, prompts, transcripts, input schemas/answers, outputs, failure
text, and external operation references before persistence, without relying
on configured redaction. Additional redactFields still apply. Omitting
payloadMode (or choosing event) preserves the lifecycle event payload behavior
below. Unknown modes are rejected.
Notifications describe durable past transitions, not a fresh assertion that all work or external effects have finished. Follow the status link for the current canonical outcome, unresolved input/reconciliation, and further inspection links. A receiver may display that link, send an alert, or use a host-supported client integration. Muxlio cannot generally resume a disconnected client conversation or reopen a closed chat. Delivery is optional; later MCP status retrieval works without a subscription or a live original client.
Filters accept exact event names, category prefixes such as run.*, or *.
worker.activity reports worker assignment lifecycle activity; execution attempt
outcomes can also be selected with execution.attempt. New subscriptions replay
matching retained events, then follow new events. Disabled subscriptions do not
fan out or deliver. Definitions default to enabled; secrets are write-only.
Each POST contains eventId, eventType, runId, seq, timestamp,
subscriptionId, subjectId, and payload. Deduplicate by eventId: delivery
is at least once, and IDs remain stable across retries and coordinator restarts.
Verify X-Muxlio-Signature as sha256= plus the hex HMAC-SHA256 of the exact raw
body using the subscription secret. Verification must use a constant-time
comparison. X-Muxlio-Event-ID also carries the event ID. Optional
signatureHeader, signaturePrefix, and signatureEncoding (hex or base64)
customize signing. Signature headers cannot use transport headers or
Content-Type / X-Muxlio-Event-ID; prefixes must use printable ASCII and
cannot start with whitespace.
Redirects are rejected.
Credential fields and embedded credentials are scrubbed automatically.
redactFields removes additional field names recursively, including within
arrays, before delivery records are persisted and bodies are signed. Choose
these fields to exclude sensitive workflow data specific to your application.
The envelope is capped at 1 MiB. Delivery records expose generic failure reasons,
never receiver response bodies or errors containing payloads or credentials.
Delivery runs in the background with a five-second request timeout and bounded
exponential backoff (one to 256 seconds after an attempt finishes).
maxRetries defaults to five, accepts
zero to fifty, and counts retries after the first attempt. An outage never
changes the workflow outcome. Pending deliveries and retry counts survive
restarts. Coordinator shutdown leaves interrupted deliveries pending without
consuming retries. Embedded coordinators may register in-process hooks on
subscription.Dispatcher.Hooks and target them with local:hook-name; hooks
receive the same signed, redacted bytes. API definitions cannot execute shell
commands. Hook invocations are bounded to one outstanding call per dispatcher;
a hook that ignores cancellation cannot block coordinator shutdown.
Administrator-only inspection and controls:
GET /v1/subscriptionsandGET /v1/subscriptions/:id: definitions without secrets.GET /v1/subscriptions/:id/deliveries: up to 1,000 recent delivery records.GET /v1/subscriptions/deadletters: up to 1,000 exhausted deliveries.POST /v1/subscriptions/deliveries/:deliveryId/requeue: start a new bounded retry cycle for a dead letter, preserving its event ID.DELETE /v1/subscriptions/:id: permanently disable fanout and delivery while retaining history. IDs cannot be reused; create a new ID to change a receiver or signing key.
Inbound webhook triggers¶
A trigger pins a registered digest so each future delivery uses the configured
plan. Register a validated plan with POST /v1/workflow-versions, then use the
returned digest as workflowDigest when creating the trigger with
POST /v1/triggers using the administrator credential. For an immediate
one-off run, use inline submission.
{
"id": "incoming-task",
"workflowDigest": "sha256:<registered-plan-digest>",
"secret": "<at-least-16-bytes-of-random-secret>",
"inputMapping": {"title": "{{/event/title}}", "count": "{{/event/count}}"},
"payloadLimitBytes": 1048576,
"deduplicationSeconds": 86400
}
Send raw JSON with POST /webhooks/incoming-task. This route requires the
trigger's HMAC-SHA256 signature on every request, including local requests;
a coordinator bearer token cannot replace it. The default signature is the
hex-encoded HMAC of the exact request body in X-Muxlio-Signature. Configure
signatureHeader, signaturePrefix (for example sha256=), and
signatureEncoding (hex or base64) for another generic signing convention.
Provider-specific event translation belongs in the sender or an adapter.
Secrets are write-only in the API and stored in the coordinator database;
protect the database and use HTTPS for remote delivery.
Idempotency-Key (up to 256 bytes) scopes retries to a trigger. Within the
configured window, concurrent or repeated valid deliveries return the same run
(200, duplicate: true); the first delivery returns 201. The window starts
at the first accepted delivery and survives coordinator restarts. After expiry,
the key can create a new run. Without a key each accepted delivery creates a run.
HMAC covers the body; senders must keep the idempotency header stable on retries.
Mapping strings use RFC 6901 JSON pointers in {{/path}}. A whole reference
preserves the source JSON type; embedded references interpolate scalar values.
With no mapping, the payload itself is the input. Invalid signatures, oversized
or malformed JSON, missing references, and inputs that fail the pinned plan's
input schema never create runs. The default payload limit is 1 MiB (maximum
8 MiB). Mapped input is also capped at 8 MiB, including repeated references
and JSON escaping. The default deduplication window is 24 hours (maximum 30 days).
Triggers default to enabled; enabled: false creates an inactive trigger.
Definitions are immutable: use a new trigger ID to change a pin or secret.
Inspect definitions with GET /v1/triggers or GET /v1/triggers/:id and audit
delivered, duplicate, and rejected attempts with
GET /v1/triggers/:id/deliveries, all under administrator authentication.
Each delivery records its workflow digest; each run stores the same digest and
immutable plan bytes, independent of subsequently registered versions.
The test-event command sends a real signed delivery and creates a real run:
muxlio test-event --server https://coordinator.example \
--secret-file /secure/trigger-secret --idempotency-key test-001 \
incoming-task event.json
Use --signature-header, --signature-prefix, and --signature-encoding when
the trigger uses custom signing settings. Repeating the command with the same
key exercises deduplication.
Large-run operations in the UI¶
The execution workbench pages executions, event history, attempt history, outputs and intermediate snapshots independently. Refresh preserves the selected history page; live events use a separate bounded feed. Artifact bytes, full attempt results, and run input/output values load when opened.
The Operations & usage tab shows the pinned version, run limits, detached operations, reconciliation holds, and collected/estimated/unavailable accounting. Worker details expose readiness checks, capability contracts and placement labels. Persistent sessions expose supported input-delivery policies and receipts. Token counts automatically use K, M, or B units.
Paged reads are opt-in for API clients: /v1/runs?offset=0&limit=25,
/v1/runs/:id/graph?offset=0&limit=50, and
/v1/runs/:id/attempts?offset=0&limit=50&details=false return hasMore
and nextOffset. /v1/runs/:id?summary=true omits input/output bodies while
preserving totals across the whole run. /v1/runs/:id/outputs lists port
metadata; /v1/outputs lists file references across runs without inline bytes.