Rotifer Protocol

Posted on Mar 23 • Originally published at rotifer.dev

Your First Rotifer Gene in 5 Minutes

#ai #tutorial #webassembly #beginners

You're about to build your first Gene — a self-contained, evolvable unit of logic that can compete, propagate, and compose with other genes inside the Rotifer ecosystem. The whole thing takes about five minutes.

We'll create a simple greeting gene: give it a name, get back a personalized greeting. Tiny, but it will walk you through the entire gene lifecycle — from writing code to submitting it to the Arena.

Let's go.

Prerequisites

Node.js 20 or later (download)
A terminal (macOS Terminal, iTerm, Windows Terminal, etc.)

That's it. No Rust toolchain, no Docker, no cloud account. Everything else comes with the CLI.

Step 1: Install & Initialize

Install the Rotifer CLI globally:

npm install -g @rotifer/playground

Or, if you prefer not to install globally, use npx to scaffold a project in one shot:

npx @rotifer/playground init my-first-gene && cd my-first-gene

Either way, you now have the rotifer command available. Verify it:

rotifer --version

You should see something like @rotifer/playground v0.x.x.

Step 2: Write the Gene

Create the gene directory and its entry file:

mkdir -p genes/hello-world

Now open genes/hello-world/index.ts in your editor and paste the following:

interface HelloInput {
  name: string;
}

interface HelloOutput {
  greeting: string;
}

export async function express(input: HelloInput): Promise<HelloOutput> {
  const name = input.name?.trim() || "World";
  return {
    greeting: `Hello, ${name}! Welcome to the Rotifer ecosystem.`,
  };
}

Three things to notice:

express() is the entry point. Every gene exports an async express function — this is the contract Rotifer uses to invoke your logic.
Typed input and output. The interfaces define the gene's phenotype — what it accepts and what it produces. This schema is what makes genes composable.
Pure logic, no dependencies. A gene is self-contained. No imports, no side effects, no framework boilerplate.

Step 3: Wrap It

Now let Rotifer generate the gene's metadata — its phenotype.json:

rotifer wrap hello-world

You'll see output like:

✔ Analyzed genes/hello-world/index.ts
✔ Generated genes/hello-world/phenotype.json

Phenotype:
  domain:   general.greeting
  fidelity: Native
  inputs:   { name: string }
  outputs:  { greeting: string }

The wrap command introspects your code, extracts the input/output schema, and produces a phenotype descriptor. This is what the ecosystem uses to discover, compose, and evaluate your gene — without needing to read your source code.

Step 4: Test It

Run the gene locally with a test input:

rotifer test hello-world

Expected output:

🧬 Testing gene: hello-world

─── Test 1: default input ───
Input:  { "name": "Rotifer" }
Output: { "greeting": "Hello, Rotifer! Welcome to the Rotifer ecosystem." }
Status: ✔ PASS (3ms)

─── Summary ───
Total: 1 | Passed: 1 | Failed: 0

The test command runs your gene's express() function with sample inputs and validates the output matches the phenotype schema. You can also provide custom inputs:

rotifer test hello-world --input '{"name": "Alice"}'

Step 5: Submit to the Arena

The Arena is where genes compete. Submit yours:

rotifer arena submit hello-world

🏟️ Submitting hello-world to Arena...

✔ Phenotype validated
✔ Gene uploaded
✔ Evaluation complete

Arena Results:
  Gene:     hello-world
  Domain:   general.greeting
  F(g):     0.72
  Rank:     #3 of 5 in domain
  Status:   Active

Your gene is now live in the Arena!

The Arena evaluates your gene using the fitness function (F(g)) — a composite score based on correctness, resource efficiency, robustness, and utilization. Your gene now competes with others in its domain. If it's good enough, other agents can discover and adopt it through Horizontal Logic Transfer (HLT).

What Just Happened?

In five minutes, you walked through the full gene lifecycle:

Write → Wrap → Test → Submit

Here's what each step means in the Rotifer Protocol:

Step	What it does	Protocol concept
Write	Define logic in `express()`	Gene = modular, typed function
Wrap	Generate `phenotype.json`	Phenotype = discoverable interface
Test	Validate input/output locally	Calibration (L2)
Submit	Compete in the Arena	Competition & Exchange (L3)

Your gene is now a first-class citizen of the ecosystem. It has a typed interface, a fitness score, and a ranking. Other genes can compose with it, agents can discover it, and the selection pressure of the Arena will determine whether it thrives.

That's the Rotifer philosophy: genes earn their place through demonstrated fitness, not manual curation.

What's Next?

You've scratched the surface. Here's where to go from here:

Gene Development Guide — deep dive into express() patterns, error handling, and multi-output genes
Composition Patterns — chain multiple genes into pipelines and workflows
Cloud Publishing — publish your gene to the cloud registry so any agent in the world can use it

Deep Dive: See the full Getting Started guide for the complete 10-step walkthrough.

This article was originally published on rotifer.dev. Follow the project on GitLab or install the CLI: npm i -g @rotifer/playground.

DEV Community