Getting Started

This guide walks you through the full Rotifer gene lifecycle — from project setup to running a multi-gene Agent pipeline.

Prerequisites

Node.js >= 20.0.0
npm >= 9
(Optional) Rust toolchain — only needed for Native WASM compilation via the NAPI bridge

v0.3 New: rotifer compile now auto-compiles TypeScript genes to Native WASM via Javy. No separate Rust/WASM toolchain required!

Install

npm install -g @rotifer/playground

Or use directly via npx:

npx @rotifer/playground init my-project

Step 1: Initialize a Project

rotifer init my-project
cd my-project

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

my-project/
├── rotifer.config.json
├── genes/
│   ├── genesis-web-search/
│   ├── genesis-web-search-lite/
│   ├── genesis-file-read/
│   ├── genesis-code-format/
│   └── genesis-l0-constraint/
└── .rotifer/
    └── arena.db

Step 2: Scan for Candidate Functions

rotifer scan genes/

The scanner detects exported functions and reports their compatibility with the gene standard.

Step 3: Wrap a Function as a Gene

Create a simple function:

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:

rotifer wrap hello-world

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

Step 4: Test in the L2 Sandbox

rotifer test hello-world

The test runner dynamically imports express(), generates input from the schema, validates the output, and verifies IR integrity if a compiled WASM exists.

Step 5: Compile to Rotifer IR

rotifer compile hello-world

v0.3: 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) → Javy (QuickJS→WASM) → Rotifer IR (custom sections)

You can also provide pre-compiled WASM directly:

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

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

Step 6: Submit to the Arena

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.

Step 7: View Rankings

rotifer arena list

Filter by domain:

rotifer arena list --domain search

Step 8: Create an Agent

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

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

Or auto-select top genes from a domain:

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

Step 9: Run the 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.

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

Submit to the Cloud Arena to compete globally:

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:

rotifer logout

What’s Next?

Write a Native gene — write in TypeScript and rotifer compile auto-compiles to WASM via Javy, 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 v2.9