runx

Files (200)

• .gitattributes
• dependabot.yml · .github/
• ci.yml · .github/workflows/
• frantic-github-thread-sync.yml · .github/workflows/
• publish-runx-py.yml · .github/workflows/
• release.yml · .github/workflows/
• secret-scan.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/
• X.yaml · bindings/nilstate/icey-server-operator/
• binding.json · bindings/nilstate/icey-server-operator/
• Cargo.lock · crates/
• Cargo.toml · crates/
• README.md · crates/
• deny.toml · crates/
• Cargo.toml · crates/runx-cli/
• README.md · crates/runx-cli/
• add.rs · crates/runx-cli/src/
• cli_args.rs · crates/runx-cli/src/
• cli_error.rs · crates/runx-cli/src/
• cli_io.rs · crates/runx-cli/src/
• command_spec.rs · crates/runx-cli/src/
• catalog.rs · crates/runx-cli/src/command_spec/
• config.rs · crates/runx-cli/src/
• connect.rs · crates/runx-cli/src/
• plan.rs · crates/runx-cli/src/connect/
• credential.rs · crates/runx-cli/src/
• parser.rs · crates/runx-cli/src/credential/
• dev.rs · crates/runx-cli/src/
• doctor.rs · crates/runx-cli/src/
• export.rs · crates/runx-cli/src/
• managed.rs · crates/runx-cli/src/export/
• parser.rs · crates/runx-cli/src/export/
• report.rs · crates/runx-cli/src/export/
• shim.rs · crates/runx-cli/src/export/
• history.rs · crates/runx-cli/src/
• kernel.rs · crates/runx-cli/src/
• lib.rs · crates/runx-cli/src/
• list.rs · crates/runx-cli/src/
• login.rs · crates/runx-cli/src/
• login_tests.rs · crates/runx-cli/src/
• main.rs · crates/runx-cli/src/
• mcp.rs · crates/runx-cli/src/
• official_skills.rs · crates/runx-cli/src/
• parser.rs · crates/runx-cli/src/
• payment.rs · crates/runx-cli/src/
• policy.rs · crates/runx-cli/src/
• public_api.rs · crates/runx-cli/src/
• error.rs · crates/runx-cli/src/public_api/
• publish.rs · crates/runx-cli/src/
• …and 140 more

SKILL.md (first lines)

# 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**
   - 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**
   - Install catalog skills with `runx add <publisher>/<skill>@<version>` or run an exact registry ref with `runx skill <publisher>/<skill>@<version>`.
   - 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, configure it once with
     `runx credential set <provider> --from-stdin`; 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**
   - Inspect receipts with `runx history` or `runx history <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
```

Find skills:

```bash
runx registry search github --json
runx registry search x402 --json
runx registry search send --json
```

From ZachDreamZ/runx, MIT.

More from ZachDreamZ/runx