DSH HUB
HomePlugin StorePlugin PacksCommunityRankingsResourcesPublish Guide
Plugin source
Back to catalog

rotifer-protocol /

rotifer-protocol/rotifer-playground

Topic repository only

Local dev environment — Rust core + TypeScript CLI for gene development & Arena competition

★ 6 Stars1 Forks10 IssuesN/A Community rating0 Confirmed installs
View on GitHub
READMESource: main@2c839588

Rotifer Playground

CI npm License: Apache-2.0 Node.js Protocol Discord

Development environment for the Rotifer Protocol — WASM-Native, Polyglot by Design: build genes in TypeScript / Rust / AssemblyScript / Go / C, compete in Arenas, share via Cloud, and simulate agent evolution.

Status: v0.34.x — The experimental P2P node can now find genes across nodes, not only hear LAN announcements. rotifer network announce writes the gene to the DHT and republishes it every 12 hours; the announce list survives a daemon restart, and rotifer network withdraw stops republishing and serving a gene (copies other nodes already hold expire on their own within 48 hours). rotifer network search <query> matches keywords against announcements this node has heard and runs a Rotifer Cloud search alongside, as two separate lists; a v2 gene ID is looked up in the DHT, and the DHT is never searched by keyword. Records from other nodes are checked before they are stored, with per-publisher and total limits, and a peer that keeps breaking them is blocked for a while. Nodes started with --host 0.0.0.0 find each other on the local network by mDNS without --bootstrap (--no-mdns turns that off); the node is on libp2p 0.57, can connect through a relay or by hole punching, and enforces connection and memory limits. Gossip on topics without a registered validator is ignored. Heartbeats can carry a Cloud-issued proof of registration that peers check and use in GossipSub scoring; the Cloud issuing side is in this repository but not deployed. Breaking: nodes on 0.27–0.33 still connect and gossip with this version but no longer share its DHT, so upgrade your bootstrap node. There is no public bootstrap node or relay yet, and the P2P node stays off unless you start it. Still true from v0.33: agents have memory (spec §38) that survives genome changes, stored in .rotifer/playground.db with every change logged to .rotifer/audit.jsonl; Rotifer Cloud does not store agent memory yet; rotifer run checks input and output against the gene's schema (--no-validate turns that off). Still true from v0.32: Arena F(g) is on a 0–1 scale (ADR-346) and scores from earlier versions are not converted; arena submit --cloud uploads the tier that actually ran; Hybrid genes must use https, and every redirect hop is checked against their allowed domains. Still true from v0.30: F(g) is scored against the season median and stays estimated and outside the ranking until coverage and robustness are measured (planned for v1.0); every CLI path runs a gene with exactly the permissions its phenotype declares; publishing enforces spec §47.5 T1. See CHANGELOG.md for full release history. Internet-wide reach and L4 Collective Immunity are later milestones — see Implementation Status below.


Install

npm install -g @rotifer/playground

Or use directly via npx:

npx -y @rotifer/playground@latest init my-agent

Requirements: Node.js >= 22.18.0 (genes are TypeScript; the CLI relies on Node’s built-in type stripping to run them from source)


First Agent in Seconds

rotifer init my-agent && cd my-agent
rotifer hello --template quality-advisor

rotifer init bootstraps the local Arena and Genesis genes. rotifer hello --template quality-advisor is the recommended preset-agent entrypoint for a first run.


30-Second Demo

$ rotifer init my-agent

  Rotifer Protocol - Agent Workspace Initialization
  ───────────────────────────────────────────────────
✓ Agent workspace scaffolding created
ℹ Installing Genesis genes...
✓ 5 Genesis genes installed
✓ 1 starter gene installed for the recommended template (quality-advisor)

  Starter Genes
  ───────────────
  Name                        Domain            Fidelity
  ────────────────────────────────────────────────────────
  genesis-file-read           filesystem        Wrapped
  hello-world                 general           Wrapped
  gene-health-scanner         meta.diagnostics  Native
  genesis-l0-constraint       safety            Native
  genesis-web-search          search            Native
  genesis-web-search-lite     search            Native
  genesis-code-format         tooling           Native
ℹ 7 starter gene(s) across 6 domain(s)

  Agent workspace "my-agent" is ready!

One command scaffolds the workspace and ships the starter genes, including the one the recommended template needs. rotifer hello --template quality-advisor then turns them into your first preset agent.


Three-Act Experience (ADR-11)

Act 1 — Wow (30 seconds)

rotifer init my-agent && cd my-agent

Your workspace already holds the starter genes. rotifer arena list shows them in the local Arena, unscored until you evaluate one with rotifer arena submit <gene>. No configuration needed.

Act 2 — Aha (5 minutes)

rotifer hello --template quality-advisor # Run the recommended preset Agent
rotifer agent list                 # Inspect the generated hello-* agent

Bundled genes become a working preset agent in seconds.

Act 3 — Hooked (30 minutes)

Turn your own code into a gene, then build a custom agent:

# Wrap existing code as a gene
rotifer scan genes/                    # Discover candidate functions
rotifer wrap hello-world               # Wrap as a gene (generates Phenotype)
rotifer test hello-world               # Run sandbox tests (WASM sandbox for compiled genes)
rotifer test hello-world --compliance  # Run structural compliance checks
rotifer arena submit hello-world       # Submit to Arena (admission gate)
rotifer arena list                     # See your gene's ranking

# Write a gene in TypeScript — same language, zero learning curve
mkdir genes/my-search && cat > genes/my-search/index.ts << 'EOF'
export function express(input: { query: string }) {
  return { results: [`Found: ${input.query}`], total: 1 };
}
EOF

rotifer wrap my-search --domain search
rotifer compile my-search           # TS → JS → WASM → Rotifer IR
rotifer arena submit my-search      # Watch it climb the rankings
rotifer arena list --domain search # Compare against Genesis genes

# Create an Agent with a gene genome (supports Seq, Par, Cond, Try)
rotifer agent create search-bot --genes genesis-web-search my-search
rotifer agent create parallel-bot --genes web-search doc-search --composition Par
rotifer agent list

# Run the Agent — WASM sandbox execution preferred
rotifer agent run search-bot --input '{"query":"rotifer protocol"}'
rotifer agent run search-bot --no-sandbox  # Force Node.js fallback

rotifer compile auto-detects TypeScript genes and compiles them to Native WASM. No separate toolchain required.


Architecture

playground/
├── crates/
│   ├── rotifer-core/        Rust: types, sandbox, arena, algebra, fitness, storage
│   └── rotifer-napi/        Native bridge: Rust ↔ Node.js FFI
├── src/                     TypeScript CLI and supporting modules
│   ├── commands/            CLI command modules
│   ├── cloud/               Cloud Binding client (auth, API, types)
│   └── utils/               Config, display, native binding, IR compiler
├── genes/                   Bundled gene directories
├── supabase/                Cloud Binding self-hosting guide
├── templates/               Gene + composition scaffolds
└── tests/                   Unit + E2E test suites

Layers

Layer Technology Responsibility
CLI TypeScript + commander.js User interface, command routing, display
Bridge Native bridge (cdylib) Rust-to-Node.js FFI binding
Core Rust + WASM runtime WASM sandbox (Direct + WASI), Arena engine, Algebra executor, Fitness computation, SQLite storage

CLI Commands

Run rotifer --help for the grouped command list. The commands below cover the main local, cloud, arena, and agent workflows.

Command Description
rotifer init [workspace-name] Initialize a new Agent workspace with Genesis genes
rotifer hello [--template <id>] Create and run a preset agent from curated templates inside a Rotifer Agent workspace. --list-templates shows which can run here; a template missing genes exits 1 and says what can be installed
rotifer scan [path] Scan for candidate genes and local skills
rotifer wrap <gene-name> Wrap a function or SKILL.md as a gene (offers to publish, default yes — see Publishing by default)
rotifer test [gene-name] Test a gene (WASM sandbox preferred, --compliance for structural checks)
rotifer compile [gene-name] Compile gene to Rotifer IR (auto TS→WASM)
rotifer run <gene-name> Execute a single local gene directly; input and output are checked against the gene's schema (--no-validate skips that)
rotifer list List local genes in the current Agent workspace
rotifer login Log in to Rotifer Cloud (OAuth)
rotifer logout Log out from Rotifer Cloud
rotifer publish [gene-name] Publish gene(s) to Rotifer Cloud
rotifer search [query] Search genes on Rotifer Cloud
rotifer install <gene-ref> Install a gene from Cloud (UUID, name, or content hash)
rotifer info <gene-ref> View gene details (local or Cloud)
rotifer stats <gene-ref> View download statistics for a gene
rotifer compare [gene-refs...] Compare 2–5 genes by reputation and downloads
rotifer reputation [gene-ref] View gene and creator reputation scores
rotifer versions <owner> <gene-name> View version history chain for a gene
rotifer arena submit <gene-name> Submit a gene to the Arena (--cloud for Cloud Arena)
rotifer arena list List Arena rankings (--cloud for Cloud Arena)
rotifer arena watch <domain> Watch Arena rankings live (--cloud for Cloud Arena)
rotifer agent create <agent-name> Create an Agent (--composition Seq|Par|Cond|Try|TryPool)
rotifer agent list List all agents
rotifer agent run <agent-name> Execute genome pipeline (WASM sandbox, --no-sandbox for Node.js)
rotifer genome export <agent> Export an agent's genome as a shareable Blueprint (.rgenome); aborts if the file would carry a credential or fail import's format checks
rotifer genome import <file> Rebuild an agent from a Blueprint: installs Native/Hybrid genes by exact version (--pinned) or picks Arena-verified substitutes that clear the F(g) and V(g) thresholds; --dry-run shows the plan
rotifer vg [path] V(g) security scan for gene/skill code
rotifer network P2P gene network commands (see rotifer network --help)
rotifer self-update Check for updates and upgrade Rotifer packages
rotifer config Manage global Rotifer configuration
rotifer whoami Show current authentication status

Publishing by default

rotifer wrap asks whether to publish the gene it just created, and the answer defaults to yes — pressing Enter uploads it to Rotifer Cloud:

Publishing is on by default — turn it off with 'rotifer config set default-publish false'
Publish 'my-search' to Rotifer Cloud? [Y/n]

Answering n keeps the gene local; rotifer publish my-search uploads it later. The default exists because a registry only helps people find genes that reached it, and the step most often skipped is the upload.

It asks rather than uploads, and it only asks when there is someone to answer:

Situation What happens
rotifer config set default-publish false (or ROTIFER_AUTO_PUBLISH=0) Never asks. rotifer publish still works.
No terminal — CI, a pipe, a script Never asks and never publishes, so a build that wraps genes does not upload them.
Signed out Never asks; points at rotifer login.
Native gene with no gene.ir.wasm Never asks; points at rotifer compile, which publishing would require anyway.

Publishing this way runs the same gates as rotifer publish: V(g) security scan, IR integrity, phenotype schema, secret scan, and dependency audit. A gene that fails them is not uploaded, and wrap still reports the gene as created.


Genesis Genes

Five pre-installed genes ship with every Agent workspace:

Gene Domain Fidelity Description
genesis-web-search search Native Demo: simulated multi-result search (example.com results, not a live search)
genesis-web-search-lite search Native Demo: simulated single-answer search (not a live search)
genesis-file-read filesystem Wrapped Read local files (L0 sandbox restricted)
genesis-code-format tooling Native Format source code (JSON, TS, etc.)
genesis-l0-constraint safety Native L0 sandbox constraint checker

Gene Composition (Algebra)

Genes can be composed using the Rotifer Algebra:

Operator Description Example
Seq Sequential pipeline Search → Format
Par Parallel with merge Search + Search-Lite, take first
Cond Conditional branch If query.length > 100 → Lite, else → Full
Try Fault tolerance Primary with fallback
Transform Map/transform Inner gene → mapper gene

See templates/composition/ for JSON examples.


Examples

The examples/ directory contains reference implementations and experiments:

Directory Description
examples/mcp-migration/ How to migrate MCP Tools into Rotifer Genes
examples/api-apocalypse/ API fault-tolerance experiment — baseline vs Rotifer agent with domain failover

Development

git clone https://github.com/rotifer-protocol/rotifer-playground.git
cd rotifer-playground

# TypeScript CLI
npm install
npm run build          # Build to dist/
npm test               # Run the TypeScript test suite (Vitest)
npm run lint           # Type-check and lint src/

# Rust Core (requires Rust toolchain)
cargo check -p rotifer-core
cargo test -p rotifer-core

# Full demo
bash demo.sh

Implementation Status

This project is in alpha. The table below shows the honest implementation status of each URAA layer.

URAA Layer Spec Name Status What Works What's Planned
L0 Kernel ~40% L0Gate pre-execution checks (domain, resource limits, filesystem) on every execution path, including genome steps and the Node.js fallback; audit log Per-gene permission policy, network check, EthicalBoundary, State Anchoring, Trust Anchor
L1 Synthesis ~70% WASM sandbox, IR compiler, TS→WASM compilation, native bridge Synthesizer interface, full WASI capability negotiation
L2 Calibration ~40% Schema validation, sandbox testing, --compliance checks Static analysis, controlled field trial
L3 Competition ~85% Arena ranking, F(g) multiplicative model, R(g) reputation, Cloud Registry, experimental P2P node (off by default: mDNS LAN discovery, gene announcements, DHT search) Public bootstrap and relay nodes, internet-wide P2P, hot-loading, retirement
L4 Collective Immunity 0% — Threat broadcasting, emergency rollback, cross-node consensus
Algebra Composition ~90% All 5 operators in Rust; CLI supports Seq/Par/Cond/Try DataFlowGraph

Key limitation: L4 depends on a mature L3 P2P layer. P2P is runnable today but experimental and off by default, and still lacks automatic peer discovery and internet-wide reach. Full L4 is targeted for v1.x.


Protocol Compliance

Targets Rotifer Protocol Specification (Frozen). See Implementation Status for detailed layer-by-layer coverage.

Depth Components Notes
Full Phenotype, AlgebraExpr, Fitness F(g), Arena Core gene lifecycle
Functional WASM Sandbox, L0 Gate, Reputation R(g), P2P HLT (LAN, experimental) L0 at ~40%, expanding
Simplified Agent Lifecycle, Gene Lifecycle, RotiferBinding MVP subset
Planned Internet-wide P2P HLT, Formal Verification, Cross-Binding Consistency, ZK Proofs, L4 Immunity Roadmap items

Changes driven by implementation feedback are proposed through the ADR process.


Roadmap

See CHANGELOG.md for detailed release history. Upcoming milestones:

  • Next — automatic peer discovery and internet-wide P2P reach
  • v1.0 — Stable release: L0-L3 complete, economic system, security audit
  • v1.x — L4 Collective Immunity

Community

  • Discord — Join the conversation
  • GitHub Discussions — Questions and proposals

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

Apache-2.0 with Rotifer Safety Clause

This project uses the Apache License 2.0 with an additional Rotifer Safety Clause that requires any deployment to either preserve the L0 Constraint Layer or clearly disclose modifications to it.


The Rotifer Protocol is alive.

—/ 5

No ratings yet

Manifest verification required

Commit 2c839588633e

Community comments

No comments yet. Be the first to write one.

DSH HUB

A community index for DSH plugins. Not an official GitHub or DeepSeek AI product.

CommunityResourcesAPIAbout