runx

Files (200)

• .gitattributes
• action.yml · .github/actions/setup-runx/
• dependabot.yml · .github/
• ci.yml · .github/workflows/
• publish-runx-py.yml · .github/workflows/
• publish-typescript-packages.yml · .github/workflows/
• release.yml · .github/workflows/
• runtime-quality.yml · .github/workflows/
• .gitignore
• AGENTS.md
• CLAUDE.md
• CODE_OF_CONDUCT.md
• CONTRIBUTING.md
• CONVENTIONS.md
• LICENSE
• NOTICE
• README.md
• SECURITY.md
• SKILL.md
• README.md · bindings/
• binding.json · bindings/nilstate/icey-server-operator/
• run.yaml · bindings/nilstate/icey-server-operator/
• README.md · connectors/apollo/
• connector.yaml · connectors/apollo/
• mark.svg · connectors/apollo/
• connector.yaml · connectors/artifact/
• mark.svg · connectors/artifact/
• connector.yaml · connectors/aws/
• mark.svg · connectors/aws/
• connector.yaml · connectors/coinbase/cdp/
• mark.svg · connectors/coinbase/cdp/
• README.md · connectors/exa/
• connector.yaml · connectors/exa/
• mark.svg · connectors/exa/
• connector.yaml · connectors/github/
• mark.svg · connectors/github/
• manifest.json · connectors/github/tools/git/push/
• push.sh · connectors/github/tools/git/push/
• connector.yaml · connectors/google/analytics/
• mark.svg · connectors/google/analytics/
• connector.yaml · connectors/google/calendar/
• mark.svg · connectors/google/calendar/
• connector.yaml · connectors/google/search-console/
• mark.svg · connectors/google/search-console/
• README.md · connectors/google/sheets/
• connector.yaml · connectors/google/sheets/
• mark.svg · connectors/google/sheets/
• README.md · connectors/linear/
• connector.yaml · connectors/linear/
• mark.svg · connectors/linear/
• NOTICE · connectors/link/
• README.md · connectors/link/
• connector.yaml · connectors/link/
• mark.svg · connectors/link/
• connector.test.mjs · connectors/link/tests/
• native-payment.test.mjs · connectors/link/tests/
• payment.test.mjs · connectors/link/tests/
• link.mjs · connectors/link/tools/link/payment/
• manifest.json · connectors/link/tools/link/payment/
• connector.yaml · connectors/moltbook/
• …and 140 more

SKILL.md (first lines)

# 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 a weather provider's skill 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:

```bash
brew install runxhq/tap/runx
# or
npm install -g @runxhq/cli
# or
curl -fsSL https://runx.ai/install | sh
```

From runxhq/runx, Apache-2.0.

More from runxhq/runx