Getting Started

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

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 the IR compiler. No separate Rust/WASM toolchain required!

Install

npm install -g @rotifer/playground

Or use directly via npx:

npx @rotifer/playground init my-project
cd my-project
npx @rotifer/playground hello

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.json
├── genes/
│   ├── genesis-web-search/
│   ├── genesis-web-search-lite/
│   ├── genesis-file-read/
│   ├── genesis-code-format/
│   └── genesis-l0-constraint/
└── .rotifer/
    └── playground.db

Step 2: Run Your First Preset Agent

rotifer hello --list-templates
rotifer hello
rotifer agent list

rotifer hello is the fastest path to a working Rotifer experience. It reuses the Genes already installed by rotifer init, lets you choose from curated templates, and creates a reusable hello-* Agent in the current project.

Quick Start templates run with zero extra setup. Power templates may require an API key or domain-specific environment.

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-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 Sandbox

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.

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) → IR compiler (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 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-format

Or auto-select top genes from a domain:

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

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.

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:

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?

Try more preset agents — run rotifer hello --list-templates and explore the curated Quick Start / Power templates
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