Skip to content
Back to search

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/runxhq--runx/badge.svg)](/listings/runxhq--runx)

HTML

<a href="/listings/runxhq--runx"><img src="/api/listings/runxhq--runx/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

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
  1. ---
  2. name: runx
  3. 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."
  4. metadata:
  5. tags: runtime, meta
  6. license: Apache-2.0
  7. ---
  8. # runx
  9. References: [spec](https://runx.ai/spec), [catalog](https://runx.ai/x),
  10. [doctrine](https://runx.ai/doctrine), [overview](https://runx.ai/what),
  11. [source](https://github.com/runxhq/runx).
  12. runx is the governed runtime for agent skills. Use it when an agent needs to do
  13. real work through a portable skill while preserving four properties:
  14. 1. the skill being run is explicit;
  15. 2. the authority granted to it is bounded;
  16. 3. consequential actions pass through a gate;
  17. 4. the run leaves a signed receipt that can be inspected later.
  18. A runx skill is not just a prompt. It is a small, portable package with a
  19. `SKILL.md` contract, optional workflow/config files, and enough procedural context
  20. for an agent to execute deliberately instead of improvising hidden side effects.
  21. ## When to use runx
  22. Use runx when the task involves one or more of these:
  23. - running a third-party or project-owned skill from a catalog, repo, or local path
  24. - chaining multiple skill steps into a bounded workflow
  25. - touching money, credentials, deployments, public messages, production systems,
  26. customer data, or other consequential surfaces
  27. - proving what happened after an agent acted
  28. - giving another agent context it can execute without copying private runbooks
  29. - comparing a proposed action with the authority actually granted
  30. Do not use runx for a normal local edit that does not need delegation,
  31. authority, a receipt, or a reusable skill package.
  32. ## Core vocabulary
  33. - **Skill**: the portable contract an agent reads and runs. `SKILL.md` explains
  34. the task, required context, safety rules, inputs, and success criteria.
  35. - **Workflow**: the executable shape under a skill when work has multiple steps.
  36. Good workflows compose skills; they do not duplicate business logic in prose.
  37. - **Grant**: explicit authority from a principal. Grants should be narrow,
  38. time-scoped, and tied to the action being performed.
  39. - **Gate**: the human or policy decision before a consequential act.
  40. - **Receipt**: signed evidence of the run, including inputs, effects, proofs,
  41. denials, and the chain of delegated steps.
  42. - **Effect**: an externally meaningful result such as payment settlement,
  43. message delivery, deployment, file write, provider mutation, or refusal.
  44. Authority must narrow as it flows through a workflow. If a child step needs broader
  45. authority than the parent grant, stop and ask for a new grant instead of trying
  46. to continue.
  47. ## Default workflow
  48. For an agent using runx, follow this loop:
  49. ```text
  50. understand objective -> choose skill -> inspect authority -> run -> verify receipt
  51. ```
  52. 1. **Understand the objective**
  53. - Identify the concrete action the user wants.
  54. - Decide whether this is read-only, draft/proposal, or consequential.
  55. - If the target, principal, amount, audience, repo, environment, or provider
  56. is ambiguous, ask before running.
  57. 2. **Choose the smallest skill**
  58. - Discover the shipped foundation and local packages with `runx list skills --json`.
  59. - Search the catalog with `runx registry search <query>` or browse <https://runx.ai/x>.
  60. - Prefer a comprehensive domain skill over many tiny private steps when the
  61. domain skill already models the full workflow.
  62. - Prefer a project-owned skill for project policy and vocabulary.
  63. - Prefer a provider-branded skill only when the provider semantics matter
  64. directly, such as a weather provider's skill or a hosted communication lane.
  65. 3. **Install or reference the skill**
  66. - The Runx foundation ships with the runtime. Run it directly, for example `runx skill runx/receipt-query`; it needs no download.
  67. - 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.
  68. - Run local skills from the checked-out package path when developing.
  69. - Treat local files as the user's workspace context, but do not publish or
  70. execute unrelated workspace junk as part of the skill package.
  71. 4. **Inspect authority before action**
  72. - Confirm the skill is allowed to use the requested tool/provider/surface.
  73. - For money, public messages, deploys, destructive actions, credential
  74. changes, provider mutations, or production access, require an explicit gate.
  75. - Refuse to continue if the task requires hidden credentials, broad ambient
  76. authority, forged receipts, or bypassing an approval.
  77. 5. **Run the skill**
  78. - Inspect the selected method with `runx skill inspect <skill>[#<method>] --json`.
  79. Build one input object from the user's actual task, matching `input_schema`,
  80. and pipe it to `runx skill <skill>[#<method>] --inputs - --json`. An exported
  81. binding supplies the exact package and closure digests; retain them.
  82. - State the requested purpose with `--act '<json act with purpose>'`.
  83. Preserve nested input types. Test examples are test data, not the user's job.
  84. - `needs_agent` is a pause. Read and verify its request artifact, follow its
  85. output contract, and continue with the full request id and request digest.
  86. `runx resume --help` gives the exact answer envelope. Keep one driver, the
  87. same working project and Runx home across continuations.
  88. - A skill whose agent makes governed calls runs on an MCP connection, because
  89. each call must be admitted and recorded. `runx mcp <skill-ref...>` serves it
  90. as a tool, and its open turns are worked on that connection with `turn_list`,
  91. `turn_status`, `turn_read`, `turn_call` and `turn_complete`, and
  92. `call_cancel` cancels one call while it executes. `runx export`
  93. registers this server as `runx-local`, and an exported skill says which way
  94. it runs. `runx mcp --run <run-id>` is for a host that opens its own connection
  95. to one paused run.
  96. Human questions and approvals must reach the person; never invent them.
  97. - If inspection reports a missing declared credential, bind it once with
  98. `runx connector use <connector>`: it binds the variable the connector
  99. declares when that is set, and otherwise asks for the secret (hidden at a
  100. terminal) or reads it from stdin when piped. Do not invent wrapper
  101. scripts or place secret values on argv.
  102. - Keep secrets in the runtime's approved secret path, not in `SKILL.md`, chat,
  103. receipts, or committed fixtures. A project `.env` is a local fallback; stored
  104. profiles and project bindings are the durable multi-account path.
  105. 6. **Verify the result**
  106. - List runs with `runx history`. Inspect an exact receipt, and verify its signed tree, with `runx verify <receipt-id> --json`.
  107. - Check that the receipt says the same action the user approved.
  108. - Confirm any effect through the skill's readback: provider status, published
  109. URL, transaction hash, delivered message id, deployment id, or denial.
  110. - Report both success and refusal receipts. A safe refusal is a valid outcome.
  111. ## Command reference
  112. Install runx:
  113. ```bash
  114. brew install runxhq/tap/runx
  115. # or
  116. npm install -g @runxhq/cli
  117. # or
  118. curl -fsSL https://runx.ai/install | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 142 on GitHub
  119. ```
  120. Find skills:
  121. ```bash
  122. runx registry search github --json
  123. runx registry search x402 --json
  124. runx registry search send --json
  125. ```
  126. Install a catalog skill:
  127. ```bash
  128. runx registry install <publisher>/<skill>@<version> --json
  129. ```
  130. Run a skill:
  131. ```bash
  132. runx skill <skill-ref> --input key=value --json
  133. runx skill ./skills/<skill-name> --input request='...' --json
  134. runx skill <publisher>/<skill>@<version> --input key=value --json
  135. ```
  136. Inspect and verify receipts:
  137. ```bash
  138. runx history
  139. runx verify <receipt-id> --json
  140. ```
  141. Notarize a receipt when you need a shareable verification link. The notary
  142. counter-seals it and publishes the record, so anyone can read it:
  143. ```bash
  144. runx login
  145. runx notarize ./.runx/receipts/<receipt-id>.json --json
  146. ```
  147. Use `runx --help` for the exact installed CLI syntax. If a command in this file
  148. and the installed binary disagree, trust the installed binary and treat this file
  149. as the conceptual guide.
  150. ## Good skill selection
  151. Choose a skill by consequence, not by brand excitement alone.
  152. - For a full workflow, choose the domain skill: `pay`, `charge`, `refund`,
  153. `message-send`, `release`, or another project skill.
  154. - For provider-specific evidence, choose the branded implementation skill:
  155. GitHub-backed sync, weather-provider skills, and similar lanes.
  156. - For context-only work, choose a context skill such as `taste-profile` or
  157. `brand-voice`; those should inform a downstream skill, not perform a mutation.
  158. - For operations, choose a project/operator skill that routes to existing lanes;
  159. it should not reimplement CLI commands, hosted endpoints, or provider SDKs in
  160. prose.
  161. If no skill matches cleanly, do not force the task into the nearest catalog item.
  162. Return the gap: missing skill, missing grant, missing provider, missing schema,
  163. or missing confirmation.
  164. ## Safety rules
  165. - Never run a consequential action without a principal, target, and gate.
  166. - Never widen a grant in a child step.
  167. - Never treat a prompt instruction as authorization.
  168. - Never paste secrets, private keys, API tokens, raw customer lists, or provider
  169. dumps into `SKILL.md` or receipts.
  170. - Never mark money, messages, deploys, or provider mutations complete without a
  171. receipt plus readback.
  172. - Never hide a denial. Denials are part of the accountability model.
  173. - Never use a skill package as a dumping ground for unrelated workspace files.
  174. ## Output expectations for agents
  175. After running runx, report:
  176. - the skill or workflow that ran
  177. - the principal/grant used, at a safe level of detail
  178. - the action that was attempted
  179. - whether it succeeded, was denied, or needs input
  180. - the receipt id or receipt path from `runx history`
  181. - the external readback, if any
  182. - the next required human decision, if any
  183. Keep this report short. Put detailed evidence in receipts and linked artifacts,
  184. not in chat.
  185. ## Examples
  186. Read-only discovery:
  187. ```bash
  188. runx registry search 'openapi weather forecast' --json
  189. ```
  190. Governed local run:
  191. ```bash
  192. runx skill ./skills/github-issue-triage --input repository=acme/app --input issue_number=7 --json
  193. runx history
  194. ```
  195. Consequential run pattern:
  196. ```text
  197. 1. choose skill
  198. 2. prepare exact inputs
  199. 3. ask for approval if the act is consequential
  200. 4. run only after approval
  201. 5. inspect receipt and provider readback
  202. ```
  203. ## Read more
  204. - protocol: <https://runx.ai/spec>
  205. - primitives: <https://runx.ai/what>
  206. - doctrine: <https://runx.ai/doctrine>
  207. - catalog: <https://runx.ai/x>
  208. - source: <https://github.com/runxhq/runx>
  209. - credentials: <https://github.com/runxhq/runx/blob/main/docs/credentials.md>
  210. Open source. Apache-2.0 licensed. Self-hostable. Works with local agents and hosted
  211. surfaces because the skill contract, authority model, and receipts are portable.
README.md · README · 611 lines · 1 finding marked
  1. <h1 align="center">runx</h1>
  2. <p align="center"><strong>The governed runtime for agent skills</strong></p>
  3. <p align="center">
  4. <a href="LICENSE"><img alt="License: Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-111111?style=flat-square"></a>
  5. <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>
  6. <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>
  7. <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>
  8. <a href="https://runx.ai/spec"><img alt="Specification" src="https://img.shields.io/badge/spec-read-7c5cff?style=flat-square"></a>
  9. </p>
  10. <p align="center">
  11. <a href="#quickstart">Quickstart</a> ·
  12. <a href="#skills-working-together">Workflows</a> ·
  13. <a href="#a-skill-carries-judgment">Write a skill</a> ·
  14. <a href="#what-a-receipt-proves">Receipts</a> ·
  15. <a href="#build-on-runx">Build on Runx</a>
  16. </p>
  17. ---
  18. ```text
  19. A skill is a URL.
  20. A workflow is what unfolds.
  21. Authority narrows. It does not pass through.
  22. Every act produces a receipt.
  23. ```
  24. A skill is expertise published as a portable `SKILL.md`: an operating manual
  25. that a human can understand and an agent can act from. It carries the method,
  26. the evidence to look for, the decisions to make, and the tools the work needs.
  27. Skills can call other skills, passing their results forward into a larger job.
  28. Runx makes that work executable. A research brief can become an outreach draft.
  29. A product launch can connect release work, documentation, and customer updates.
  30. Search and product analytics can inform the next change to your site. Across
  31. those handoffs, Runx admits calls under explicit authority, delivers credentials
  32. at the tool boundary, supervises execution, and seals a verifiable record.
  33. ![Northstar's team-workspaces launch connects operations-review, audience evidence from lead-enrichment, release preparation, content-package, message-send, and email or Slack delivery. Product-analytics tracks the path from workspace creation to the first teammate invited.](docs/assets/readme/business-ops.svg)
  34. **Your agent supplies the judgment. Runx owns the execution boundary.** Use the
  35. CLI, MCP, or a language client with the agent or orchestration framework you
  36. already use. Execution, state, and receipt signing run locally; hosted registry,
  37. credential custody, and notary services are optional. The runtime is written
  38. in Rust and licensed under Apache-2.0.
  39. ## Quickstart
  40. ### With your agent
  41. Give your agent the [Runx operating manual](https://runx.ai/SKILL.md):
  42. ```text
  43. Set up Runx: https://runx.ai/SKILL.md
  44. ```
  45. Then give it a bounded job. For example:
  46. ```text
  47. Use Runx to investigate where our organic visitors stop becoming active users.
  48. Use Search Console, GA4, and our saved PostHog activation funnel. Compare the
  49. last two complete 28-day periods. Bring back the evidence, three priorities,
  50. and a proposed content or product change. Stop before publishing or sending.
  51. ```
  52. The agent can discover skills, inspect their inputs, bind the tools you choose,
  53. and work through the run's open turns. Missing accounts, evidence, or decisions
  54. remain explicit requests. [Native skill exports](docs/agent-skills.md) are also
  55. available for Claude Code and Codex.
  56. ### From your terminal
  57. Install the native CLI through npm:
  58. ```bash
  59. npm install --global @runxhq/cli
  60. ```
  61. Or use the standalone installer on macOS or Linux:
  62. ```bash
  63. curl -fsSL https://runx.ai/install | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 84 on GitHub
  64. ```
  65. Run the smallest complete example. This needs Git and Node.js 20 or newer;
  66. it needs no Runx account, model, or provider key.
  67. ```bash
  68. git clone --depth 1 https://github.com/runxhq/runx.git
  69. cd runx
  70. runx skill ./examples/hello-world --run-id first-run \
  71. -i message="Hello, Runx." --json
  72. ```
  73. Selected fields from the result:
  74. ```json
  75. {
  76. "status": "sealed",
  77. "outcome": "completed",
  78. "run_id": "first-run",
  79. "result": { "message": "Hello, Runx." },
  80. "receipt_id": "sha256:…"
  81. }
  82. ```
  83. Read the run, then verify the full receipt ID returned by the command:
  84. ```bash
  85. runx history first-run --json
  86. runx verify <receipt-id> --json
  87. ```
  88. The example executes a checked-in Node.js command. It exercises the same
  89. admission, execution, and signing path used by larger skills. The npm package
  90. distributes the native runtime; Node.js is needed here for the example script.
  91. See [Getting started](docs/getting-started.md) for the full walkthrough and
  92. [installation options](https://runx.ai/start) for platform packages.
  93. Skills can come from a local directory, a URL, or the registry. Published skills
  94. keep their `publisher/name` identity; verified publishers' skills can also hold
  95. a short root name. Local packages take precedence when resolving a bare name.
  96. Use an exact version and digest when you need to reproduce someone else's run.
  97. ## Skills working together
  98. Skills pass useful work forward: matched facts, a source-backed brief, a
  99. validated draft, an exact action to approve, or a receipt from the last run.
  100. The next skill can use that result directly.
  101. These are compositions you can give an agent: Runx skills working with your
  102. repositories, provider skills, and connected accounts. Your agent or a
  103. project-owned workflow makes the handoffs, carrying the actual outputs into the
  104. next skill's inputs.
  105. ### Business ops: get the next release into customers' hands
  106. ```text
  107. We're launching team workspaces in Northstar. Use Runx to prepare the release,
  108. choose the customer audience, update the setup guide, draft the announcement,
  109. and coordinate the rollout with the team. Establish the activation baseline
  110. from workspace creation to the first teammate invited so we can measure adoption.
  111. Bring back the launch kit, blockers, and receipts. Ask before sending,
  112. publishing, or deploying.
  113. ```
  114. [`operations-review`](skills/operations-review/SKILL.md) reviews the release state and proposes
  115. the next launch actions. [`lead-enrichment`](skills/lead-enrichment/SKILL.md)
  116. organizes supplied customer facts to inform the audience choice; the operator
  117. supplies the actual audience and contact policy.
  118. [`release#prepare`](skills/release/SKILL.md) checks the project's release
  119. profile and produces the version-bound brief. The full `release` method owns
  120. approval, publication, and verification through the project's commands.
  121. [`content-package`](skills/content-package/SKILL.md) combines release facts
  122. and product documentation with `research` and `ghostwrite` to prepare the setup
  123. guide and announcement, then packages them for publication.
  124. [`message-send#plan`](skills/message-send/SKILL.md) binds the principal,
  125. audience, accepted content, and approval requirements. The calling agent can
  126. hand that plan to [Nitrosend](https://nitrosend.com/SKILL.md) or another email
  127. provider's skill for its review, approval, and delivery workflow. For a team
  128. update, `message-send#send` owns the Slack post and independent readback itself.
  129. [`product-analytics`](skills/product-analytics/SKILL.md) establishes the
  130. workspace-to-invitation baseline from supplied reports and compares later
  131. results under the same measurement definition.
  132. **What comes back:** a launch kit with release notes, a setup guide, the customer
  133. announcement, a team update, and an activation baseline—plus the blockers,
  134. decisions, and receipts needed to take it live and follow adoption afterward.
  135. ### Outreach: facts → fit → a useful first contact
  136. ![Outreach composition: lead-enrichment and lead-qualify establish facts and fit; research, brand-voice, taste-profile, and contact eligibility feed cold-outreach. Its ghostwrite admission and verification surround the draft. message-send planning hands the accepted email to a selected provider for approval, delivery, and readback.](docs/assets/readme/outreach.svg)
  137. [`lead-enrichment`](skills/lead-enrichment/SKILL.md) normalizes supplied facts
  138. about a confidently matched subject.
  139. [`lead-qualify`](skills/lead-qualify/SKILL.md) checks those facts against your
  140. ICP and keeps commercial fit separate from contact eligibility.
  141. [`cold-outreach`](skills/cold-outreach/SKILL.md) takes that context, supported
  142. research, and the exact recipient's suppression state to prepare one email.
  143. The draft can use [`brand-voice`](skills/brand-voice/SKILL.md) and
  144. [`taste-profile`](skills/taste-profile/SKILL.md) without allowing either to
  145. invent product claims. Inside `cold-outreach`, `ghostwrite#admit` validates the
  146. evidence and writing context before drafting; `ghostwrite#verify` checks the
  147. result's source bindings afterward. Missing eligibility, suppression, or an
  148. unsupported claim produces a hold.
  149. **What comes back:** the exact sender, recipient, subject, body, and a source
  150. binding for review. `message-send#plan` can take that accepted draft into a
  151. provider handoff. The selected email skill—Nitrosend or another provider—checks
  152. its own audience and sender requirements, obtains approval for the exact send,
  153. and reports the provider result. Choose a provider and delivery mode that permit
  154. the intended contact; commercial fit alone never grants that permission.
  155. Enrichment uses the evidence you supply; a provider lookup is a separate
  156. connector operation. The calling application retains outcomes for follow-up.
  157. A reply, opt-out, or changed eligibility changes what the next run may do.
  158. Try it with your agent: *“Use the supplied prospect research, our ICP, brand
  159. voice, and contact-policy decision to prepare one useful first-contact email.
  160. Show the facts behind it and hold any recipient with unresolved eligibility.”*
  161. ### Organic growth: connect discovery to activation
  162. ![Organic growth composition: google-search-console, google-analytics, product-analytics, and site research meet in organic-growth. Priorities feed content-package or repository work through code-plan and github-issue-to-pr. Approved changes are measured again using comparable windows and definitions.](docs/assets/readme/organic-growth.svg)
  163. Each source answers a different question. Search Console shows how people find
  164. you. GA4 shows acquisition and behavior under the property's measurement model.
  165. Product analytics shows where a defined journey loses people or accounts
  166. after signup.
  167. [`google-search-console`](skills/google-search-console/SKILL.md) and
  168. [`google-analytics`](skills/google-analytics/SKILL.md) return normalized
  169. evidence with source digests and measurement caveats. The
  170. [`PostHog connector`](connectors/posthog/README.md) reads saved insights from
  171. your selected Cloud project and region; it preserves their query definitions
  172. and cached-result freshness.
  173. [`product-analytics`](skills/product-analytics/SKILL.md) consumes the supplied
  174. aggregate reports, calculates funnel and retention rates, and checks whether
  175. the comparison is meaningful.
  176. [`organic-growth`](skills/organic-growth/SKILL.md) combines search, analytics,
  177. site, and market evidence into priorities and a measurement plan. Product
  178. findings can join that evidence with their source reference and digest. For
  179. example, a page getting more clicks while its visitors fail to activate may
  180. need a clearer promise, a better onboarding path, or an instrumentation fix.
  181. **What comes back:** observations, hypotheses, ranked actions, source bindings,
  182. and a measurement plan. Content work can continue through `content-package`;
  183. code and instrumentation work can go through
  184. [`code-plan`](skills/code-plan/SKILL.md) and
  185. [`github-issue-to-pr`](skills/github-issue-to-pr/SKILL.md) in the owning repository. The next
  186. analysis reuses comparable windows and definitions. Missing or stale reports
  187. remain measurement gaps.
  188. ### Run the local workflow proofs
  189. From this checkout:
  190. ```bash
  191. # Research → draft → channel package → publication handoff
  192. runx test skills/content-package/tests/composes-in-workflow.yaml
  193. # A specific outreach draft with supplied evidence and writing context
  194. runx test skills/cold-outreach/tests/prepares-approved-context-email.yaml
  195. # Search + analytics + site evidence → growth priorities
  196. runx test skills/organic-growth/tests/composes-in-workflow.yaml
  197. # Defined product funnel → rates and source-bound recommendations
  198. runx test skills/product-analytics/tests/composes-in-workflow.yaml
  199. # Exact Slack post → approval → provider response → independent readback
  200. runx test skills/message-send/tests/post-default-notifies-and-verifies.yaml
  201. ```
  202. These are fixture-backed executions, with no live account reads or sends. Live
  203. work uses your provider bindings and actual evidence. Browse the
  204. [skill catalog](https://runx.ai/x) for more workflows, or the
  205. [demo gallery](docs/demos.md) for local execution, state, and loop examples.
  206. ## A skill carries judgment
  207. `SKILL.md` is the capability's operating manual. It explains when to use the
  208. skill, what evidence matters, how to make the decisions, when to stop, and what
  209. completion means. It remains readable and useful on its own.
  210. ```markdown
  211. ---
  212. name: hello-world
  213. description: Echo a message through a checked-in command.
  214. ---
  215. # Hello World
  216. Print the supplied message so the caller can inspect the local execution
  217. and its signed receipt.
  218. ```
  219. When the work needs executable steps, typed inputs and outputs, authority,
  220. artifacts, or test cases, the package also carries a `run.yaml`:
  221. ```yaml
  222. version: "0.1.1"
  223. minimum_runx: 0.12.0
  224. catalog:
  225. visibility: public
  226. methods:
  227. default:
  228. inputs:
  229. message:
  230. type: string
  231. description: Message to print from the example skill.
  232. steps:
  233. - id: default
  234. tool: {command: node, args: [run.mjs]}
  235. inputs:
  236. message: $input.message
  237. outputs:
  238. message: {type: string}
  239. ```
  240. This is the execution shape of [`examples/hello-world`](examples/hello-world).
  241. Its checked-in package also includes the command and test case.
  242. | Part | Responsibility |
  243. | --- | --- |
  244. | `SKILL.md` and references | Expertise, procedure, judgment, recovery, and completion criteria. |
  245. | `run.yaml` | Executable methods, typed contracts, declared capabilities, authority, and test cases. |
  246. | Domain modules | Deterministic computation specific to the skill. |
  247. | Runx | Provider transport, filesystem and process access, credential delivery, execution state, and receipts. |
  248. Runx binds the manual and closure by digest. An acting agent receives
  249. the invoked skill's full manual; declared adjacent skills contribute bounded
  250. summaries until invoked. A workflow can also supply a skill as explicit
  251. `context.skills` on an agent step—for example, a writing rubric. Context informs
  252. judgment; permission comes from admission.
  253. ## Workflows make acts composable
  254. A method can combine five step kinds:
  255. | Step | Use it for |
  256. | --- | --- |
  257. | `agent` | Judgment under the skill's manual and an explicit allowance of calls. |
  258. | `tool` | A native capability, deterministic computation, or declared process command. |
  259. | `operation` | A typed connector call to an external provider. |
  260. | `ask` | A question or decision the run needs before it can continue. |
  261. | `skill` | Another skill's method, with explicit inputs and outputs. |
  262. A method's steps make the dataflow visible. The `hello-workflow` example's
  263. run.yaml runs one skill twice:
  264. ```yaml
  265. minimum_runx: 0.12.0
  266. methods:
  267. default:
  268. steps:
  269. - id: first
  270. skill: ../hello-world
  271. inputs:
  272. message: Hello from the first skill.
  273. - id: second
  274. skill: ../hello-world
  275. inputs:
  276. message: $steps.first.message
  277. ```
  278. The second step consumes the first step's typed output, and the method's
  279. receipt links their receipts. The same mechanism lets `content-package` pass a
  280. research packet into `ghostwrite`, then pass the validated draft into its
  281. packaging and handoff methods. Inspect its
  282. [actual methods](skills/content-package/run.yaml).
  283. Use an agent turn for work that needs judgment. Use a workflow when phases,
  284. branches, guards, or approval boundaries must be part of the execution
  285. contract. Required side effects belong in explicit execution steps, where
  286. Runx can record the attempt and result. An agent's completion text cannot
  287. substitute for a provider operation.
  288. Workflows and agent turns can both call skills. A host can pass an existing packet
  289. artifact into a later call; Runx checks its content digest and input schema.
  290. This is how a useful result becomes an input to more work without flattening
  291. its provenance into prose.
  292. [Compose skills](docs/composing-skills.md) ·
  293. [Execution profile reference](docs/reference.md#skill-and-execution-profile)
  294. ## Work can outlive an agent turn
  295. By default, an agent step yields work to the calling agent. Runx returns the
  296. manual, typed request, and allowed calls. Your host can work the turn through
  297. MCP, provide its result, and continue the same run. The optional
  298. `--drive` mode delegates those turns to a configured model provider.
  299. ```bash
  300. # Inspect a running, paused, or completed run
  301. runx history <run-id> --json
  302. # Serve the paused run's agent turns over MCP
  303. runx mcp --run <run-id>
  304. # Continue with answers to the run's exact pending requests
  305. runx resume <run-id> answers.json --json
  306. ```
  307. The run records pending requests and completed calls. Independent read calls
  308. can run concurrently; effects are serialized within the run. A retry reuses
  309. the call's identity, and an uncertain external result remains explicit for
  310. reconciliation. Resume checks the package and closure so a changed
  311. skill cannot silently continue an old run.
  312. Agent answers and human approvals have separate fields. Each decision binds to
  313. the digest of the request it answers. The host is responsible for obtaining
  314. the human decision; putting a JSON value in an approval field is a host
  315. assertion, not proof of a person's identity.
  316. For recurring operations, the outer host owns scheduling and stop policy.
  317. Each iteration can read prior receipts and durable state, submit a bounded
  318. run, and retain the result for the next iteration. See the
  319. [loop example](examples/loop-orchestration) and
  320. [continuation contract](docs/reference.md#local-cli).
  321. ## Connect tools without handing secrets to skills
  322. Skills declare the connector operations they need. Connectors declare typed
  323. requests, scopes, credential requirements, and readback behavior. You choose
  324. the account and binding: a local credential, a supported existing session, or
  325. an optional hosted connection.
  326. For example, install web search and bind it to your Exa account:
  327. ```bash
  328. runx registry install runx/web-search
  329. runx connector use exa
  330. runx skill runx/web-search -i query="Agent skill interoperability" --json
  331. ```
  332. If the connector's declared credential variable is set, `connector use` binds
  333. to it; otherwise it asks for the key. For supported sessions, such as an
  334. existing `gh` sign-in:
  335. ```bash
  336. runx connector use github --session --scope repo.read
  337. ```
  338. The kernel delivers credentials only at the admitted operation's transport
  339. boundary. Skills name operations and supply typed inputs. Secret material
  340. stays out of their instructions, model context, and receipts.
  341. One skill can work with different compatible providers. One connector binding
  342. can serve several skills. Using hosted credential custody leaves the calling
  343. operator and its state local unless you explicitly select a hosted service.
  344. Connector names identify the capability provider: `github`, `posthog`,
  345. `google/analytics`, or `google/search-console`. A skill binding a connector
  346. outside its own plugin pins the manifest digest; the closure binds
  347. the operations it will actually use.
  348. [Credential setup](docs/credentials.md) ·
  349. [Connector catalog](https://runx.ai/connectors) ·
  350. [Connector manifests](connectors/)
  351. ## Authority follows the work
  352. Every governed execution follows the same boundary:
  353. ```text
  354. Admit → Resolve grant → Deliver credentials → Execute → Seal
  355. ```
  356. Authority is checked where a call executes. Child calls remain within the
  357. parent's grant; naming another skill or describing an action in a prompt does
  358. not create permission. An operation that requires approval pauses with the
  359. exact request for the host to present to the human.
  360. The execution lanes have deliberate boundaries:
  361. - **Deterministic modules** perform JSON-to-JSON domain computation without
  362. ambient filesystem, network, process, environment, clock, or random access.
  363. - **Native capabilities** own reusable runtime mechanics and their admission
  364. checks, including file access, processes, artifacts, and data operations.
  365. - **Connector operations** execute declared HTTP, MCP, or Connect calls under
  366. typed authority and effect contracts.
  367. - **Process tools** are trusted local executables. Runx controls their argv,
  368. working directory, delivered environment, credentials, and supervision.
  369. They execute with the host's OS permissions; this is not portable OS isolation.
  370. These guarantees cover work executed through Runx. The surrounding agent or
  371. application owns its other tools, authentication of human decisions, and host
  372. isolation.
  373. [Authority and security proof](docs/security-authority-proof.md) ·
  374. [Security policy](SECURITY.md)
  375. ## What a receipt proves
  376. A receipt answers the questions that matter after the agent has moved on:
  377. | Question | Evidence |
  378. | --- | --- |
  379. | What ran? | Skill identity, source and execution digests, and method metadata. |
  380. | Who or what admitted it? | Actor references, grant references, and execution terms. |
  381. | What was allowed? | Scopes, resolved grants, and approval decisions. |
  382. | What happened? | Acts, output references and how each ended. |
  383. | How did the work connect? | Linked child receipts and artifact provenance. |
  384. | Can I check it later? | A content-addressed ID, canonical digest, and signature. |
  385. Runx signs receipts with Ed25519. On first use, an unconfigured Runx home
  386. creates its own local signing key. `runx history` inspects the record;
  387. `runx verify` checks its signature and linked receipt tree.
  388. A valid signature establishes integrity against a trusted signer. Read the
  389. receipt's outcome as well: a sealed refusal or failed run is still sealed.
  390. A local content draft proves preparation; provider readback establishes the
  391. external result. A receipt from another home or hosted issuer requires that
  392. issuer's trusted public key.
  393. Receipts carry references, decisions, hashes, and bounded observations.
  394. Raw credentials and unchecked private provider bodies do not belong in proof.
  395. The result payload and the signed receipt have separate jobs: the result is
  396. what the next caller uses; the receipt records how the work was admitted and
  397. what execution established.
  398. Read the [receipt schema](schemas/receipt.schema.json), inspect a
  399. [sealed fixture](fixtures/receipt-verify/valid-production/receipt.json), or
  400. use the [standalone verifier](tools/verify/verify.mjs) to check proof outside
  401. the execution runtime.
  402. ## Author, test, and publish
  403. Keep a skill in your project, adapt an existing package, or publish it for
  404. others to compose. Start an authoring run with:
  405. ```bash
  406. runx skill runx/skill-build#build \
  407. -i objective="Review a release and prepare its customer announcement" \
  408. -i target_dir=skills/launch-review
  409. ```
  410. Your agent works the authoring turns; the package is written after
  411. validation. Without a managed agent, the run returns the pending work and
  412. resume instructions.
  413. A finished package should include test cases for its successful path,
  414. refusals, and composition with other skills. The test replays declared
  415. inputs and agent/provider responses so those contracts can be checked locally.
  416. ```bash
  417. runx test ./skills/launch-review
  418. runx login --for publish
  419. runx registry publish ./skills/launch-review
  420. ```
  421. Hosted publication reconstructs the submitted package, reruns its test,
  422. and stores immutable package digests. Local test results prove the cases
  423. they exercise; live integration claims need evidence from the actual provider
  424. path too.
  425. [Authoring reference](docs/reference.md#standalone-skill-packages) ·
  426. [Skill quality standard](docs/skill-quality-standard.md) ·
  427. [Publishing](docs/publishing.md)
  428. ## Build on Runx
  429. The CLI, MCP server, and language clients use the same Rust execution path.
  430. An application can start a skill, expose its open turns to a model, route
  431. human decisions, resume the run, and inspect its receipts.
  432. | Surface | Entry point |
  433. | --- | --- |
  434. | CLI | `runx skill <skill-ref>[#<method>] -i key=value --json` — [reference](docs/reference.md#local-cli). |
  435. | MCP | `runx mcp <skill-ref>` to expose a skill; `runx mcp --run <run-id>` to work an existing run. |
  436. | TypeScript / Node.js | [`@runxhq/client`](packages/client/README.md), with explicit workspace and environment configuration. |
  437. | Python | [Python SDK](packages/sdk-python/README.md). |
  438. | Contracts | [Schemas](schemas/) and the [public specification](https://runx.ai/spec). |
  439. MCP exposes a turn's allowed calls as typed tools. The host owns the model
  440. conversation; Runx admits and records the calls. You can integrate a single
  441. skill or build a product around long-lived runs without introducing another
  442. execution implementation.
  443. <details>
  444. <summary><strong>Inside the runtime: which layer owns what</strong></summary>
  445. | Layer | Owner |
  446. | --- | --- |
  447. | Portable wire contracts | `runx-contracts` |
  448. | Pure policy, authority, and state transitions | `runx-core` |
  449. | Package parsing and validated package representation | `runx-parser` |
  450. | Canonical receipts, hashing, signatures, and verification | `runx-receipts` |
  451. | Execution, capabilities, processes, adapters, and effects | `runx-runtime` |
  452. | Argument parsing and presentation | `runx-cli` |
  453. | Language clients and extension protocols | `packages/` |
  454. | Operator knowledge and domain computation | `skills/` and product-owned packages |
  455. The [system architecture](docs/architecture/runx-system.md) defines these
  456. ownership boundaries. SDKs, exported agent skills, schemas, and catalog views
  457. consume the same contracts.
  458. </details>
  459. ## Contribute
  460. Runx is in active development. Start with a concrete workflow, a reproducible
  461. execution problem, a connector contract, or a skill with useful test cases.
  462. The [contributor guide](CONTRIBUTING.md) covers setup, focused checks, and
  463. sign-off requirements.
  464. Build the native CLI from this checkout:
  465. ```bash
  466. cargo build --manifest-path crates/Cargo.toml -p runx-cli
  467. crates/target/debug/runx test examples/hello-world
  468. ```
  469. [Reference](docs/reference.md) · [Demos](docs/demos.md) ·
  470. [Releases](https://github.com/runxhq/runx/releases) ·
  471. [Open an issue](https://github.com/runxhq/runx/issues)
  472. ---
  473. <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
  1. # runx installer for Windows.
  2. #
  3. # irm runx.ai/install.ps1 | iex
    • Note: Runs a downloaded PowerShell script (iex / Invoke-Expression)
    • Line 3 on GitHub
  4. #
  5. # Downloads the prebuilt binary from the GitHub Release, verifies its sha256, and
  6. # installs it. Honors $env:RUNX_VERSION (default: latest cli-v* release) and
  7. # $env:RUNX_INSTALL_DIR (default: %LOCALAPPDATA%\runx\bin).
  8. $ErrorActionPreference = "Stop"
  9. $repo = "runxhq/runx"
  10. $arch = $env:PROCESSOR_ARCHITECTURE
  11. if ($arch -ne "AMD64") { throw "unsupported architecture: $arch (only x64 is published)" }
  12. $target = "x86_64-pc-windows-msvc"
  13. $version = $env:RUNX_VERSION
  14. if (-not $version) {
  15. Write-Host "runx: resolving latest release..."
  16. $releases = Invoke-RestMethod "https://api.github.com/repos/$repo/releases"
  17. $tag = ($releases | Where-Object { $_.tag_name -like "cli-v*" } | Select-Object -First 1).tag_name
  18. if (-not $tag) { throw "could not resolve latest cli-v* release; set `$env:RUNX_VERSION" }
  19. $version = $tag
  20. }
  21. $version = $version -replace '^cli-v','' -replace '^v',''
  22. $archive = "runx-$version-$target.zip"
  23. $base = if ($env:RUNX_BASE_URL) { $env:RUNX_BASE_URL } else { "https://github.com/$repo/releases/download/cli-v$version" }
  24. $tmp = Join-Path $env:TEMP ("runx-" + [guid]::NewGuid())
  25. New-Item -ItemType Directory -Path $tmp | Out-Null
  26. try {
  27. Write-Host "runx: downloading $version ($target)"
  28. Invoke-WebRequest "$base/$archive" -OutFile "$tmp\$archive"
  29. try {
  30. Invoke-WebRequest "$base/$archive.sha256" -OutFile "$tmp\$archive.sha256"
  31. $expected = (Get-Content "$tmp\$archive.sha256").Split(" ")[0]
  32. $actual = (Get-FileHash "$tmp\$archive" -Algorithm SHA256).Hash.ToLower()
  33. if ($expected -ne $actual) { throw "checksum mismatch (expected $expected, got $actual)" }
  34. Write-Host "runx: checksum verified"
  35. } catch { Write-Warning "runx: skipping checksum verification ($_)" }
  36. Expand-Archive "$tmp\$archive" -DestinationPath $tmp -Force
  37. $dir = $env:RUNX_INSTALL_DIR
  38. if (-not $dir) { $dir = Join-Path $env:LOCALAPPDATA "runx\bin" }
  39. New-Item -ItemType Directory -Path $dir -Force | Out-Null
  40. Copy-Item "$tmp\runx-$version-$target\runx.exe" "$dir\runx.exe" -Force
  41. Copy-Item "$tmp\runx-$version-$target\runx-js-worker.exe" "$dir\runx-js-worker.exe" -Force
  42. Write-Host "runx: installed to $dir\runx.exe"
  43. $userPath = [Environment]::GetEnvironmentVariable("Path", "User")
  44. if ($userPath -notlike "*$dir*") {
  45. [Environment]::SetEnvironmentVariable("Path", "$userPath;$dir", "User")
  46. Write-Host "runx: added $dir to your user PATH (restart your shell)"
  47. }
  48. } finally {
  49. Remove-Item -Recurse -Force $tmp -ErrorAction SilentlyContinue
  50. }

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.