runx

the governed runtime for agent skills

a skill is a URL.
a graph is what unfolds.
authority narrows. it does not pass through.
every act produces a receipt.

A skill is expertise published as a portable SKILL.md: an operating manual that a human can understand and an agent can act from. Skills compose into graphs and real work without bespoke glue code. Runx supplies the boundary: it admits each act under explicit authority, delivers credentials without turning them into prompt material, supervises execution, and seals the result into a verifiable receipt.

Authority narrows through the chain, so agent work compounds without becoming ambient trust.

what runx is not

Runx is the governed runtime beneath agents and orchestration tools, not another agent framework. There are no agents, prompt chains, model loops, or vector stores here; runx sits under whatever orchestration layer you already run. Runx admits each act under explicit authority, delivers credentials without turning them into prompt material, supervises execution, and seals the result into a verifiable receipt.

The local CLI/runtime (runx, the @runxhq/cli npm package) is what executes skills and seals receipts on your machine. The hosted surfaces are optional complements: the registry/catalog at runx.ai/x publishes and discovers skills, the harness replays checked-in cases, and connectors are credential-bound provider adapters. You can use the local runtime alone; none of the hosted surfaces are required to seal your first receipt.

quickstart

This README has an agent-readable twin at runx.ai/SKILL.md. Give it to an agent and the agent learns the CLI, the catalog at runx.ai/x, and how to return receipts.

Install the CLI:

npm i -g @runxhq/cli
# or: curl -fsSL https://runx.ai/install | sh

Then choose how you want to run skills.

agent path

Hand the agent a goal and let it drive the runtime:

Use runx to plan and execute end-to-end business ops for my company.
Signal: acme.com signed up 40 seats yesterday.
Stop before sends, spend, merges, deploys, or publishing. Return receipts.

CLI path

Run a local or catalog skill directly:

runx skill <skill-ref> [runner] -i key=value --json

Seal a receipt locally in under five minutes, with no account and no hosted surface:

npm i -g @runxhq/cli
git clone --depth 1 https://github.com/runxhq/runx.git
cd runx
runx skill ./examples/hello-world -i message="hello, runx" --json

The checked-in examples/hello-world skill runs a local command, and the final --json output is a runx.skill_run.v1 result with status: "sealed" and a receipt_id. Inspect the governance record with runx history <receipt-id> --detail --json.

business-ops is one prebuilt skill for routing a business signal end to end:

runx skill business-ops \
  -i signal="acme.com signed up 40 seats yesterday: classify the work, prepare the governed handoffs, and preserve proof" \
  --json

The graph is the core shape. One signal enters, skills chain under governed authority, consequential lanes hold at approval gates, and every act seals into one receipt tree that can feed the next run. The demo lanes are stand-ins; real teams bind their own context, policies, tools, providers, and readbacks.

Some other examples:

# Docs and product engineering: build a source-bound documentation packet.
runx skill sourcey -i project=. --json

# Research and strategy: produce a governed decision brief.
runx skill deep-research \
  -i objective="Which launch risks should we resolve first?" \
  --json

# Maintainer operations: draft a useful issue response.
runx skill issue-triage \
  -i issue_url=https://github.com/runxhq/runx/issues/241 \
  -i objective="Draft the next helpful maintainer response" \
  --json

Build the native CLI from source when working on Runx itself:

cargo build --manifest-path crates/Cargo.toml -p runx-cli

On macOS 26, complete the Developer Tools permission prerequisite if this build stalls.

The npm package distributes the same Rust-owned behavior; it is not a second runtime.

a skill carries judgment, not runtime plumbing

SKILL.md is the capability's operating manual. It teaches the operator what the work means, when to use the lane, what evidence matters, where judgment ends, what requires approval, how failure and recovery work, and when to route to an adjacent skill.

---
name: hello-world
description: Echo a first Runx message through a checked-in command.
---

# Hello World

Use this package to prove the local execution and receipt path.

When a skill needs deterministic execution, typed inputs, graph stages, authority, artifacts, or harness cases, it also carries an X.yaml execution profile:

skill: hello-world
version: "0.1.0"

runners:
  default:
    default: true
    type: cli-tool
    command: node
    args: [run.mjs]
    inputs:
      message:
        type: string
        required: true

The split is deliberate:

• SKILL.md owns the knowledge a human and acting agent need.
• X.yaml owns machine-checkable execution, authority, and evidence contracts.
• package JavaScript exists only for deterministic domain computation that the graph and native capability plane cannot express cleanly.
• HTTP, filesystem, process, credential, packet, and receipt mechanics belong to the runtime, not copied helpers inside skills.

Runx digest-binds the complete current manual into the acting context and the resume envelope. Declared adjacent skills contribute bounded summaries until invoked; invocation then supplies that skill's complete manual.

See Skill to Graph and Skill Catalog.

graphs make acts composable

A runner calls runx through the CLI subprocess (runx skill <skill-ref> ...), the MCP surface, or the language bindings in packages/; there is no HTTP server to stand up. One runx skill invocation is one governed turn; to chain multiple skills in a single run, compose a graph.

Graphs let one governed act consume the typed output of another:

name: hello-graph
steps:
  - id: first
    skill: ../hello-world
    inputs:
      message: hello from graph
  - id: second
    skill: ../hello-world
    context:
      message: first.stdout

The boundary is not how many model calls happened. The boundary is what must be guaranteed:

• Graphs own deterministic composition, branches, fan-out, guards, and recovery.
• Agent tasks own bounded judgment under the current manual and an explicit tool set.
• Native capabilities own reusable, product-neutral runtime mechanics.
• Deterministic modules perform isolated JSON-to-JSON domain computation with no ambient filesystem, network, process, environment, clock, or random authority.
• CLI tools are intentional trusted local executables under an exact resolved grant. Runx controls argv, cwd, delivered environment, credentials, supervision, and evidence; it does not claim portable OS confinement.
• Provider adapters perform governed HTTP, MCP, external-adapter, outbox, or Connect operations under typed authority and effect contracts.

Required mutations, API calls, payments, and provider writes belong in deterministic effect-owning lanes. An agent or graph author cannot acquire an effect merely by naming it in prose or input data.

authority without secret leakage

Provider-backed skills declare credential requirements in X.yaml. Configure a durable local profile by piping material on stdin:

printf '%s' "$NITROSEND_API_KEY" |
  runx credential set nitrosend --profile account-one --from-stdin

runx skill ./skills/nitrosend status --profile account-one --json

Runx resolves explicit profiles, project bindings, global defaults, hosted handles, and the workspace environment through one canonical path. Skill runs, resume, inspect, managed agents, and MCP use the same readiness contract.

Receipts may include requested and granted scopes, grant references, typed execution-boundary observations, approval decisions, provider observations, and hashes. They must not contain raw tokens, passwords, ambient environment dumps, or unchecked private provider bodies.

See Credential Resolution and Security Authority Proof.

what a receipt proves

A Runx receipt answers the questions that matter after the agent has moved on:

Every governed execution passes through one invariant:

admit -> resolve grant -> deliver credentials -> execute -> seal

Run a local verification with the explicit development-signature allowance:

runx verify --allow-local-development-signatures --json

Production verification requires a trusted verification key. The receipt is not the product by itself; it is where authority, action, evidence, and future learning meet in one verifiable object.

The committed contract is schemas/receipt.schema.json; a real sealed receipt example lives at fixtures/receipt-verify/tampered-body/receipt.json.

demos that prove boundaries

These checked-in paths produce receipts rather than screenshots or prose-only claims:

See Demos.

publish and trust

A public skill is a standalone package: a substantive SKILL.md, optional X.yaml, and only the files Runx can consume. Publish locally first:

runx registry publish ./skills/<your-skill>

Then publish to the hosted catalog when you want shared discovery:

runx login --for publish
runx registry publish ./skills/<your-skill> \
  --registry https://api.runx.ai

Hosted publishing reconstructs the submitted package, reruns its harness, and stores immutable package digests. Publisher declaration alone is not trust.

See Publishing.

architecture

Runx has one owner for every contract and behavior:

The native CLI, SDKs, schemas, catalog views, exported agent shims, and docs all consume those owners; none is a parallel parser, executor, credential loader, authoring framework, effect registry, or provider client.

The normative contract is Runx System Architecture. Historical design notes explain how the repository arrived here but do not override it.

docs

contributing

Setup, focused test selection, and sign-off rules are in CONTRIBUTING.md. Security policy: SECURITY.md. Runx is Apache-2.0 licensed; see LICENSE.

_{built in Rust · Apache-2.0 · runx.ai}