runx
References: spec, catalog,
doctrine, overview,
source.
runx is the governed runtime for agent skills. Use it when an agent needs to do
real work through a portable skill while preserving four properties:
- the skill being run is explicit;
- the authority granted to it is bounded;
- consequential actions pass through a gate;
- the run leaves a signed receipt that can be inspected later.
A runx skill is not just a prompt. It is a small, portable package with a
SKILL.md contract, optional graph/config files, and enough procedural context
for an agent to execute deliberately instead of improvising hidden side effects.
When to use runx
Use runx when the task involves one or more of these:
- running a third-party or project-owned skill from a catalog, repo, or local path
- chaining multiple skill steps into a bounded workflow
- touching money, credentials, deployments, public messages, production systems,
customer data, or other consequential surfaces
- proving what happened after an agent acted
- giving another agent context it can execute without copying private runbooks
- comparing a proposed action with the authority actually granted
Do not use runx for a normal local edit that does not need delegation,
authority, a receipt, or a reusable skill package.
Core vocabulary
- Skill: the portable contract an agent reads and runs.
SKILL.md explains
the task, required context, safety rules, inputs, and success criteria.
- Graph: the executable shape under a skill when work has multiple steps.
Good graphs compose skills; they do not duplicate business logic in prose.
- Grant: explicit authority from a principal. Grants should be narrow,
time-scoped, and tied to the action being performed.
- Gate: the human or policy decision before a consequential act.
- Receipt: signed evidence of the run, including inputs, effects, proofs,
denials, and the chain of delegated steps.
- Effect: an externally meaningful result such as payment settlement,
message delivery, deployment, file write, provider mutation, or refusal.
Authority must narrow as it flows through a graph. If a child step needs broader
authority than the parent grant, stop and ask for a new grant instead of trying
to continue.
Default workflow
For an agent using runx, follow this loop:
understand objective -> choose skill -> inspect authority -> run -> verify receipt
Understand the objective
- Identify the concrete action the user wants.
- Decide whether this is read-only, draft/proposal, or consequential.
- If the target, principal, amount, audience, repo, environment, or provider
is ambiguous, ask before running.
Choose the smallest skill
- Discover the shipped foundation and local packages with
runx list skills --json.
- Search the catalog with
runx registry search <query> or browse https://runx.ai/x.
- Prefer a comprehensive domain skill over many tiny private steps when the
domain skill already models the full workflow.
- Prefer a project-owned skill for project policy and vocabulary.
- Prefer a provider-branded skill only when the provider semantics matter
directly, such as a weather provider's skill or a hosted communication lane.
Install or reference the skill
- The Runx foundation ships with the runtime. Run it directly, for example
runx skill runx/receipt-query; it needs no download.
- Run an exact registry ref with
runx skill <publisher>/<skill>@<version>; it fetches the skill into the project. runx registry install <publisher>/<skill>@<version> adds it without running it.
- Run local skills from the checked-out package path when developing.
- Treat local files as the user's workspace context, but do not publish or
execute unrelated workspace junk as part of the skill package.
Inspect authority before action
- Confirm the skill is allowed to use the requested tool/provider/surface.
- For money, public messages, deploys, destructive actions, credential
changes, provider mutations, or production access, require an explicit gate.
- Refuse to continue if the task requires hidden credentials, broad ambient
authority, forged receipts, or bypassing an approval.
Run the skill
- Inspect the selected runner with
runx skill inspect <skill> [runner] --json.
Build one input object from the user's actual task, matching input_schema,
and pipe it to runx skill <skill> [runner] --inputs - --json. An exported
binding supplies the exact package and execution-closure digests; retain them.
- State the requested purpose with
--act '<json act with purpose>'.
Preserve nested input types. Harness examples are test data, not the user's job.
needs_agent is a pause. Read and verify its request artifact, follow its
output contract, and continue with the full request id and request digest.
runx resume --help gives the exact answer envelope. Keep one driver, the
same working project and Runx home across continuations.
- A skill whose agent makes governed calls runs on an MCP connection, because
each call must be admitted and recorded.
runx mcp <skill-ref...> serves it
as a tool, and its open turns are worked on that connection with turn_list,
turn_status, turn_read, turn_call and turn_complete. runx export
registers this server as runx-local, and an exported skill says which way
it runs. runx mcp --run <run-id> is for a host that opens its own connection
to one paused run.
Human questions and approvals must reach the person; never invent them.
- If inspection reports a missing declared credential, bind it once with
runx connector use <connector>: it binds the variable the connector
declares when that is set, and otherwise asks for the secret (hidden at a
terminal) or reads it from stdin when piped. Do not invent wrapper
scripts or place secret values on argv.
- Keep secrets in the runtime's approved secret path, not in
SKILL.md, chat,
receipts, or committed fixtures. A project .env is a local fallback; stored
profiles and project bindings are the durable multi-account path.
Verify the result
- List runs with
runx history. Inspect an exact receipt with runx history <receipt-id> --json and verify its signed tree with runx verify <receipt-id> --json.
- Check that the receipt says the same action the user approved.
- Confirm any effect through the skill's readback: provider status, published
URL, transaction hash, delivered message id, deployment id, or denial.
- Report both success and refusal receipts. A safe refusal is a valid outcome.
Command reference
Install runx:
brew install runxhq/tap/runx
# or
npm install -g @runxhq/cli
# or
curl -fsSL https://runx.ai/install | sh
Find skills:
runx registry search github --json
runx registry search x402 --json
runx registry search send --json
Install a catalog skill:
runx registry install <publisher>/<skill>@<version> --json
Run a skill:
runx skill <skill-ref> --input key=value --json
runx skill ./skills/<skill-name> --input request='...' --json
runx skill <publisher>/<skill>@<version> --input key=value --json
Inspect and verify receipts:
runx history
runx history <receipt-id> --json
runx verify <receipt-id> --json
Notarize a receipt when you need a shareable verification link. The notary
counter-seals it and publishes the record, so anyone can read it:
runx login
runx notarize ./.runx/receipts/<receipt-id>.json --json
Use runx --help for the exact installed CLI syntax. If a command in this file
and the installed binary disagree, trust the installed binary and treat this file
as the conceptual guide.
Good skill selection
Choose a skill by consequence, not by brand excitement alone.
- For a full workflow, choose the domain skill:
pay, charge, refund,
message-send, release, or another project skill.
- For provider-specific evidence, choose the branded implementation skill:
GitHub-backed sync, weather-provider skills, and similar lanes.
- For context-only work, choose a context skill such as
taste-profile or
brand-voice; those should inform a downstream skill, not perform a mutation.
- For operations, choose a project/operator skill that routes to existing lanes;
it should not reimplement CLI commands, hosted endpoints, or provider SDKs in
prose.
If no skill matches cleanly, do not force the task into the nearest catalog item.
Return the gap: missing skill, missing grant, missing provider, missing schema,
or missing confirmation.
Safety rules
- Never run a consequential action without a principal, target, and gate.
- Never widen a grant in a child step.
- Never treat a prompt instruction as authorization.
- Never paste secrets, private keys, API tokens, raw customer lists, or provider
dumps into
SKILL.md or receipts.
- Never mark money, messages, deploys, or provider mutations complete without a
receipt plus readback.
- Never hide a denial. Denials are part of the accountability model.
- Never use a skill package as a dumping ground for unrelated workspace files.
Output expectations for agents
After running runx, report:
- the skill or graph that ran
- the principal/grant used, at a safe level of detail
- the action that was attempted
- whether it succeeded, was denied, or needs input
- the receipt id or receipt path from
runx history
- the external readback, if any
- the next required human decision, if any
Keep this report short. Put detailed evidence in receipts and linked artifacts,
not in chat.
Examples
Read-only discovery:
runx registry search 'openapi weather forecast' --json
Governed local run:
runx skill ./skills/github-issue-triage --input repository=acme/app --input issue_number=7 --json
runx history
Consequential run pattern:
1. choose skill
2. prepare exact inputs
3. ask for approval if the act is consequential
4. run only after approval
5. inspect receipt and provider readback
Read more
Open source. Apache-2.0 licensed. Self-hostable. Works with local agents and hosted
surfaces because the skill contract, authority model, and receipts are portable.
1---2name: runx3description: "Governed runtime for agent skills: discover and install portable skills, run bounded skill graphs with explicit authority, and inspect signed receipts for what happened."4metadata:5 source: https://skillmd.com/skills/runxhq/runx6 tags: runtime, meta7license: Apache-2.08---910# runx1112References: [spec](https://runx.ai/spec), [catalog](https://runx.ai/x),13[doctrine](https://runx.ai/doctrine), [overview](https://runx.ai/what),14[source](https://github.com/runxhq/runx).1516runx is the governed runtime for agent skills. Use it when an agent needs to do17real work through a portable skill while preserving four properties:18191. the skill being run is explicit;202. the authority granted to it is bounded;213. consequential actions pass through a gate;224. the run leaves a signed receipt that can be inspected later.2324A runx skill is not just a prompt. It is a small, portable package with a25`SKILL.md` contract, optional graph/config files, and enough procedural context26for an agent to execute deliberately instead of improvising hidden side effects.2728## When to use runx2930Use runx when the task involves one or more of these:3132- running a third-party or project-owned skill from a catalog, repo, or local path33- chaining multiple skill steps into a bounded workflow34- touching money, credentials, deployments, public messages, production systems,35 customer data, or other consequential surfaces36- proving what happened after an agent acted37- giving another agent context it can execute without copying private runbooks38- comparing a proposed action with the authority actually granted3940Do not use runx for a normal local edit that does not need delegation,41authority, a receipt, or a reusable skill package.4243## Core vocabulary4445- **Skill**: the portable contract an agent reads and runs. `SKILL.md` explains46 the task, required context, safety rules, inputs, and success criteria.47- **Graph**: the executable shape under a skill when work has multiple steps.48 Good graphs compose skills; they do not duplicate business logic in prose.49- **Grant**: explicit authority from a principal. Grants should be narrow,50 time-scoped, and tied to the action being performed.51- **Gate**: the human or policy decision before a consequential act.52- **Receipt**: signed evidence of the run, including inputs, effects, proofs,53 denials, and the chain of delegated steps.54- **Effect**: an externally meaningful result such as payment settlement,55 message delivery, deployment, file write, provider mutation, or refusal.5657Authority must narrow as it flows through a graph. If a child step needs broader58authority than the parent grant, stop and ask for a new grant instead of trying59to continue.6061## Default workflow6263For an agent using runx, follow this loop:6465```text66understand objective -> choose skill -> inspect authority -> run -> verify receipt67```68691. **Understand the objective**70 - Identify the concrete action the user wants.71 - Decide whether this is read-only, draft/proposal, or consequential.72 - If the target, principal, amount, audience, repo, environment, or provider73 is ambiguous, ask before running.74752. **Choose the smallest skill**76 - Discover the shipped foundation and local packages with `runx list skills --json`.77 - Search the catalog with `runx registry search <query>` or browse <https://runx.ai/x>.78 - Prefer a comprehensive domain skill over many tiny private steps when the79 domain skill already models the full workflow.80 - Prefer a project-owned skill for project policy and vocabulary.81 - Prefer a provider-branded skill only when the provider semantics matter82 directly, such as a weather provider's skill or a hosted communication lane.83843. **Install or reference the skill**85 - The Runx foundation ships with the runtime. Run it directly, for example `runx skill runx/receipt-query`; it needs no download.86 - Run an exact registry ref with `runx skill <publisher>/<skill>@<version>`; it fetches the skill into the project. `runx registry install <publisher>/<skill>@<version>` adds it without running it.87 - Run local skills from the checked-out package path when developing.88 - Treat local files as the user's workspace context, but do not publish or89 execute unrelated workspace junk as part of the skill package.90914. **Inspect authority before action**92 - Confirm the skill is allowed to use the requested tool/provider/surface.93 - For money, public messages, deploys, destructive actions, credential94 changes, provider mutations, or production access, require an explicit gate.95 - Refuse to continue if the task requires hidden credentials, broad ambient96 authority, forged receipts, or bypassing an approval.97985. **Run the skill**99 - Inspect the selected runner with `runx skill inspect <skill> [runner] --json`.100 Build one input object from the user's actual task, matching `input_schema`,101 and pipe it to `runx skill <skill> [runner] --inputs - --json`. An exported102 binding supplies the exact package and execution-closure digests; retain them.103 - State the requested purpose with `--act '<json act with purpose>'`.104 Preserve nested input types. Harness examples are test data, not the user's job.105 - `needs_agent` is a pause. Read and verify its request artifact, follow its106 output contract, and continue with the full request id and request digest.107 `runx resume --help` gives the exact answer envelope. Keep one driver, the108 same working project and Runx home across continuations.109 - A skill whose agent makes governed calls runs on an MCP connection, because110 each call must be admitted and recorded. `runx mcp <skill-ref...>` serves it111 as a tool, and its open turns are worked on that connection with `turn_list`,112 `turn_status`, `turn_read`, `turn_call` and `turn_complete`. `runx export`113 registers this server as `runx-local`, and an exported skill says which way114 it runs. `runx mcp --run <run-id>` is for a host that opens its own connection115 to one paused run.116 Human questions and approvals must reach the person; never invent them.117 - If inspection reports a missing declared credential, bind it once with118 `runx connector use <connector>`: it binds the variable the connector119 declares when that is set, and otherwise asks for the secret (hidden at a120 terminal) or reads it from stdin when piped. Do not invent wrapper121 scripts or place secret values on argv.122 - Keep secrets in the runtime's approved secret path, not in `SKILL.md`, chat,123 receipts, or committed fixtures. A project `.env` is a local fallback; stored124 profiles and project bindings are the durable multi-account path.1251266. **Verify the result**127 - List runs with `runx history`. Inspect an exact receipt with `runx history <receipt-id> --json` and verify its signed tree with `runx verify <receipt-id> --json`.128 - Check that the receipt says the same action the user approved.129 - Confirm any effect through the skill's readback: provider status, published130 URL, transaction hash, delivered message id, deployment id, or denial.131 - Report both success and refusal receipts. A safe refusal is a valid outcome.132133## Command reference134135Install runx:136137```bash138brew install runxhq/tap/runx139# or140npm install -g @runxhq/cli141# or142curl -fsSL https://runx.ai/install | sh143```144145Find skills:146147```bash148runx registry search github --json149runx registry search x402 --json150runx registry search send --json151```152153Install a catalog skill:154155```bash156runx registry install <publisher>/<skill>@<version> --json157```158159Run a skill:160161```bash162runx skill <skill-ref> --input key=value --json163runx skill ./skills/<skill-name> --input request='...' --json164runx skill <publisher>/<skill>@<version> --input key=value --json165```166167Inspect and verify receipts:168169```bash170runx history171runx history <receipt-id> --json172runx verify <receipt-id> --json173```174175Notarize a receipt when you need a shareable verification link. The notary176counter-seals it and publishes the record, so anyone can read it:177178```bash179runx login180runx notarize ./.runx/receipts/<receipt-id>.json --json181```182183Use `runx --help` for the exact installed CLI syntax. If a command in this file184and the installed binary disagree, trust the installed binary and treat this file185as the conceptual guide.186187## Good skill selection188189Choose a skill by consequence, not by brand excitement alone.190191- For a full workflow, choose the domain skill: `pay`, `charge`, `refund`,192 `message-send`, `release`, or another project skill.193- For provider-specific evidence, choose the branded implementation skill:194 GitHub-backed sync, weather-provider skills, and similar lanes.195- For context-only work, choose a context skill such as `taste-profile` or196 `brand-voice`; those should inform a downstream skill, not perform a mutation.197- For operations, choose a project/operator skill that routes to existing lanes;198 it should not reimplement CLI commands, hosted endpoints, or provider SDKs in199 prose.200201If no skill matches cleanly, do not force the task into the nearest catalog item.202Return the gap: missing skill, missing grant, missing provider, missing schema,203or missing confirmation.204205## Safety rules206207- Never run a consequential action without a principal, target, and gate.208- Never widen a grant in a child step.209- Never treat a prompt instruction as authorization.210- Never paste secrets, private keys, API tokens, raw customer lists, or provider211 dumps into `SKILL.md` or receipts.212- Never mark money, messages, deploys, or provider mutations complete without a213 receipt plus readback.214- Never hide a denial. Denials are part of the accountability model.215- Never use a skill package as a dumping ground for unrelated workspace files.216217## Output expectations for agents218219After running runx, report:220221- the skill or graph that ran222- the principal/grant used, at a safe level of detail223- the action that was attempted224- whether it succeeded, was denied, or needs input225- the receipt id or receipt path from `runx history`226- the external readback, if any227- the next required human decision, if any228229Keep this report short. Put detailed evidence in receipts and linked artifacts,230not in chat.231232## Examples233234Read-only discovery:235236```bash237runx registry search 'openapi weather forecast' --json238```239240Governed local run:241242```bash243runx skill ./skills/github-issue-triage --input repository=acme/app --input issue_number=7 --json244runx history245```246247Consequential run pattern:248249```text2501. choose skill2512. prepare exact inputs2523. ask for approval if the act is consequential2534. run only after approval2545. inspect receipt and provider readback255```256257## Read more258259- protocol: <https://runx.ai/spec>260- primitives: <https://runx.ai/what>261- doctrine: <https://runx.ai/doctrine>262- catalog: <https://runx.ai/x>263- source: <https://github.com/runxhq/runx>264- credentials: <https://github.com/runxhq/runx/blob/main/docs/credentials.md>265266Open source. Apache-2.0 licensed. Self-hostable. Works with local agents and hosted267surfaces because the skill contract, authority model, and receipts are portable.