01 / SCAFFOLD
Generate the repo
Run the CLI with a slug, your domain, and the entity type your community is built around (a comedian, a venue, a school). Generates the FastAPI app + schema + manifest in one shot.
A ceiba is a federated community node: a FastAPI service that publishes a manifest at /.well-known/ceiba.json, exposes an entity CRUD over /v1/<type>s, and joins the network. Four steps to go from idea to live node.
Run the CLI with a slug, your domain, and the entity type your community is built around (a comedian, a venue, a school). Generates the FastAPI app + schema + manifest in one shot.
The scaffold writes a ceiba.json at the project root and re-exports it at /.well-known/ceiba.json. Set the description, claimed entity types, and at least one payment rail if your community wants the economic layer.
Vercel, Fly.io, Render, a $5 VPS, a Raspberry Pi behind Tailscale Funnel. The protocol cares that you respond with a valid manifest — not where you live.
Submit your URL to the public registry. The validator fetches your manifest, checks it against the JSON Schema, and merges your entry — your ceiba is now discoverable from ceiba.to/ceibas.json.
/health, entity CRUD, /llms.txt. Bumping to L2 (claim flow + auth + edit history) or L3 (MCP server + Schema.org + cross-ceiba identity) is documented in the runbook.
State, May 2026: the GitHub template repo and the public registry are live. The Python CLI (pip install koa-gen-ceiba) is still pending publication to PyPI — for now, clone the template repo or open [email protected] for an early CLI build. Three ways to ship:
ceiba.json, deploy on Fly.io / Render / your VPS.koa-gen-ceiba before it lands on PyPI.This is what installation will look like the moment koa-gen-ceiba ships to PyPI:
# Install the CLI (pending PyPI publication) pip install koa-gen-ceiba # Bootstrap a new ceiba koa-gen-ceiba init my-ceiba \ --domain my-ceiba.example \ --display "My Ceiba" \ --description "What this directory tracks." \ --entity tattoo_artist \ --port 8240 # Run locally cd my-ceiba make install # venv + deps + SQLite schema make dev # uvicorn on :8240 --reload make smoke # curl the L1 endpoints # Validate against the canonical schema koa-gen-ceiba verify . # → fetches https://ceiba.to/ceiba.schema.json and validates ceiba.json # → expected: ✓ ceiba.json VALID # Print PR instructions to submit your node to the public registry koa-gen-ceiba register . # → opens git.koanet/koanet/ceibas-registry in your editor with the entry to PR
gh repo create my-ceiba --template koalabs-ai/ceiba-template cd my-ceiba # edit ceiba.json, deploy with `flyctl launch` or `render deploy`
curl -s https://my-ceiba.example/.well-known/ceiba.json | jq '.protocol_version, .roles_supported' # → "0.5" # → ["operator"] curl -s https://my-ceiba.example/health # → {"ok": true, "ceiba": "my-ceiba", "ts": "..."} curl -s https://my-ceiba.example/v1/stats # → {"entities": 0, "members": 0, "events": 0}
koa-gen-ceiba CLI is still pending publication to PyPI; for early access write to [email protected].
The reference implementation in production is La Cartelera (Mexico City live-comedy graph). Useful to point any agent or client at:
# self-describe curl -s https://lacartelera.app/.well-known/ceiba.json | jq '.compliance_level, .interconnections' # list entities of a type curl -s https://lacartelera.app/v1/comedians?limit=5 # health + stats curl -s https://lacartelera.app/health curl -s https://lacartelera.app/v1/stats # the MCP server for LLM agents curl -s https://lacartelera.app/mcp -H "Accept: application/json"