Runcastle

Getting started

Runcastle is a registry for AI agent workflows built on Sandcastle. Installing a workflow copies readable source files into your project — nothing executes, and you own the files afterward.

What is a workflow?

A workflow (the on-disk format is called a package) is a manifest file (workflow.json) plus a .sandcastle/payload directory, living in the author's public GitHub repository. The payload contains everything the workflow needs: the TypeScript entrypoint that calls Sandcastle's run(), prompt files, a Dockerfile, and a .env.example.

Distribution is shadcn-style: readable source files are copied into your project. There is no opaque dependency to trust — after install, the code is yours to read, edit, and version.

Inspect before you trust

A workflow is arbitrary code and prompts that agents will run against your repository with your API keys. Runcastle's job is not to make that safe — it can't be, fully — but to make everything inspectable, tamper-evident, and free of surprises. Before installing:

  • Read the workflow's files on its detail page — every file in the package is rendered read-only, exactly as it will be written to disk.
  • Check the disclosures block: host hooks, sandbox hooks, network access, and shell expansion are always shown prominently — never hidden behind a click. A mismatch between declared and detected behavior blocks publishing.
  • Check the env vars table so you know which API keys the workflow expects (it never touches your .env — you fill that in yourself).

Installing a workflow

npx runcastle add author/slug

The CLI walks through three steps, in order:

  1. Preview. A mandatory pre-write display: summary, required env vars, the full disclosures block, and the exact file plan (with diffs if files already exist). Nothing is written until you confirm.
  2. Verification. Every file is checked against SHA-256 checksums recorded at publish time. A force-pushed or edited repository cannot silently change what you receive.
  3. Write. Files are copied into .sandcastle/. That is all — the CLI writes files and prints text.

Nothing executes on install

runcastle add never runs code, never installs npm dependencies, and never touches your .env. Running the workflow is a separate, deliberate step you take after reading what was installed.

Versions and pinning

Every published version is immutable: a semver string pinned to a git commit SHA with per-file checksums. Installing author/slug resolves to the latest version; author/[email protected]pins a specific one. Because versions pin a SHA and the registry caches files at publish time, existing installs keep working even if the author's repository changes.

Namespaced installs

If your project already has a .sandcastle/ directory, the workflow is installed into .sandcastle/<slug>/ instead. Note that promptFile paths inside the installed entrypoint are package-root-relative — Sandcastle resolves them against your working directory, so authors are nudged to write namespace-safe paths.

The lockfile

Each install records what was written to .sandcastle/runcastle.lock.json: slug, version, pinned SHA, and per-file checksums. This lets future tooling (like runcastle update) diff cleanly between what you have, what you changed, and what a newer version ships.

Next steps