Cloud Binding Guide

The Cloud Binding (introduced in v0.4) enables cross-developer gene sharing. Publish your genes to a shared registry, discover genes created by others, and compete in a global Arena.

Architecture

Developer A                           Cloud                           Developer B
┌──────────┐                    ┌──────────────┐                    ┌──────────┐
│ rotifer  │ ── publish ──→    │  Supabase    │    ←── search ─── │ rotifer  │
│ CLI      │ ←── search ───   │  ┌────────┐  │    ──→ install ──→ │ CLI      │
│          │ ── arena ──→     │  │ Genes  │  │    ←── arena ───   │          │
└──────────┘                   │  │ Arena  │  │                    └──────────┘
                               │  │ Auth   │  │
                               │  └────────┘  │
                               └──────────────┘

Getting Started

1. Authenticate

rotifer login

This opens your browser for GitHub OAuth authentication. After authorization, your credentials are stored locally at ~/.rotifer/credentials.json.

2. Publish a Gene

First, create and test your gene:

rotifer init my-project && cd my-project
rotifer wrap my-search --domain search.web
rotifer test my-search
rotifer compile my-search

Then publish:

rotifer publish my-search

3. Discover Genes

# Browse all genes
rotifer search

# Search by keyword
rotifer search "web search"

# Filter by domain
rotifer search -d search.web

# Filter by fidelity
rotifer search --fidelity Native

4. Install a Gene

rotifer install <gene-id>

The gene is downloaded to your local genes/ directory and is immediately ready for testing and Arena competition.

5. Cloud Arena

Compete with developers worldwide:

# Submit your gene to the global Arena
rotifer arena submit my-search --cloud

# View global rankings
rotifer arena list --cloud

# Watch live ranking changes
rotifer arena watch search.web --cloud

Cloud Configuration

Default Endpoint

All cloud commands connect to https://rotifer-cloud.supabase.co by default.

Custom Endpoints

For alternative deployments (e.g., self-hosted, regional):

Option 1: Environment variable

export ROTIFER_CLOUD_ENDPOINT=https://your-instance.supabase.co
export ROTIFER_CLOUD_ANON_KEY=your-anon-key

Option 2: Config file (~/.rotifer/cloud.json)

{
  "endpoint": "https://your-instance.supabase.co",
  "anonKey": "your-anon-key"
}

Multiple Endpoints

You can maintain connections to multiple cloud instances:

# Global endpoint (default)
rotifer publish my-gene

# China endpoint
rotifer publish my-gene --endpoint https://rotifer.cloud

Cloud API

The Cloud Binding uses a REST API built on Supabase PostgREST:

Endpoint	Method	Description
/rest/v1/genes	GET	List/search genes
/rest/v1/genes	POST	Publish a gene
/rest/v1/genes?id=eq.{id}	GET	Get gene by ID
/rest/v1/arena_entries	GET	List Arena rankings
/rest/v1/arena_entries	POST	Submit Arena entry
/storage/v1/object/gene-wasm/{path}	POST	Upload WASM binary
/storage/v1/object/public/gene-wasm/{path}	GET	Download WASM binary

Authentication is via Bearer token in the Authorization header.

Data Model

Gene Registry

Field	Type	Description
id	UUID	Auto-generated identifier
owner_id	UUID	Publishing user’s ID
name	text	Gene name
domain	text	Functional domain
version	text	Semantic version
fidelity	text	Native / Wrapped / Hybrid
phenotype	jsonb	Full phenotype metadata
wasm_path	text	Storage path for WASM binary
downloads	bigint	Download count
published	boolean	Visibility flag

Arena Entries

Field	Type	Description
gene_id	UUID	Reference to gene
domain	text	Competition domain
fitness_value	float	F(g) score
safety_score	float	V(g) score
total_calls	integer	Evaluation count

Security

• Row Level Security (RLS) — Users can only modify their own genes
• PKCE OAuth — Secure token exchange (no client secrets in CLI)
• WASM Storage — Public read, authenticated write
• Input Validation — Server-side schema validation via PostgREST

Troubleshooting

”Not logged in” error

rotifer login  # Re-authenticate

”Gene not found” on install

The gene ID is a UUID. Make sure you’re using the full ID from rotifer search.

Slow uploads

Large WASM files (>1MB) may take time to upload. Consider optimizing your gene’s bundle size by:

• Minimizing dependencies
• Using tree-shaking in the compilation pipeline
• Splitting large genes into smaller, composable units