runxBLOCK

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

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

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: runx
description: "Governed runtime for agent skills: discover and install portable skills, run bounded skill graphs with explicit authority, and inspect signed receipts for what happened."
metadata:
  tags: runtime, meta
license: Apache-2.0
---

# runx

References: [spec](https://runx.ai/spec), [catalog](https://runx.ai/x),
[doctrine](https://runx.ai/doctrine), [overview](https://runx.ai/what),
[source](https://github.com/runxhq/runx).

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:

1. the skill being run is explicit;
2. the authority granted to it is bounded;
3. consequential actions pass through a gate;
4. 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:

```text
understand objective -> choose skill -> inspect authority -> run -> verify receipt
```

1. **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.

2. **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 `x402-pay`, `stripe-pay`, or a hosted communication lane.

3. **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.

4. **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.

5. **Run the skill**
   - Use `runx skill <skill> --input ... --json` or the skill's documented runner.
   - Provide structured inputs when possible. Do not bury critical values only
     in prose.
   - 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.

6. **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:

```bas

BLOCKgrade F · trust 34/100 Do not install this without reading the findings. The audit found something that could harm you or your machine.

What the source does

Filesystem

declared (11 observation(s))

Network

declared (10 observation(s))

Shell

declared (2 observation(s))

Dependencies

not all pinned

Secrets in source

found

Findings (25)

If a page cap makes an event window partial, narrow the requested window into disjoint smaller windows, read them under the same selected calendar authority, and merge only complete slices by event in

payload.rs

x402-v2-payment-payload.schema.json

| ".netrc"

| "id_rsa"

| "id_ed25519"

"id_ed25519",

|| normalized == "metadata.google.internal"

"http://169.254.169.254",

"http://metadata.google.internal",

"http://127.0.0.1:18081/v1/chat/completions",

"http://127.0.0.1:18081/v1/chat/completions"

Sessions::default().open(&transport, "https://127.0.0.1/mcp", None, &BTreeMap::new());

let secret = "never-print-this-secret";

let secret = "never-debug-this-secret";

let secret = "ghs_observation_secret_must_not_leak";

: jsonResponse({ token: "anonymous-pull-token" });

const SECRET: &str = "ghs_cli_local_provision_secret_value";

let secret = "ghs_observation_secret_must_not_leak";

curl -fsSL https://runx.ai/install | sh

official-payment-payload.json

let docs = include_str!("../../../../docs/cli-exit-codes.md");

const CORPUS_ROOT: &str = concat!(env!("CARGO_MANIFEST_DIR"), "/../../fixtures/receipt-verify");

include_str!("../../../fixtures/registry/install/echo-SKILL.md"),

include_str!("../../../fixtures/registry/install/echo-run.yaml"),

Gates applied: critical_finding, no_behavioural_pass, undeclared_transfer.