Agent Commands
Agents are autonomous entities that use genes to perform tasks. An agent has a genome — a set of genes it can invoke — and automatically selects the fittest gene for each task from the Arena.
rotifer agent create
Section titled “rotifer agent create”Create a new agent with a genome composed of selected genes.
rotifer agent create <agent-name> [options]Arguments:
| Argument | Required | Description |
|---|---|---|
name | Yes | Agent name |
Options:
| Flag | Description |
|---|---|
-g, --genes <genes...> | Gene names to include in genome |
--composition <type> | Composition type: Seq (default), Par, Cond, Try, TryPool |
--par-merge <strategy> | Merge strategy for Par branches: first (default), concat, merge |
--domain <domain> | Auto-select top genes from this domain |
--top <n> | Number of top genes to auto-select (default: 2) |
--strategy <strategy> | Gene selection strategy (default: greedy) |
--memory-quota <size> | The agent’s memory quota: a number with KB, MB or GB, e.g. 50MB (default: 10MB). See Memory API. |
Lifecycle states:
Initializing→Active→Terminated
The agent is automatically activated upon creation.
Examples:
# Sequential pipeline (default)$ rotifer agent create search-agent --genes web-search code-format ✓ Agent 'search-agent' created Genome: web-search → code-format (Seq)
# Parallel execution with merge$ rotifer agent create multi-search --genes web-search doc-search --composition Par --par-merge concat Genome: web-search ∥ doc-search (Par)
# Conditional branching$ rotifer agent create smart-agent --genes fast-search deep-search --composition Cond Genome: fast-search / deep-search (Cond)
# With a larger memory quota$ rotifer agent create my-agent --genes hello-world --memory-quota=50MB ✓ Agent 'my-agent' created Memory quota: 50 MBrotifer agent list
Section titled “rotifer agent list”View all registered agents and their states.
rotifer agent listOutput columns:
- ID — Unique agent identifier
- Name — Agent name
- State — Lifecycle state (Initializing / Active / Terminated)
- Genome — Number of genes in genome
Example:
$ rotifer agent list ┌──────────────┬──────────────┬────────┬────────┐ │ ID │ Name │ State │ Genome │ ├──────────────┼──────────────┼────────┼────────┤ │ agent-abc123 │ search-agent │ Active │ 2 │ │ agent-def456 │ file-agent │ Active │ 3 │ └──────────────┴──────────────┴────────┴────────┘rotifer agent memory
Section titled “rotifer agent memory”Look at and clean up what an agent has stored in its memory. Both commands act as the agent’s deployer, so the entries’ access policies do not limit them. See Memory API for what the entries are.
rotifer agent memory list <agent-name> [options]rotifer agent memory delete <agent-name> (--key <key> | --category <category>)list options:
| Flag | Description |
|---|---|
-c, --category <category> | Only entries of this category: PREFERENCE, PATTERN, CONTEXT or CACHE |
list shows each entry’s key, category, size, the gene that created it and when it was last updated, then how much of the agent’s quota is used. It never prints values.
delete options (give exactly one):
| Flag | Description |
|---|---|
-k, --key <key> | Delete the entry with this key |
-c, --category <category> | Delete every entry of this category |
delete prints how many entries it removed. Deleting a key that does not exist fails with MEMORY_NOT_FOUND. PREFERENCE entries are never cleared to make room, so this is how you free a full memory. Every deletion is recorded in the audit log.
Examples:
$ rotifer agent memory list my-agent --category PREFERENCE$ rotifer agent memory delete my-agent --category CACHE✓ Deleted 3 entries from my-agent's memoryrotifer agent run
Section titled “rotifer agent run”Execute an agent’s genome pipeline — the agent selects and invokes genes based on Arena fitness rankings.
rotifer agent run <agent-name> [options]Arguments:
| Argument | Required | Description |
|---|---|---|
name | Yes | Agent name to run |
Options:
| Flag | Description |
|---|---|
--input <json> | Input JSON for the pipeline (default: {"name":"world"}) |
--verbose | Show intermediate input/output for each step |
--no-sandbox | Force Node.js execution (skip WASM sandbox) |
--trust-unsigned | Allow Node.js execution for Cloud-installed or ClawHub-wrapped genes |
--allow-credentials <list> | Let external genes use these credentials from your environment, each only at its host: KEY@api.example.com,KEY2@other.example.com. Without it, an external gene that runs in the sandbox and declares a credential makes the command ask once at a terminal (default no), or exit 1 with credentials_not_granted elsewhere. This only covers sandboxed genes: a gene you let run on Node.js with --trust-unsigned is not asked about and can read every environment variable you have |
How it works:
- Load agent’s genome and composition configuration
- For each gene, prefer WASM sandbox execution if compiled (
gene.ir.wasmexists). A gene installed from Cloud or wrapped from ClawHub that is not compiled is refused on the Node.js path unless you pass--trust-unsigned— the same rule asrotifer run. The L0 gate still applies either way - Execute genes using composition algebra (Seq by default, or as configured)
- Return combined result with execution metrics (fuel, duration)
Composition operators available:
- Seq — Execute genes sequentially, piping output to next input
- Par — Execute genes in parallel, collect all results
- Cond — Conditional execution based on runtime predicate
- Try — Execute primary gene, fall back to secondary on error
- TryPool — Try multiple genes in pool, return first success
Example:
$ rotifer agent run search-agent --verbose Running agent 'search-agent'...
[1/2] genesis-web-search completed via WASM sandbox (23ms, fuel: 42000) Input: { "query": "rotifer protocol" } Output: { "results": [...] }
[2/2] genesis-code-format completed via WASM sandbox (12ms, fuel: 18500) Input: { "code": "..." } Output: { "formatted": "..." }
✓ Pipeline execution complete Genes Executed: 2 Duration: 35ms