Skip to content

Getting Started

This guide walks you through the first three layers of the Rotifer experience: bootstrap an Agent workspace, launch a preset Agent with rotifer hello --template quality-advisor, then turn your own code into a Gene and compose a custom Agent.

  • Node.js >= 22.18.0. On any Node older than 22.18, npx @rotifer/playground without a version silently installs 0.20.0, the last release that still runs there; 0.21.0 and later require 22.18. Check with node -v first.
  • npm >= 9
  • (Optional) Rust toolchain — only needed for Native WASM compilation via the NAPI bridge

rotifer compile auto-compiles TypeScript genes to Native WASM via the IR compiler. No separate Rust/WASM toolchain required!

Choose Your Language (WASM-Native, Polyglot by Design)

Section titled “Choose Your Language (WASM-Native, Polyglot by Design)”

The Rotifer IR layer is language-agnostic by spec design (see Rotifer IR Specification §1.2). The CLI ships with a built-in TypeScript path (esbuild + Javy/QuickJS) and accepts pre-compiled WASM from any other language through rotifer compile --wasm:

LanguagePathToolchain
TypeScriptBuilt-in (auto-detect index.ts)Bundled — no setup
Rust--wasm target/.../*.wasmcargo + rustup target add wasm32-unknown-unknown
AssemblyScript--wasm gene.wasmnpm install --save-dev assemblyscript
Go--wasm gene.wasm (WASI ABI)tinygo
C / C++--wasm gene.wasm (STANDALONE_WASM)emscripten

Full recipes for each language live in the Polyglot Genes guide.

Terminal window
npm install -g @rotifer/playground

Or use directly via npx:

Terminal window
npx -y @rotifer/playground@latest init my-agent
cd my-agent
npx -y @rotifer/playground@latest hello --template quality-advisor
Terminal window
rotifer init my-agent
cd my-agent

Your Agent workspace now contains five Genesis genes pre-ranked in a live Arena:

my-agent/
├── rotifer.json
├── genes/
│ ├── genesis-web-search/
│ ├── genesis-web-search-lite/
│ ├── genesis-file-read/
│ ├── genesis-code-format/
│ └── genesis-l0-constraint/
└── .rotifer/
└── playground.db
Terminal window
rotifer hello --template quality-advisor
rotifer agent list

rotifer hello --template quality-advisor is the fastest path to a working Rotifer experience. It reuses the Genes already installed by rotifer init and creates a reusable hello-* Agent in the current Agent workspace. To explore other presets later, run rotifer hello --list-templates.

--list-templates shows which templates can run in this workspace. If you pick one whose genes are missing, hello exits 1 and says, gene by gene, what to do: it prints the rotifer install command to copy, or says the gene isn’t available yet. It never installs anything itself. Some templates also need an API key or domain knowledge.

Genes installed from Cloud or wrapped from ClawHub run in the sandbox when they are compiled. Since 0.38.0 hello refuses an uncompiled one unless you pass --trust-unsigned, and it says to run rotifer compile <gene> first. The genes rotifer init sets up are not affected. If a compiled external gene declares a credential from your environment, hello asks before running it in the sandbox; --allow-credentials KEY@host allows it for that run. A gene you let run on Node.js with --trust-unsigned is not asked about and can read every environment variable you have.

If you want to build your own capability, start by wrapping a simple function as a Gene:

Terminal window
mkdir -p genes/hello-world

Write genes/hello-world/index.ts:

interface Input { name: string; }
interface Output { greeting: string; }
export async function express(input: Input): Promise<Output> {
return {
greeting: `Hello, ${input.name}! Welcome to the Rotifer Protocol.`,
};
}

Wrap it:

Terminal window
rotifer wrap hello-world

This generates phenotype.json — the gene’s metadata describing its domain, schemas, and fidelity.

Terminal window
rotifer test hello-world
rotifer test hello-world --compliance

The test runner executes the gene — compiled genes run through the WASM sandbox with fuel metering and L0 gate checks; uncompiled genes fall back to Node.js import() with a warning. It generates input from the schema, validates the output, and verifies IR integrity. Add --compliance for structural compliance checks.

If you’re wrapping an existing directory instead of writing a fresh Gene by hand, rotifer scan genes/ is still the fastest way to discover exported functions before you wrap them.

Terminal window
rotifer compile hello-world

Auto TS→WASM compilation. If the gene has an index.ts or index.js and no pre-compiled gene.wasm, the compiler automatically runs:

index.ts → esbuild (strip types) → IR compiler (QuickJS→WASM) → Rotifer IR (custom sections)

You can also provide pre-compiled WASM directly:

Terminal window
rotifer compile hello-world --wasm path/to/hello.wasm

The IR compiler injects Rotifer custom sections (version, phenotype, constraints, metering) into the WASM binary.

Terminal window
rotifer arena submit hello-world

The Arena runs an admission gate: tests the gene, computes fitness F(g) and safety V(g), and registers it if both pass.

Terminal window
rotifer arena list

Filter by domain:

Terminal window
rotifer arena list --domain search

An Agent assembles a genome — a composition of genes from the Arena.

Terminal window
rotifer agent create greeter-bot --genes hello-world genesis-code-format

Or auto-select top genes from a domain:

Terminal window
rotifer agent create search-agent --domain search --top 2

Execute the genome as a sequential pipeline — each gene’s output feeds the next:

Terminal window
rotifer agent run greeter-bot --input '{"name":"World"}'

Use --verbose to see intermediate inputs and outputs.

Log in with GitHub, publish your gene, and let others install it:

Terminal window
rotifer login # GitHub OAuth (opens browser)
rotifer publish hello-world # Upload to cloud registry
rotifer search # Browse all published genes
rotifer install <gene-ref> # Install someone else's gene

Submit to the Cloud Arena to compete globally:

Terminal window
rotifer arena submit hello-world --cloud # Submit to cloud Arena
rotifer arena list --cloud # Global rankings
rotifer arena watch search --cloud # Live ranking updates

Log out when done:

Terminal window
rotifer logout
  • Try more preset agents — run rotifer hello --list-templates to see which presets can run here and what the others need
  • Write a Native gene — write in TypeScript and rotifer compile auto-compiles to WASM via the IR compiler, or use Rust for hand-optimized WASM
  • Share via Cloud — rotifer publish to share genes, rotifer install to use others’ genes
  • Explore composition — Seq, Par, Cond, Try, Transform operators (see templates/composition/)
  • Migrate MCP Tools — see examples/mcp-migration/ for before/after examples
  • Read the spec — Protocol Specification