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.
Prerequisites
Section titled “Prerequisites”- Node.js >= 22.18.0. On any Node older than 22.18,
npx @rotifer/playgroundwithout a version silently installs 0.20.0, the last release that still runs there; 0.21.0 and later require 22.18. Check withnode -vfirst. - npm >= 9
- (Optional) Rust toolchain — only needed for Native WASM compilation via the NAPI bridge
rotifer compileauto-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:
| Language | Path | Toolchain |
|---|---|---|
| TypeScript | Built-in (auto-detect index.ts) | Bundled — no setup |
| Rust | --wasm target/.../*.wasm | cargo + rustup target add wasm32-unknown-unknown |
| AssemblyScript | --wasm gene.wasm | npm 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.
Install
Section titled “Install”npm install -g @rotifer/playgroundOr use directly via npx:
npx -y @rotifer/playground@latest init my-agentcd my-agentnpx -y @rotifer/playground@latest hello --template quality-advisorStep 1: Initialize an Agent Workspace
Section titled “Step 1: Initialize an Agent Workspace”rotifer init my-agentcd my-agentYour 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.dbStep 2: Run Your First Preset Agent
Section titled “Step 2: Run Your First Preset Agent”rotifer hello --template quality-advisorrotifer agent listrotifer 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.
Step 3: Create Your First Gene
Section titled “Step 3: Create Your First Gene”If you want to build your own capability, start by wrapping a simple function as a Gene:
mkdir -p genes/hello-worldWrite 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:
rotifer wrap hello-worldThis generates phenotype.json — the gene’s metadata describing its domain, schemas, and fidelity.
Step 4: Test in the Sandbox
Section titled “Step 4: Test in the Sandbox”rotifer test hello-worldrotifer test hello-world --complianceThe 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.
Step 5: Compile to Rotifer IR
Section titled “Step 5: Compile to Rotifer IR”rotifer compile hello-worldAuto 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:
rotifer compile hello-world --wasm path/to/hello.wasmThe IR compiler injects Rotifer custom sections (version, phenotype, constraints, metering) into the WASM binary.
Step 6: Submit to the Arena
Section titled “Step 6: Submit to the Arena”rotifer arena submit hello-worldThe Arena runs an admission gate: tests the gene, computes fitness F(g) and safety V(g), and registers it if both pass.
Step 7: View Rankings
Section titled “Step 7: View Rankings”rotifer arena listFilter by domain:
rotifer arena list --domain searchStep 8: Create a Custom Agent
Section titled “Step 8: Create a Custom Agent”An Agent assembles a genome — a composition of genes from the Arena.
rotifer agent create greeter-bot --genes hello-world genesis-code-formatOr auto-select top genes from a domain:
rotifer agent create search-agent --domain search --top 2Step 9: Run the Custom Agent
Section titled “Step 9: Run the Custom Agent”Execute the genome as a sequential pipeline — each gene’s output feeds the next:
rotifer agent run greeter-bot --input '{"name":"World"}'Use --verbose to see intermediate inputs and outputs.
Step 10: Share via Cloud
Section titled “Step 10: Share via Cloud”Log in with GitHub, publish your gene, and let others install it:
rotifer login # GitHub OAuth (opens browser)rotifer publish hello-world # Upload to cloud registryrotifer search # Browse all published genesrotifer install <gene-ref> # Install someone else's geneSubmit to the Cloud Arena to compete globally:
rotifer arena submit hello-world --cloud # Submit to cloud Arenarotifer arena list --cloud # Global rankingsrotifer arena watch search --cloud # Live ranking updatesLog out when done:
rotifer logoutWhat’s Next?
Section titled “What’s Next?”- Try more preset agents — run
rotifer hello --list-templatesto see which presets can run here and what the others need - Write a Native gene — write in TypeScript and
rotifer compileauto-compiles to WASM via the IR compiler, or use Rust for hand-optimized WASM - Share via Cloud —
rotifer publishto share genes,rotifer installto use others’ genes - Explore composition —
Seq,Par,Cond,Try,Transformoperators (seetemplates/composition/) - Migrate MCP Tools — see
examples/mcp-migration/for before/after examples - Read the spec — Protocol Specification