cradle

A runtime for portable agents defined as folders. An agent is a directory: a SYSTEM.md or APPEND_SYSTEM.md plus optional model config, skills, extensions, and sandbox posture. cradle run <dir> reads the folder and launches the pi coding agent configured from it — sandboxed when the folder declares a posture, with a choice of backend: nono (host OS policy) or Docker Sandboxes (sbx, a microVM). Think of cradle as a pi agent switcher: one pi install, many agents, each described entirely by its own directory.

The folder is static, portable, and committable; runtime state (generated extensions, session history, the generated sandbox profile) lives outside it under ~/.cradle/. An agent folder is code — extensions run with the pi process's permissions — so treat a third-party folder like any repo you'd run.

cradle doctor              # check pi (required), nono/sbx/mise (recommended) on PATH
cradle run ./my-agent    # launch pi as this agent; sandboxed when sandbox/nono.json or sandbox/sbx.json exists
cradle run ./my-agent --sandbox-backend sbx   # run in a Docker Sandboxes microVM instead of nono
cradle run ./my-agent --offline       # block all outbound network
cradle run ./my-agent --dry-run       # print the write plan + command, do not spawn
cradle run ./my-agent -- -p "prompt"  # everything after -- is forwarded to pi

Install

Standalone binary to ~/.local/bin/cradle (macOS and Linux; no Bun required to run it):

curl -fsSL https://coryrylan.github.io/cradle/install.sh | bash

Or the npm package (the command is still cradle; Bun must be on your PATH):

npm install -g @coryrylan/cradle

Full install, dependency, and usage details are in the CLI README.

The agent folder

my-agent/
  SYSTEM.md          required*  replace pi's system prompt (role + instructions)
  APPEND_SYSTEM.md   required*  append to pi's system prompt (role + instructions)
  settings.json      optional   pi-native settings (model selection, packages)
  models.json        optional   pi-native custom provider definitions
  skills/            optional   markdown playbooks, loaded when relevant
  extensions/        optional   pi extensions: custom tools, commands, hooks
  sandbox/           optional   sandbox posture (nono.json, sbx.json)

* At least one of SYSTEM.md (replaces pi's default prompt) / APPEND_SYSTEM.md (appends to it) is required; a folder may ship both. Every supported file uses a pi-native or cross-tool-standard name, mirroring pi's own ~/.pi/agent/ layout — anything written for a personal pi config drops in unchanged. See ARCHITECTURE.md for the full folder-format spec and examples/ for runnable agents:

• examples/hello — minimal agent, locked offline to a local Ollama model.
• examples/browser — agent-browser + Chrome for Testing running sandboxed under nono.

This repo

Bun workspaces monorepo. Packages live under projects/.

• projects/cli — @coryrylan/cradle, the cradle CLI (bin: cradle). The runtime itself, built with Bun and TypeScript and compiled to standalone platform binaries.
• projects/docs — @coryrylan/cradle-docs, the Eleventy + NVIDIA Elements documentation site. Deployed statically (it also hosts install.sh and the platform binaries); not published to npm.

Common commands (run at root)

bun install          # install deps for all workspaces
bun run ci           # format + lint:knip + per-package ci (lint + build + test)
bun run format       # prettier check across the monorepo
bun run format:fix   # prettier write
bun run lint:knip    # knip across all workspaces (unused files / deps / exports)

Package-scoped scripts (build, test, lint, …) run inside the package — e.g. cd projects/cli && bun run build. See each package's README.md and the root CLAUDE.md for details.

License

MIT