Skip to content

getting-started.md

Latest commit

 

History

History
89 lines (69 loc) · 3.35 KB

getting-started.md

File metadata and controls

89 lines (69 loc) · 3.35 KB

Getting Started

This walkthrough proves the local runx path with one small skill. It uses the checked-in examples/hello-world package so the commands stay tied to the repo.

Prerequisites

  • Rust 1.85 or newer for the native CLI path.
  • Node.js 20 or newer for the checked-in hello-world runner command. No TypeScript install is required for the native CLI path.
  • pnpm 10 or newer only when exercising the npm wrapper or TypeScript package tests.

Build the native CLI from the OSS workspace:

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

Run The Example

Run the skill directly through the CLI:

export RUNX_RECEIPT_SIGN_KID=runx-demo-key
export RUNX_RECEIPT_SIGN_ED25519_SEED_BASE64=QkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkI=
export RUNX_RECEIPT_SIGN_ISSUER_TYPE=hosted
export RUNX_RECEIPT_DIR="$(mktemp -d)"
crates/target/debug/runx skill examples/hello-world \
  --message "hello from docs" \
  --non-interactive \
  --json

The JSON response should report status: "sealed" and include a receipt id. The npm wrapper may be used for package-distribution checks, but it should delegate to the same Rust binary behavior.

Inspect The Receipt

The quickstart writes receipts to the temporary directory stored in RUNX_RECEIPT_DIR. Use the id from the previous command as a history query:

crates/target/debug/runx history <receipt-id> --json

The history projection should show a runx.receipt.v1 receipt. The demo key above is intentionally public and exists only for local smoke tests. It is still durable evidence that runx executed the skill, recorded the input shape, and captured the output without relying on prose claims.

Production Receipt Signing

For production-trusted receipts, replace the demo key with an Ed25519 signing key before running skills, graphs, harness replay, or MCP server calls:

export RUNX_RECEIPT_SIGN_KID="hosted-prod-key"
export RUNX_RECEIPT_SIGN_ED25519_SEED_BASE64="<32-byte-ed25519-seed-base64>"
export RUNX_RECEIPT_SIGN_ISSUER_TYPE="hosted"

All three variables must be set together. RUNX_RECEIPT_SIGN_ISSUER_TYPE must be hosted or ci; production receipts are never stamped as local issuers. When configured, the runtime signs each receipt body digest with Ed25519 and writes the matching public key hash in the issuer metadata. To have runx history report those receipts as production-verified, provide the public verification key to the same command:

export RUNX_RECEIPT_VERIFY_KID="hosted-prod-key"
export RUNX_RECEIPT_VERIFY_ED25519_PUBLIC_KEY_BASE64="<32-byte-ed25519-public-key-base64>"
crates/target/debug/runx history <receipt-id> --json

Next

  • Use crates/target/debug/runx new docs-demo to scaffold a native cli-tool skill (SKILL.md + X.yaml + run.mjs, zero npm deps). To cold-start without installing runx first, run npx @runxhq/cli new docs-demo; it downloads the launcher and runs the same native scaffold.
  • Compose the example into a graph with Skill To Graph.
  • Publish a ready skill from a public repo at https://runx.ai/x/publish, or run crates/target/debug/runx login --for publish followed by crates/target/debug/runx registry publish ... --registry https://api.runx.ai. See Publishing for the full local and hosted paths.
  • See API Surface for public package exports.