runx
"Governed runtime for agent skills: discover and install portable skills, run bounded skill workflows with explicit authority, and inspect signed receipts for what happened."
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 14 Nov 2026. Its scripts were only partly scanned.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/runxhq/runx with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/runxhq/runx'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/runxhq--runx)HTML
<a href="/listings/runxhq--runx"><img src="/api/listings/runxhq--runx/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
These steps run a script from the network that findsafeskills does not scan.
With your agent
Give your agent the [Runx operating manual](https://runx.ai/SKILL.md):
Set up Runx: https://runx.ai/SKILL.md
Then give it a bounded job. For example:
Use Runx to investigate where our organic visitors stop becoming active users. Use Search Console, GA4, and our saved PostHog activation funnel. Compare the last two complete 28-day periods. Bring back the evidence, three priorities, and a proposed content or product change. Stop before publishing or sending.
The agent can discover skills, inspect their inputs, bind the tools you choose, and work through the run's open turns. Missing accounts, evidence, or decisions remain explicit requests. [Native skill exports](docs/agent-skills.md) are also available for Claude Code and Codex.
From your terminal
Install the native CLI through npm:
npm install --global @runxhq/cli
Or use the standalone installer on macOS or Linux:
curl -fsSL https://runx.ai/install | sh
Run the smallest complete example. This needs Git and Node.js 20 or newer; it needs no Runx account, model, or provider key.
git clone --depth 1 https://github.com/runxhq/runx.git cd runx runx skill ./examples/hello-world --run-id first-run \ -i message="Hello, Runx." --json
Selected fields from the result:
{
"status": "sealed",
"outcome": "completed",
"run_id": "first-run",
"result": { "message": "Hello, Runx." },
"receipt_id": "sha256:…"
}Read the run, then verify the full receipt ID returned by the command:
runx history first-run --json runx verify <receipt-id> --json
The example executes a checked-in Node.js command. It exercises the same admission, execution, and signing path used by larger skills. The npm package distributes the native runtime; Node.js is needed here for the example script. See [Getting started](docs/getting-started.md) for the full walkthrough and [installation options](https://runx.ai/start) for platform packages.
Skills can come from a local directory, a URL, or the registry. Published skills keep their `publisher/name` identity; verified publishers' skills can also hold a short root name. Local packages take precedence when resolving a bare name. Use an exact version and digest when you need to reproduce someone else's run.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 266 lines · 1 finding marked
- ---
- name: runx
- description: "Governed runtime for agent skills: discover and install portable skills, run bounded skill workflows 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 workflow/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.
- - **Workflow**: the executable shape under a skill when work has multiple steps.
- Good workflows 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 workflow. 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**
- - Inspect the selected method with `runx skill inspect <skill>[#<method>] --json`.
- Build one input object from the user's actual task, matching `input_schema`,
- and pipe it to `runx skill <skill>[#<method>] --inputs - --json`. An exported
- binding supplies the exact package and closure digests; retain them.
- - State the requested purpose with `--act '<json act with purpose>'`.
- Preserve nested input types. Test 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`, and
- `call_cancel` cancels one call while it executes. `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.
- 6. **Verify the result**
- - List runs with `runx history`. Inspect an exact receipt, 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
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 142 on GitHub
- ```
- Find skills:
- ```bash
- runx registry search github --json
- runx registry search x402 --json
- runx registry search send --json
- ```
- Install a catalog skill:
- ```bash
- runx registry install <publisher>/<skill>@<version> --json
- ```
- Run a skill:
- ```bash
- 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:
- ```bash
- runx history
- 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:
- ```bash
- 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 workflow 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:
- ```bash
- runx registry search 'openapi weather forecast' --json
- ```
- Governed local run:
- ```bash
- runx skill ./skills/github-issue-triage --input repository=acme/app --input issue_number=7 --json
- runx history
- ```
- Consequential run pattern:
- ```text
- 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
- - protocol: <https://runx.ai/spec>
- - primitives: <https://runx.ai/what>
- - doctrine: <https://runx.ai/doctrine>
- - catalog: <https://runx.ai/x>
- - source: <https://github.com/runxhq/runx>
- - credentials: <https://github.com/runxhq/runx/blob/main/docs/credentials.md>
- 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.
README.md · README · 611 lines · 1 finding marked
- <h1 align="center">runx</h1>
- <p align="center"><strong>The governed runtime for agent skills</strong></p>
- <p align="center">
- <a href="LICENSE"><img alt="License: Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-111111?style=flat-square"></a>
- <a href="https://www.npmjs.com/package/@runxhq/cli"><img alt="npm @runxhq/cli" src="https://img.shields.io/npm/v/@runxhq/cli?style=flat-square&color=f97316&label=%40runxhq%2Fcli"></a>
- <a href="https://github.com/runxhq/runx/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/runxhq/runx/actions/workflows/ci.yml/badge.svg"></a>
- <a href="https://runx.ai/x"><img alt="Skill catalog" src="https://img.shields.io/badge/catalog-runx.ai%2Fx-ff2e88?style=flat-square"></a>
- <a href="https://runx.ai/spec"><img alt="Specification" src="https://img.shields.io/badge/spec-read-7c5cff?style=flat-square"></a>
- </p>
- <p align="center">
- <a href="#quickstart">Quickstart</a> ·
- <a href="#skills-working-together">Workflows</a> ·
- <a href="#a-skill-carries-judgment">Write a skill</a> ·
- <a href="#what-a-receipt-proves">Receipts</a> ·
- <a href="#build-on-runx">Build on Runx</a>
- </p>
- ---
- ```text
- A skill is a URL.
- A workflow 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. It carries the method,
- the evidence to look for, the decisions to make, and the tools the work needs.
- Skills can call other skills, passing their results forward into a larger job.
- Runx makes that work executable. A research brief can become an outreach draft.
- A product launch can connect release work, documentation, and customer updates.
- Search and product analytics can inform the next change to your site. Across
- those handoffs, Runx admits calls under explicit authority, delivers credentials
- at the tool boundary, supervises execution, and seals a verifiable record.
- 
- **Your agent supplies the judgment. Runx owns the execution boundary.** Use the
- CLI, MCP, or a language client with the agent or orchestration framework you
- already use. Execution, state, and receipt signing run locally; hosted registry,
- credential custody, and notary services are optional. The runtime is written
- in Rust and licensed under Apache-2.0.
- ## Quickstart
- ### With your agent
- Give your agent the [Runx operating manual](https://runx.ai/SKILL.md):
- ```text
- Set up Runx: https://runx.ai/SKILL.md
- ```
- Then give it a bounded job. For example:
- ```text
- Use Runx to investigate where our organic visitors stop becoming active users.
- Use Search Console, GA4, and our saved PostHog activation funnel. Compare the
- last two complete 28-day periods. Bring back the evidence, three priorities,
- and a proposed content or product change. Stop before publishing or sending.
- ```
- The agent can discover skills, inspect their inputs, bind the tools you choose,
- and work through the run's open turns. Missing accounts, evidence, or decisions
- remain explicit requests. [Native skill exports](docs/agent-skills.md) are also
- available for Claude Code and Codex.
- ### From your terminal
- Install the native CLI through npm:
- ```bash
- npm install --global @runxhq/cli
- ```
- Or use the standalone installer on macOS or Linux:
- ```bash
- curl -fsSL https://runx.ai/install | sh
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 84 on GitHub
- ```
- Run the smallest complete example. This needs Git and Node.js 20 or newer;
- it needs no Runx account, model, or provider key.
- ```bash
- git clone --depth 1 https://github.com/runxhq/runx.git
- cd runx
- runx skill ./examples/hello-world --run-id first-run \
- -i message="Hello, Runx." --json
- ```
- Selected fields from the result:
- ```json
- {
- "status": "sealed",
- "outcome": "completed",
- "run_id": "first-run",
- "result": { "message": "Hello, Runx." },
- "receipt_id": "sha256:…"
- }
- ```
- Read the run, then verify the full receipt ID returned by the command:
- ```bash
- runx history first-run --json
- runx verify <receipt-id> --json
- ```
- The example executes a checked-in Node.js command. It exercises the same
- admission, execution, and signing path used by larger skills. The npm package
- distributes the native runtime; Node.js is needed here for the example script.
- See [Getting started](docs/getting-started.md) for the full walkthrough and
- [installation options](https://runx.ai/start) for platform packages.
- Skills can come from a local directory, a URL, or the registry. Published skills
- keep their `publisher/name` identity; verified publishers' skills can also hold
- a short root name. Local packages take precedence when resolving a bare name.
- Use an exact version and digest when you need to reproduce someone else's run.
- ## Skills working together
- Skills pass useful work forward: matched facts, a source-backed brief, a
- validated draft, an exact action to approve, or a receipt from the last run.
- The next skill can use that result directly.
- These are compositions you can give an agent: Runx skills working with your
- repositories, provider skills, and connected accounts. Your agent or a
- project-owned workflow makes the handoffs, carrying the actual outputs into the
- next skill's inputs.
- ### Business ops: get the next release into customers' hands
- ```text
- We're launching team workspaces in Northstar. Use Runx to prepare the release,
- choose the customer audience, update the setup guide, draft the announcement,
- and coordinate the rollout with the team. Establish the activation baseline
- from workspace creation to the first teammate invited so we can measure adoption.
- Bring back the launch kit, blockers, and receipts. Ask before sending,
- publishing, or deploying.
- ```
- [`operations-review`](skills/operations-review/SKILL.md) reviews the release state and proposes
- the next launch actions. [`lead-enrichment`](skills/lead-enrichment/SKILL.md)
- organizes supplied customer facts to inform the audience choice; the operator
- supplies the actual audience and contact policy.
- [`release#prepare`](skills/release/SKILL.md) checks the project's release
- profile and produces the version-bound brief. The full `release` method owns
- approval, publication, and verification through the project's commands.
- [`content-package`](skills/content-package/SKILL.md) combines release facts
- and product documentation with `research` and `ghostwrite` to prepare the setup
- guide and announcement, then packages them for publication.
- [`message-send#plan`](skills/message-send/SKILL.md) binds the principal,
- audience, accepted content, and approval requirements. The calling agent can
- hand that plan to [Nitrosend](https://nitrosend.com/SKILL.md) or another email
- provider's skill for its review, approval, and delivery workflow. For a team
- update, `message-send#send` owns the Slack post and independent readback itself.
- [`product-analytics`](skills/product-analytics/SKILL.md) establishes the
- workspace-to-invitation baseline from supplied reports and compares later
- results under the same measurement definition.
- **What comes back:** a launch kit with release notes, a setup guide, the customer
- announcement, a team update, and an activation baseline—plus the blockers,
- decisions, and receipts needed to take it live and follow adoption afterward.
- ### Outreach: facts → fit → a useful first contact
- 
- [`lead-enrichment`](skills/lead-enrichment/SKILL.md) normalizes supplied facts
- about a confidently matched subject.
- [`lead-qualify`](skills/lead-qualify/SKILL.md) checks those facts against your
- ICP and keeps commercial fit separate from contact eligibility.
- [`cold-outreach`](skills/cold-outreach/SKILL.md) takes that context, supported
- research, and the exact recipient's suppression state to prepare one email.
- The draft can use [`brand-voice`](skills/brand-voice/SKILL.md) and
- [`taste-profile`](skills/taste-profile/SKILL.md) without allowing either to
- invent product claims. Inside `cold-outreach`, `ghostwrite#admit` validates the
- evidence and writing context before drafting; `ghostwrite#verify` checks the
- result's source bindings afterward. Missing eligibility, suppression, or an
- unsupported claim produces a hold.
- **What comes back:** the exact sender, recipient, subject, body, and a source
- binding for review. `message-send#plan` can take that accepted draft into a
- provider handoff. The selected email skill—Nitrosend or another provider—checks
- its own audience and sender requirements, obtains approval for the exact send,
- and reports the provider result. Choose a provider and delivery mode that permit
- the intended contact; commercial fit alone never grants that permission.
- Enrichment uses the evidence you supply; a provider lookup is a separate
- connector operation. The calling application retains outcomes for follow-up.
- A reply, opt-out, or changed eligibility changes what the next run may do.
- Try it with your agent: *“Use the supplied prospect research, our ICP, brand
- voice, and contact-policy decision to prepare one useful first-contact email.
- Show the facts behind it and hold any recipient with unresolved eligibility.”*
- ### Organic growth: connect discovery to activation
- 
- Each source answers a different question. Search Console shows how people find
- you. GA4 shows acquisition and behavior under the property's measurement model.
- Product analytics shows where a defined journey loses people or accounts
- after signup.
- [`google-search-console`](skills/google-search-console/SKILL.md) and
- [`google-analytics`](skills/google-analytics/SKILL.md) return normalized
- evidence with source digests and measurement caveats. The
- [`PostHog connector`](connectors/posthog/README.md) reads saved insights from
- your selected Cloud project and region; it preserves their query definitions
- and cached-result freshness.
- [`product-analytics`](skills/product-analytics/SKILL.md) consumes the supplied
- aggregate reports, calculates funnel and retention rates, and checks whether
- the comparison is meaningful.
- [`organic-growth`](skills/organic-growth/SKILL.md) combines search, analytics,
- site, and market evidence into priorities and a measurement plan. Product
- findings can join that evidence with their source reference and digest. For
- example, a page getting more clicks while its visitors fail to activate may
- need a clearer promise, a better onboarding path, or an instrumentation fix.
- **What comes back:** observations, hypotheses, ranked actions, source bindings,
- and a measurement plan. Content work can continue through `content-package`;
- code and instrumentation work can go through
- [`code-plan`](skills/code-plan/SKILL.md) and
- [`github-issue-to-pr`](skills/github-issue-to-pr/SKILL.md) in the owning repository. The next
- analysis reuses comparable windows and definitions. Missing or stale reports
- remain measurement gaps.
- ### Run the local workflow proofs
- From this checkout:
- ```bash
- # Research → draft → channel package → publication handoff
- runx test skills/content-package/tests/composes-in-workflow.yaml
- # A specific outreach draft with supplied evidence and writing context
- runx test skills/cold-outreach/tests/prepares-approved-context-email.yaml
- # Search + analytics + site evidence → growth priorities
- runx test skills/organic-growth/tests/composes-in-workflow.yaml
- # Defined product funnel → rates and source-bound recommendations
- runx test skills/product-analytics/tests/composes-in-workflow.yaml
- # Exact Slack post → approval → provider response → independent readback
- runx test skills/message-send/tests/post-default-notifies-and-verifies.yaml
- ```
- These are fixture-backed executions, with no live account reads or sends. Live
- work uses your provider bindings and actual evidence. Browse the
- [skill catalog](https://runx.ai/x) for more workflows, or the
- [demo gallery](docs/demos.md) for local execution, state, and loop examples.
- ## A skill carries judgment
- `SKILL.md` is the capability's operating manual. It explains when to use the
- skill, what evidence matters, how to make the decisions, when to stop, and what
- completion means. It remains readable and useful on its own.
- ```markdown
- ---
- name: hello-world
- description: Echo a message through a checked-in command.
- ---
- # Hello World
- Print the supplied message so the caller can inspect the local execution
- and its signed receipt.
- ```
- When the work needs executable steps, typed inputs and outputs, authority,
- artifacts, or test cases, the package also carries a `run.yaml`:
- ```yaml
- version: "0.1.1"
- minimum_runx: 0.12.0
- catalog:
- visibility: public
- methods:
- default:
- inputs:
- message:
- type: string
- description: Message to print from the example skill.
- steps:
- - id: default
- tool: {command: node, args: [run.mjs]}
- inputs:
- message: $input.message
- outputs:
- message: {type: string}
- ```
- This is the execution shape of [`examples/hello-world`](examples/hello-world).
- Its checked-in package also includes the command and test case.
- | Part | Responsibility |
- | --- | --- |
- | `SKILL.md` and references | Expertise, procedure, judgment, recovery, and completion criteria. |
- | `run.yaml` | Executable methods, typed contracts, declared capabilities, authority, and test cases. |
- | Domain modules | Deterministic computation specific to the skill. |
- | Runx | Provider transport, filesystem and process access, credential delivery, execution state, and receipts. |
- Runx binds the manual and closure by digest. An acting agent receives
- the invoked skill's full manual; declared adjacent skills contribute bounded
- summaries until invoked. A workflow can also supply a skill as explicit
- `context.skills` on an agent step—for example, a writing rubric. Context informs
- judgment; permission comes from admission.
- ## Workflows make acts composable
- A method can combine five step kinds:
- | Step | Use it for |
- | --- | --- |
- | `agent` | Judgment under the skill's manual and an explicit allowance of calls. |
- | `tool` | A native capability, deterministic computation, or declared process command. |
- | `operation` | A typed connector call to an external provider. |
- | `ask` | A question or decision the run needs before it can continue. |
- | `skill` | Another skill's method, with explicit inputs and outputs. |
- A method's steps make the dataflow visible. The `hello-workflow` example's
- run.yaml runs one skill twice:
- ```yaml
- minimum_runx: 0.12.0
- methods:
- default:
- steps:
- - id: first
- skill: ../hello-world
- inputs:
- message: Hello from the first skill.
- - id: second
- skill: ../hello-world
- inputs:
- message: $steps.first.message
- ```
- The second step consumes the first step's typed output, and the method's
- receipt links their receipts. The same mechanism lets `content-package` pass a
- research packet into `ghostwrite`, then pass the validated draft into its
- packaging and handoff methods. Inspect its
- [actual methods](skills/content-package/run.yaml).
- Use an agent turn for work that needs judgment. Use a workflow when phases,
- branches, guards, or approval boundaries must be part of the execution
- contract. Required side effects belong in explicit execution steps, where
- Runx can record the attempt and result. An agent's completion text cannot
- substitute for a provider operation.
- Workflows and agent turns can both call skills. A host can pass an existing packet
- artifact into a later call; Runx checks its content digest and input schema.
- This is how a useful result becomes an input to more work without flattening
- its provenance into prose.
- [Compose skills](docs/composing-skills.md) ·
- [Execution profile reference](docs/reference.md#skill-and-execution-profile)
- ## Work can outlive an agent turn
- By default, an agent step yields work to the calling agent. Runx returns the
- manual, typed request, and allowed calls. Your host can work the turn through
- MCP, provide its result, and continue the same run. The optional
- `--drive` mode delegates those turns to a configured model provider.
- ```bash
- # Inspect a running, paused, or completed run
- runx history <run-id> --json
- # Serve the paused run's agent turns over MCP
- runx mcp --run <run-id>
- # Continue with answers to the run's exact pending requests
- runx resume <run-id> answers.json --json
- ```
- The run records pending requests and completed calls. Independent read calls
- can run concurrently; effects are serialized within the run. A retry reuses
- the call's identity, and an uncertain external result remains explicit for
- reconciliation. Resume checks the package and closure so a changed
- skill cannot silently continue an old run.
- Agent answers and human approvals have separate fields. Each decision binds to
- the digest of the request it answers. The host is responsible for obtaining
- the human decision; putting a JSON value in an approval field is a host
- assertion, not proof of a person's identity.
- For recurring operations, the outer host owns scheduling and stop policy.
- Each iteration can read prior receipts and durable state, submit a bounded
- run, and retain the result for the next iteration. See the
- [loop example](examples/loop-orchestration) and
- [continuation contract](docs/reference.md#local-cli).
- ## Connect tools without handing secrets to skills
- Skills declare the connector operations they need. Connectors declare typed
- requests, scopes, credential requirements, and readback behavior. You choose
- the account and binding: a local credential, a supported existing session, or
- an optional hosted connection.
- For example, install web search and bind it to your Exa account:
- ```bash
- runx registry install runx/web-search
- runx connector use exa
- runx skill runx/web-search -i query="Agent skill interoperability" --json
- ```
- If the connector's declared credential variable is set, `connector use` binds
- to it; otherwise it asks for the key. For supported sessions, such as an
- existing `gh` sign-in:
- ```bash
- runx connector use github --session --scope repo.read
- ```
- The kernel delivers credentials only at the admitted operation's transport
- boundary. Skills name operations and supply typed inputs. Secret material
- stays out of their instructions, model context, and receipts.
- One skill can work with different compatible providers. One connector binding
- can serve several skills. Using hosted credential custody leaves the calling
- operator and its state local unless you explicitly select a hosted service.
- Connector names identify the capability provider: `github`, `posthog`,
- `google/analytics`, or `google/search-console`. A skill binding a connector
- outside its own plugin pins the manifest digest; the closure binds
- the operations it will actually use.
- [Credential setup](docs/credentials.md) ·
- [Connector catalog](https://runx.ai/connectors) ·
- [Connector manifests](connectors/)
- ## Authority follows the work
- Every governed execution follows the same boundary:
- ```text
- Admit → Resolve grant → Deliver credentials → Execute → Seal
- ```
- Authority is checked where a call executes. Child calls remain within the
- parent's grant; naming another skill or describing an action in a prompt does
- not create permission. An operation that requires approval pauses with the
- exact request for the host to present to the human.
- The execution lanes have deliberate boundaries:
- - **Deterministic modules** perform JSON-to-JSON domain computation without
- ambient filesystem, network, process, environment, clock, or random access.
- - **Native capabilities** own reusable runtime mechanics and their admission
- checks, including file access, processes, artifacts, and data operations.
- - **Connector operations** execute declared HTTP, MCP, or Connect calls under
- typed authority and effect contracts.
- - **Process tools** are trusted local executables. Runx controls their argv,
- working directory, delivered environment, credentials, and supervision.
- They execute with the host's OS permissions; this is not portable OS isolation.
- These guarantees cover work executed through Runx. The surrounding agent or
- application owns its other tools, authentication of human decisions, and host
- isolation.
- [Authority and security proof](docs/security-authority-proof.md) ·
- [Security policy](SECURITY.md)
- ## What a receipt proves
- A receipt answers the questions that matter after the agent has moved on:
- | Question | Evidence |
- | --- | --- |
- | What ran? | Skill identity, source and execution digests, and method metadata. |
- | Who or what admitted it? | Actor references, grant references, and execution terms. |
- | What was allowed? | Scopes, resolved grants, and approval decisions. |
- | What happened? | Acts, output references and how each ended. |
- | How did the work connect? | Linked child receipts and artifact provenance. |
- | Can I check it later? | A content-addressed ID, canonical digest, and signature. |
- Runx signs receipts with Ed25519. On first use, an unconfigured Runx home
- creates its own local signing key. `runx history` inspects the record;
- `runx verify` checks its signature and linked receipt tree.
- A valid signature establishes integrity against a trusted signer. Read the
- receipt's outcome as well: a sealed refusal or failed run is still sealed.
- A local content draft proves preparation; provider readback establishes the
- external result. A receipt from another home or hosted issuer requires that
- issuer's trusted public key.
- Receipts carry references, decisions, hashes, and bounded observations.
- Raw credentials and unchecked private provider bodies do not belong in proof.
- The result payload and the signed receipt have separate jobs: the result is
- what the next caller uses; the receipt records how the work was admitted and
- what execution established.
- Read the [receipt schema](schemas/receipt.schema.json), inspect a
- [sealed fixture](fixtures/receipt-verify/valid-production/receipt.json), or
- use the [standalone verifier](tools/verify/verify.mjs) to check proof outside
- the execution runtime.
- ## Author, test, and publish
- Keep a skill in your project, adapt an existing package, or publish it for
- others to compose. Start an authoring run with:
- ```bash
- runx skill runx/skill-build#build \
- -i objective="Review a release and prepare its customer announcement" \
- -i target_dir=skills/launch-review
- ```
- Your agent works the authoring turns; the package is written after
- validation. Without a managed agent, the run returns the pending work and
- resume instructions.
- A finished package should include test cases for its successful path,
- refusals, and composition with other skills. The test replays declared
- inputs and agent/provider responses so those contracts can be checked locally.
- ```bash
- runx test ./skills/launch-review
- runx login --for publish
- runx registry publish ./skills/launch-review
- ```
- Hosted publication reconstructs the submitted package, reruns its test,
- and stores immutable package digests. Local test results prove the cases
- they exercise; live integration claims need evidence from the actual provider
- path too.
- [Authoring reference](docs/reference.md#standalone-skill-packages) ·
- [Skill quality standard](docs/skill-quality-standard.md) ·
- [Publishing](docs/publishing.md)
- ## Build on Runx
- The CLI, MCP server, and language clients use the same Rust execution path.
- An application can start a skill, expose its open turns to a model, route
- human decisions, resume the run, and inspect its receipts.
- | Surface | Entry point |
- | --- | --- |
- | CLI | `runx skill <skill-ref>[#<method>] -i key=value --json` — [reference](docs/reference.md#local-cli). |
- | MCP | `runx mcp <skill-ref>` to expose a skill; `runx mcp --run <run-id>` to work an existing run. |
- | TypeScript / Node.js | [`@runxhq/client`](packages/client/README.md), with explicit workspace and environment configuration. |
- | Python | [Python SDK](packages/sdk-python/README.md). |
- | Contracts | [Schemas](schemas/) and the [public specification](https://runx.ai/spec). |
- MCP exposes a turn's allowed calls as typed tools. The host owns the model
- conversation; Runx admits and records the calls. You can integrate a single
- skill or build a product around long-lived runs without introducing another
- execution implementation.
- <details>
- <summary><strong>Inside the runtime: which layer owns what</strong></summary>
- | Layer | Owner |
- | --- | --- |
- | Portable wire contracts | `runx-contracts` |
- | Pure policy, authority, and state transitions | `runx-core` |
- | Package parsing and validated package representation | `runx-parser` |
- | Canonical receipts, hashing, signatures, and verification | `runx-receipts` |
- | Execution, capabilities, processes, adapters, and effects | `runx-runtime` |
- | Argument parsing and presentation | `runx-cli` |
- | Language clients and extension protocols | `packages/` |
- | Operator knowledge and domain computation | `skills/` and product-owned packages |
- The [system architecture](docs/architecture/runx-system.md) defines these
- ownership boundaries. SDKs, exported agent skills, schemas, and catalog views
- consume the same contracts.
- </details>
- ## Contribute
- Runx is in active development. Start with a concrete workflow, a reproducible
- execution problem, a connector contract, or a skill with useful test cases.
- The [contributor guide](CONTRIBUTING.md) covers setup, focused checks, and
- sign-off requirements.
- Build the native CLI from this checkout:
- ```bash
- cargo build --manifest-path crates/Cargo.toml -p runx-cli
- crates/target/debug/runx test examples/hello-world
- ```
- [Reference](docs/reference.md) · [Demos](docs/demos.md) ·
- [Releases](https://github.com/runxhq/runx/releases) ·
- [Open an issue](https://github.com/runxhq/runx/issues)
- ---
- <p align="center"><sub>Built in Rust · Apache-2.0 · <a href="https://runx.ai">runx.ai</a></sub></p>
scripts/install.ps1 · Bundled script · 56 lines · 1 finding marked
- # runx installer for Windows.
- #
- # irm runx.ai/install.ps1 | iex
- Note: Runs a downloaded PowerShell script (iex / Invoke-Expression)
- Line 3 on GitHub
- #
- # Downloads the prebuilt binary from the GitHub Release, verifies its sha256, and
- # installs it. Honors $env:RUNX_VERSION (default: latest cli-v* release) and
- # $env:RUNX_INSTALL_DIR (default: %LOCALAPPDATA%\runx\bin).
- $ErrorActionPreference = "Stop"
- $repo = "runxhq/runx"
- $arch = $env:PROCESSOR_ARCHITECTURE
- if ($arch -ne "AMD64") { throw "unsupported architecture: $arch (only x64 is published)" }
- $target = "x86_64-pc-windows-msvc"
- $version = $env:RUNX_VERSION
- if (-not $version) {
- Write-Host "runx: resolving latest release..."
- $releases = Invoke-RestMethod "https://api.github.com/repos/$repo/releases"
- $tag = ($releases | Where-Object { $_.tag_name -like "cli-v*" } | Select-Object -First 1).tag_name
- if (-not $tag) { throw "could not resolve latest cli-v* release; set `$env:RUNX_VERSION" }
- $version = $tag
- }
- $version = $version -replace '^cli-v','' -replace '^v',''
- $archive = "runx-$version-$target.zip"
- $base = if ($env:RUNX_BASE_URL) { $env:RUNX_BASE_URL } else { "https://github.com/$repo/releases/download/cli-v$version" }
- $tmp = Join-Path $env:TEMP ("runx-" + [guid]::NewGuid())
- New-Item -ItemType Directory -Path $tmp | Out-Null
- try {
- Write-Host "runx: downloading $version ($target)"
- Invoke-WebRequest "$base/$archive" -OutFile "$tmp\$archive"
- try {
- Invoke-WebRequest "$base/$archive.sha256" -OutFile "$tmp\$archive.sha256"
- $expected = (Get-Content "$tmp\$archive.sha256").Split(" ")[0]
- $actual = (Get-FileHash "$tmp\$archive" -Algorithm SHA256).Hash.ToLower()
- if ($expected -ne $actual) { throw "checksum mismatch (expected $expected, got $actual)" }
- Write-Host "runx: checksum verified"
- } catch { Write-Warning "runx: skipping checksum verification ($_)" }
- Expand-Archive "$tmp\$archive" -DestinationPath $tmp -Force
- $dir = $env:RUNX_INSTALL_DIR
- if (-not $dir) { $dir = Join-Path $env:LOCALAPPDATA "runx\bin" }
- New-Item -ItemType Directory -Path $dir -Force | Out-Null
- Copy-Item "$tmp\runx-$version-$target\runx.exe" "$dir\runx.exe" -Force
- Copy-Item "$tmp\runx-$version-$target\runx-js-worker.exe" "$dir\runx-js-worker.exe" -Force
- Write-Host "runx: installed to $dir\runx.exe"
- $userPath = [Environment]::GetEnvironmentVariable("Path", "User")
- if ($userPath -notlike "*$dir*") {
- [Environment]::SetEnvironmentVariable("Path", "$userPath;$dir", "User")
- Write-Host "runx: added $dir to your user PATH (restart your shell)"
- }
- } finally {
- Remove-Item -Recurse -Force $tmp -ErrorAction SilentlyContinue
- }
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.