runx

runx

エージェントスキルのガバナンス対応ランタイム

---

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

スキルとは、持ち運び可能な SKILL.md として公開された専門知識です。人間が理解でき、エージェントがそれに基づいて行動できる運用マニュアルです。スキルを組み合わせれば、専用のグルーコードを用意せずにグラフや実際の作業を構成できます。Runx はその境界を担います。明示的な権限のもとで各アクションを許可し、認証情報をプロンプトの素材にすることなく受け渡し、実行を監督し、結果を検証可能なレシートとして封印します。

権限は一連の流れを通じて絞り込まれるため、エージェントの作業は暗黙の信頼を生み出すことなく積み重なります。

runx ではないもの

Runx はエージェントやオーケストレーションツールの下位に位置するガバナンス対応ランタイムであり、新たなエージェントフレームワークではありません。ここにはエージェント、プロンプトチェーン、モデルループ、ベクトルストアはありません。Runx は、すでに利用しているオーケストレーションレイヤーの下で動作します。Runx は明示的な権限のもとで各アクションを許可し、認証情報をプロンプトの素材にすることなく受け渡し、実行を監督し、結果を検証可能なレシートとして封印します。

ローカル CLI／ランタイム（runx、npm パッケージ @runxhq/cli）は、スキルを実行し、お使いのマシン上でレシートを封印します。ホステッドサービスは任意で利用できる補完機能です。runx.ai/x のレジストリ／カタログではスキルを公開、検索でき、ハーネスはチェックイン済みのケースを再生し、コネクターは各プロバイダー操作と、それを認可する認証情報を宣言します。ローカルランタイムだけでも利用できます。最初のレシートを封印するのに、ホステッドサービスは必要ありません。

クイックスタート

この README には、エージェントが読み取れる版の runx.ai/SKILL.md もあります。これをエージェントに渡すと、エージェントは CLI、runx.ai/x のカタログ、レシートの返し方を学習します。

CLI をインストールします。

npm i -g @runxhq/cli
# or: curl -fsSL https://runx.ai/install | sh

次に、スキルの実行方法を選びます。

エージェントを使う場合

エージェントに目標を渡し、ランタイムを操作させます。

Use runx to plan and execute end-to-end business ops for my company.
Signal: acme.com signed up 40 seats yesterday.
Stop before sends, spend, merges, deploys, or publishing. Return receipts.

CLI パス

ローカルまたはカタログのスキルを直接実行します。

runx skill <skill-ref> [runner] -i key=value --json

アカウントもホストされた環境も不要で、5 分以内にローカルでレシートを封印できます。

npm i -g @runxhq/cli
git clone --depth 1 https://github.com/runxhq/runx.git
cd runx
runx skill ./examples/hello-world -i message="hello, runx" --json

チェックイン済みの examples/hello-world スキルはローカルコマンドを実行し、最後の --json 出力は、status: "sealed" と receipt_id を含む runx.skill_run.v1 の結果です。ガバナンス記録を runx history <receipt-id> --detail --json で確認できます。

business-ops は、ビジネスシグナルをエンドツーエンドでルーティングする、事前構築済みスキルのひとつです。

runx skill business-ops \
  -i signal="acme.com signed up 40 seats yesterday: classify the work, prepare the governed handoffs, and preserve proof" \
  --json

このグラフが中核となる構成です。ひとつのシグナルが入り、ガバナンスされた権限のもとでスキルが連携し、重大な影響を伴うレーンは承認ゲートで停止します。そして、すべての実行がひとつのレシートツリーに封印され、次の実行に利用できます。デモのレーンは代替例です。実際のチームでは、独自のコンテキスト、ポリシー、ツール、プロバイダー、読み戻しを結び付けます。

ほかの例：

# Docs and product engineering: build a source-bound documentation packet.
runx skill sourcey -i project=. --json

# Research and strategy: produce a governed decision brief.
runx skill deep-research \
  -i objective="Which launch risks should we resolve first?" \
  --json

# Maintainer operations: draft a useful issue response.
runx skill issue-triage \
  -i issue_url=https://github.com/runxhq/runx/issues/241 \
  -i objective="Draft the next helpful maintainer response" \
  --json

Runx 自体の開発時に、ソースからネイティブ CLI をビルドします。

cargo build --manifest-path crates/Cargo.toml -p runx-cli

macOS 26 でこのビルドが停止する場合は、 Developer Tools の権限に関する前提条件 を満たしてください。

npm パッケージは同じ Rust 管理の動作を提供するもので、別のランタイムではありません。

スキルが担うのは判断であり、ランタイムの仕組みではありません

SKILL.md は、その機能の運用マニュアルです。作業の意味、レーンを使うタイミング、重要な証拠、判断の限界、承認が必要な事項、失敗と復旧の方法、隣接するスキルへのルーティングが必要なタイミングを、オペレーターに伝えます。

---
name: hello-world
description: Echo a first Runx message through a checked-in command.
---

# Hello World

Use this package to prove the local execution and receipt path.

スキルに決定論的な実行、型付き入力、グラフのステージ、権限、アーティファクト、ハーネスケースが必要な場合は、run.yaml の実行プロファイルも含めます。各ランナーはステップのリストで、各ステップは agent、tool、operation、ask、skill の5種類のいずれかです。

skill: hello-world
version: "0.1.0"

runners:
  default:
    default: true
    inputs:
      message:
        type: string
        required: true
    steps:
      - id: default
        tool: { command: node, args: [run.mjs] }
        inputs:
          message: $input.message
        outputs:
          message: string

この分離には意図があります。

• SKILL.md は、人間と実行エージェントが必要とする知識を担います。
• run.yaml は、機械検証可能な実行、権限、証拠の契約を担います。
• パッケージの JavaScript は、グラフとネイティブ機能プレーンでは簡潔に表現できない、決定論的なドメイン計算にのみ使います。
• HTTP、ファイルシステム、プロセス、認証情報、パケット、レシートの仕組みはランタイムに属し、スキル内にヘルパーとして複製しません。

Runx は、現在のマニュアル全体をダイジェストでバインドし、実行コンテキストと再開エンベロープに含めます。宣言された隣接スキルは、呼び出されるまでは範囲を限定した要約を提供し、呼び出されると、そのスキルのマニュアル全体を提供します。

Skill to Graph と Skill Catalog を参照してください。

グラフでアクトを合成できます

ランナーは、CLI サブプロセス（runx skill <skill-ref> ...）、MCP サーフェス、または packages/ の言語バインディングを通じて runx を呼び出します。起動する HTTP サーバーはありません。1 回の runx skill 呼び出しが 1 つのガバナンス対象ターンです。1 回の実行で複数のスキルを連鎖させるには、グラフを合成します。

グラフを使うと、あるガバナンス対象アクトが別のアクトの型付き出力を利用できます。

name: hello-graph
steps:
  - id: first
    skill: ../hello-world
    inputs:
      message: hello from graph
  - id: second
    skill: ../hello-world
    inputs:
      message: $steps.first.message

境界を決めるのは、モデルが何回呼び出されたかではありません。保証すべき内容です。

• グラフは、決定論的な合成、分岐、ガード、復旧を担います。
• エージェントのステップは、現在のマニュアルと明示的なツールセットの下で、範囲を限定した判断を担います。
• ネイティブ機能は、再利用可能で、特定の製品に依存しないランタイムの仕組みを担います。
• 決定論的モジュールは、周囲のファイルシステム、ネットワーク、プロセス、環境、クロック、乱数に対する権限を持たずに、分離された JSON から JSON へのドメイン計算を実行します。
• プロセスツールは、正確に解決された許可の下で、意図的に信頼されたローカル実行可能ファイルを実行します。Runx は、argv、cwd、引き渡す環境、認証情報、監視、証跡を制御しますが、移植可能な OS の隔離を保証するものではありません。
• コネクター操作は、型付きの権限とエフェクト契約の下で、ガバナンス対象の HTTP、MCP、Connect リクエストを実行します。

必須の変更、API 呼び出し、支払い、プロバイダーへの書き込みは、決定論的でエフェクトを管理するレーンに属します。エージェントやグラフの作成者は、説明文や入力データに名前を記載するだけでエフェクトを取得することはできません。

シークレットを漏らさない権限管理

認証情報はコネクターに属し、スキルでは呼び出すコネクター操作のみを指定します。標準入力からデータをパイプして、アカウントを一度だけバインドします。

printf '%s' "$NITROSEND_API_KEY" |
  runx credential set nitrosend --credential api_key --from-stdin

runx skill ./skills/nitrosend status --json

カーネルは、許可した各操作に対して、バインド済みインスタンスの認証情報を渡します。そのため、スキル、プロンプト、入力、レシートのいずれにも認証情報の実体は保存されません。スキルの実行、再開、検査、管理対象エージェント、MCP は、同じ準備状態の契約を使用します。

レシートには、要求されたスコープと付与されたスコープ、許可参照、型付きの実行境界の観測情報、承認判断、プロバイダーの観測情報、ハッシュを含めることができます。生のトークン、パスワード、周囲の環境のダンプ、未検証の非公開プロバイダー本文を含めてはなりません。

認証情報とセキュリティ権限の証明を参照してください。

レシートが証明すること

Runx のレシートは、エージェントが処理を終えた後に重要となる問いに答えます。

問い	レシートの項目
何が実行されたか？	サブジェクト、スキル参照、ソースタイプ、ランナーのメタデータ
誰が、または何が実行を許可したか？	アクター参照、許可参照、実行条件
何が許可されていたか？	スコープ、解決済みの許可、承認メタデータ
何が起きたか？	アクト、出力アーティファクト、終了ステータス、終了サマリー
後から検証できるか？	コンテンツアドレス指定 ID、正規ダイジェスト、署名、系譜
証明情報にシークレットが漏れていないか？	編集メタデータとハッシュ化された素材参照

すべてのガバナンス対象の実行には、次の不変条件が適用されます。

admit -> resolve grant -> deliver credentials -> execute -> seal

Runx はすべてのレシートに署名します。署名者が設定されていない場合は、この runx ホームの独自の鍵（初回実行時に作成）で署名します。この鍵を使って、ワークスペースのレシートを検証します。

runx verify --json

別のホームやホストされた発行者のレシートは、そのために設定した公開鍵で検証します。レシート自体がプロダクトなのではありません。権限、アクション、証跡、将来の学習が、検証可能な 1 つのオブジェクトとして交わる場所です。

コミット済みの契約は schemas/receipt.schema.jsonです。実際の封印済みレシートの例は fixtures/receipt-verify/tampered-body/receipt.json にあります。

境界を証明するデモ

チェックイン済みの以下のパスは、スクリーンショットや文章だけの主張ではなく、証跡を生成します。

デモ	証明する内容	実行方法
examples/hello-world	ネイティブ CLI スキルのパスと、封印済み証跡のベースライン	runx harness examples/hello-world
skills/business-ops	1 つのシグナルがガバナンスされたレーンに分岐し、グラフの証跡が保持されること	runx harness skills/business-ops
examples/http-graph	ネイティブのガバナンスされた HTTP がローカルフィクスチャに対して実行されること	sh examples/http-graph/run.sh

デモを参照してください。

公開と信頼

公開スキルはスタンドアロンのパッケージです。実質的な内容を持つSKILL.md、任意の run.yaml、そして Runx が利用できるファイルのみで構成されます。まずローカルで公開します。

runx registry publish ./skills/<your-skill>

共有カタログで検索できるようにする場合は、次にホスト型カタログへ公開します。

runx login --for publish
runx registry publish ./skills/<your-skill> \
  --registry https://api.runx.ai

ホスト型の公開では、送信されたパッケージを再構築してハーネスを再実行し、 不変のパッケージダイジェストを保存します。公開者であるとの申告だけでは、信頼の根拠になりません。

公開を参照してください。

アーキテクチャ

Runx では、各コントラクトと動作の所有者を 1 つに定めています。

レイヤー	所有者
ポータブルなワイヤーコントラクト	runx-contracts
純粋なポリシー、権限、状態遷移	runx-core
パッケージの解析と、検証済みパッケージを集約した IR	runx-parser
正規化された証跡、ハッシュ、署名、検証	runx-receipts
実行、機能、プロセスの監視、アダプター、副作用	runx-runtime
引数の解析と表示	runx-cli
生成された言語バインディングと限定的な拡張プロトコル	packages/
運用者の知識と、還元不可能なドメイン計算	skills/ とプロダクト所有のパッケージ

ネイティブ CLI、SDK、スキーマ、カタログビュー、エクスポートされたエージェント用シム、ドキュメントは、 すべてこれらの所有者を利用します。並列したパーサー、エグゼキューター、認証情報ローダー、 オーサリングフレームワーク、副作用レジストリ、プロバイダークライアントは存在しません。

規範となるコントラクトは Runx システムアーキテクチャです。過去の設計 ノートは、リポジトリが現在の形に至った経緯を説明するものであり、これに優先するものではありません。

ドキュメント

こちらを読む	必要な情報
はじめに	最初のスキル、最初の証跡
システムアーキテクチャ	所有権、実行レーン、境界
認証情報	コネクターの認証情報、インスタンス、ホスト型の許可
スキルからグラフへ	ガバナンスされたアクトの構成
セキュリティ権限の証明	スコープ、認証情報、許可、検証
デモ	実行可能な証明パス
公開	ローカルおよびホスト型のスキル公開
スキルカタログ	カテゴリー、検索、ファーストパーティーマップ
リファレンス	CLI、クレート、レジストリ、証跡、拡張プロトコル
仕様	アクトモデル、証跡文法、公開コントラクト
カタログ	URL で参照できるガバナンスされたスキル

コントリビューション

セットアップ、対象を絞ったテストの選択、承認ルールについては CONTRIBUTING.mdを参照してください。セキュリティポリシー： SECURITY.md。Runx は Apache-2.0 ライセンスです。LICENSEを参照してください。

---

_{Rust で構築 · Apache-2.0 · runx.ai}