Creator FAQ

CLI & Setup

How do I install the CLI?

npm install -g @rotifer/playground

Or run directly without installing:

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

Requirements: Node.js >= 20.0.0, npm >= 9.

For the fastest first-run inside an initialized project, run rotifer hello (or npx @rotifer/playground hello) to launch a preset Agent immediately.

How do I create my first Gene?

# 1. Initialize a project
rotifer init my-project && cd my-project

# 2. Fastest first-run (recommended)
rotifer hello

# 3. Write your Gene logic
# Edit genes/my-gene/index.ts:
# export async function express(input) { return { result: ... }; }

# 4. Wrap it (generates phenotype.json)
rotifer wrap my-gene --domain search

# 5. Compile to WASM (optional, for Native fidelity)
rotifer compile my-gene

# 6. Test it
rotifer test my-gene

rotifer hello is optional for Gene authoring, but it is the fastest way to confirm the project, Genesis genes, and Agent flow are working before you build your own capability.

See the Getting Started guide for a complete walkthrough.

How do I publish to Cloud Registry?

# 1. Log in via GitHub OAuth
rotifer login

# 2. Publish your Gene
rotifer publish my-gene

Your Gene will appear in the Gene Catalog and can be discovered via rotifer search.

How do I search and install Genes?

# Search by keyword
rotifer search "grammar"

# Install a Gene from the Cloud Registry
rotifer install grammar-checker

Installed Genes are placed in your project’s genes/ directory, ready to use.

Running Genes

How do I run a Gene?

There are three ways to run Native Genes:

1. Via Agent pipeline (recommended):

# Create an Agent with a genome
rotifer agent create content-checker --genes grammar-checker readability-analyzer

# Run the pipeline
rotifer agent run content-checker --input '{"text":"Your text here"}' --verbose

2. Direct import in TypeScript:

import { express as grammarCheck } from "./genes/grammar-checker/index.js";

const result = await grammarCheck({ text: "Check this text." });
console.log(result.score, result.issues);

3. Fan-out parallel composition — run multiple Genes on the same input and merge results. See tests/demo/content-pipeline-demo.ts for an example.

Can Wrapped Genes be executed?

No. Wrapped Genes have no express() function — they contain only metadata (phenotype.json) and a description (SKILL.md).

To make a Wrapped Gene executable, implement an index.ts file with an express() function, upgrading it to Native.

How does Seq pipeline composition work?

When an Agent has multiple Genes, they execute in sequential order (Seq composition):

Input → Gene 1 → Output₁ → Gene 2 → Output₂ → Gene 3 → Final Output

Each Gene’s output becomes the next Gene’s input. Adjacent Genes must have compatible schemas.

rotifer agent create my-pipeline --genes step1 step2 step3
rotifer agent run my-pipeline --input '{"data": "..."}'

What if input/output schemas don’t match between Genes?

The pipeline will fail at runtime. To solve this:

Ensure schema compatibility — design your Genes so that adjacent I/O schemas align
Write adapter Genes — create a small Gene that transforms one schema into another
Use fan-out composition — if Genes analyze the same input independently, run them in parallel instead of sequentially

How do I create an Agent?

An Agent is the carrier for Genes — it defines the execution order of a set of Genes (its genome).

# Create an Agent with multiple Genes
rotifer agent create my-agent --genes gene-a gene-b gene-c

# View the Agent's genome configuration
rotifer agent info my-agent

# Run the Agent
rotifer agent run my-agent --input '{"text":"Hello world"}' --verbose

Agent vs Gene:

A Gene is an atomic capability unit (one function)
An Agent is a composition of Genes — it decides which Genes run in what order
An Agent can carry 1–N Genes, connected through compatible schemas

See the Gene Development Guide for more.

Hybrid Genes

What is a Hybrid Gene?

A Hybrid Gene combines WASM safety with controlled network access. It can call external APIs (LLMs, databases, embeddings) through a Network Gateway that enforces:

Domain whitelisting — only pre-declared domains are accessible
Rate limiting — capped requests per minute
Timeouts — per-request timeout enforcement
Response size caps — truncation at a configurable byte limit

See the Hybrid Gene Development Guide for a complete walkthrough.

How do I create a Hybrid Gene?

rotifer init my-gene --fidelity Hybrid

This generates a phenotype.json with a network block. Edit allowedDomains to declare the APIs your Gene needs:

{
  "network": {
    "allowedDomains": ["api.openai.com"],
    "maxTimeoutMs": 30000,
    "maxResponseBytes": 1048576,
    "maxRequestsPerMin": 10
  }
}

In your express() function, use ctx.gatewayFetch instead of global fetch:

export async function express(input, ctx?) {
  const res = await ctx.gatewayFetch("https://api.openai.com/v1/...", { ... });
  return { result: await res.json() };
}

Why does rotifer publish fail with E0055 or E0056?

E0055 — Your Hybrid Gene’s network.allowedDomains is missing or empty. Every Hybrid Gene must declare at least one domain.

Fix: Add domains to phenotype.json:

"network": { "allowedDomains": ["api.example.com"] }

E0056 — A domain in allowedDomains resolves to localhost or a private IP (e.g. localhost, 127.0.0.1, 192.168.x.x). These are forbidden in published Genes.

Fix: Remove private/localhost domains from allowedDomains.

Can I use wildcard domains?

Yes. Use *.domain.com to allow all subdomains:

"allowedDomains": ["*.supabase.co"]

This matches abc.supabase.co and supabase.co. It does not match unrelated domains.

How do I handle API keys in Hybrid Genes?

Never hardcode API keys. Use environment variables:

const apiKey = process.env.OPENAI_API_KEY;
if (!apiKey) throw new Error("OPENAI_API_KEY not set");

Set them before running:

OPENAI_API_KEY=sk-... rotifer agent run my-agent --input '{}'

What happens if my Gene calls a domain not in allowedDomains?

The Network Gateway blocks the request immediately with a DOMAIN_BLOCKED error. The request is never sent — no network traffic leaves the machine.

Skill → Gene Migration

How do I migrate an existing MCP Tool to a Gene?

Migration is a progressive enhancement, not a tear-down:

# 1. Scan your project for migratable Skills
rotifer scan --skills

# 2. Auto-wrap into a Gene (generates phenotype.json from SKILL.md)
rotifer wrap my-tool --from-skill ./SKILL.md --domain search

# 3. (Optional) Implement express() for Native upgrade
# Edit genes/my-tool/index.ts

# 4. Compile and test
rotifer compile my-tool
rotifer test my-tool

What you can reuse: core business logic, inputSchema/outputSchema (maps directly to Phenotype), composition patterns (Workflow/Chain → Genome DataFlowGraph).

Troubleshooting

Why does rotifer publish fail with a 409 error?

A 409 Conflict means a Gene with the same name + version already exists in the Cloud Registry.

Fix: Bump the version field in your Gene’s phenotype.json, then publish again:

{
  "version": "0.2.0"
}

rotifer publish my-gene

How do I update a published Gene version?

Published Gene versions are immutable — you cannot overwrite an existing version. You must publish a new one.

# 1. After modifying your code, bump the version
# Edit phenotype.json: "version": "0.2.0"

# 2. Publish again
rotifer publish my-gene

Versioning strategy:

Patch (0.1.0 → 0.1.1) — bug fixes, no behavior change
Minor (0.1.0 → 0.2.0) — new features, backward compatible
Major (0.1.0 → 1.0.0) — breaking changes (outputSchema changed)

After publishing a new version, the Arena re-evaluates fitness. Old versions remain installable (via rotifer install [email protected]), but the latest version is installed by default.

How do I create an account / log in?

rotifer login

This opens a GitHub OAuth flow in your browser. After authorization, your session token is stored locally at ~/.rotifer/credentials.json.

rotifer compile fails — what should I check?

Common causes:

IR compiler not found — rotifer compile requires the IR compiler binary. Check it’s installed and on your PATH.
TypeScript errors — your index.ts must compile cleanly. Run npx tsc --noEmit to check.
No express() export — the compiler expects export async function express(input) as the entry point.

rotifer agent run errors with “Gene has no source file”

The Gene directory must contain one of: index.ts, index.js, or index.mjs. Check:

ls genes/my-gene/

If only phenotype.json and SKILL.md exist, the Gene is Wrapped (not executable). You need to implement index.ts with an express() function.

Is the Cloud Registry open source?

The API gateway design and database schema are documented in the protocol specification. The infrastructure runs on managed services (Supabase). The REST API is publicly accessible for searching and installing Genes.