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 declare each provider operation and the credential that authorizes it. 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 a run.yaml execution profile. Each runner is a list of steps, and each step is one of five kinds: agent, tool, operation, ask, or skill.

skill: hello-world
version: "0.1.0"

runners:
  default:
    default: true
    inputs:
      message:
        type: string
        required: true
    steps:
      - id: default
        tool: { command: node, args: [run.mjs] }
        inputs:
          message: $input.message
        outputs:
          message: string

The split is deliberate:

• SKILL.md owns the knowledge a human and acting agent need.
• run.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
    inputs:
      message: $steps.first.message

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

• Graphs own deterministic composition, branches, guards, and recovery.
• Agent steps 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.
• Process 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.
• Connector operations perform governed HTTP, MCP, or Connect requests 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

Credentials belong to connectors, and skills only name the connector operations they call. Bind an account once by piping material on stdin:

printf '%s' "$NITROSEND_API_KEY" |
  runx credential set nitrosend --credential api_key --from-stdin

runx skill ./skills/nitrosend status --json

The kernel delivers the bound instance's credential to each operation it admits, so no skill, prompt, input, or receipt holds the material. 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 Credentials and Security Authority Proof.

what a receipt proves

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

Question	Receipt surface
What ran?	subject, skill ref, source type, runner metadata
Who or what admitted it?	actor ref, grant refs, execution terms
What was allowed?	scopes, resolved grants, approval metadata
What happened?	acts, output artifacts, exit status, closure summary
Can it be checked later?	content-addressed id, canonical digest, signature, lineage
Did secrets leak into proof?	redaction metadata and hashed material refs

Every governed execution passes through one invariant:

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

Runx signs every receipt. With no signer configured, it signs with this runx home's own key, created on the first run. Verify the workspace's receipts against it:

runx verify --json

A receipt from another home or a hosted issuer verifies against the public key you configure for it. 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:

Demo	What it proves	Run
examples/hello-world	Native CLI skill path and sealed receipt baseline	runx harness examples/hello-world
skills/business-ops	One signal fans through governed lanes and preserves a graph receipt	runx harness skills/business-ops
examples/http-graph	Native governed HTTP executes against a local fixture	sh examples/http-graph/run.sh

See Demos.

publish and trust

A public skill is a standalone package: a substantive SKILL.md, optional run.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:

Layer	Owner
portable wire contracts	runx-contracts
pure policy, authority, and state transitions	runx-core
package parsing and the aggregate validated package IR	runx-parser
canonical receipts, hashing, signatures, verification	runx-receipts
execution, capabilities, process supervision, adapters, effects	runx-runtime
argument parsing and presentation	runx-cli
generated language bindings and narrow extension protocols	packages/
operator knowledge and irreducible domain computation	skills/ and product-owned packages

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

Read this	When you need
getting started	first skill, first receipt
system architecture	ownership, execution lanes, boundaries
credentials	connector credentials, instances, hosted grants
skill to graph	compose governed acts
security authority proof	scope, credentials, grants, verification
demos	runnable proof paths
publishing	local and hosted skill publishing
skill catalog	categories, search, first-party map
reference	CLI, crates, registry, receipts, extension protocols
the spec	act model, receipt grammar, public contracts
the catalog	governed skills by URL

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}