Platform reference
The platform reference describes the system layer of Xema. It defines the typed objects, the capability-mediated invocation plane, the execution environments, and the installable software bundles (biomes) that humans, agents, workflows, and external apps all share.
This section is the public reference for the Xema platform — for org admins choosing what to install, for biome authors building extensions, and for integrators embedding Xema into their own products.
Quick Links
| Page | What it covers |
|---|---|
| Overview | What Xema is, the conceptual architecture layers, and the four Agent primitives |
| Objects | XemaObject, the typed universe, XVFS read path |
| Capabilities | Capability refs, the gateway, two-stage permission model |
| Connectors | Typed integration points, named multi-account connections, wallet credentials, OAuth flow, first-party connectors |
| Conversation channels | Telegram and Slack to durable agent sessions: channel accounts, coalesced replies, the sandboxed default agent, resending uncertain replies |
| Biomes | The installable software bundle, the seven-state lifecycle, the install flow |
| Execution Environments | The nine built-in environments, the reach ceiling, environment grants |
| Spaces | The seven-level SpaceRef hierarchy, URI grammar, data classification, re-scoping |
| Execution Contexts | The per-invocation envelope; what flows where |
| Policy | PolicyDecision shape, the closed obligation set, route hints, credential selection, approval flow |
| Permissions & Access | The whole access model — capabilities, grants, roles, teams, agent reach tiers, auto-grant |
| Profiles | Named grant bundles attached to subjects — planned, not implemented |
| Runners | The runner kinds, execution targets, enrollment ceilings, attestation, push vs pull, the selector |
| Controllers | Reconciliation loops, desired vs observed state, error categories |
| Service Registry | Service discovery + @InjectService(name) |
| Hook plane | Admit, transform or defer an operation before it commits |
| Process topology | Own process or composed process, and what it means for biome code |
| Distributed init | Design, not yet available: kernel join, runtime registration, permissions as data |
| Decisions | The one primitive for a human choice: approvals, consent, questions |
| Governed web access | The audited door to the public web: page fetch, search, reach-tier gating, the untrusted-content envelope |
| MCP and Capabilities | The six meta-tools + external MCP federation |
| Developer Annotations | @XemaResource / @XemaRoute + convention inference |
| CLI | The global xema CLI — install, commands, workflows |
| Xema-as-Code | Declarative provisioning — xema.yaml, the Terraform provider, the managedBy ownership model |
| Public exposure and CORS | Which public API routes the gateway serves on which host, and which browser origins may call them |
| Skills | Skill bundles, Space ownership, authoring and slash commands |
| Agent Composition | Recursive agent tree, agent lifecycle, Model Resolution Matrix |
| Shell | The unified command surface, WebSocket protocol, sandbox terminal |
| Canopy | The universal agent: conversations and threads, Tier A and Tier B, autonomy levels, consent and standing grants |
| Store | The four Store capabilities, listing lifecycle, submission and review flow (the Store is a catalogue; installs go through biome lifecycle) |
| Editions | The six editions that ship, what each can and cannot do, the three installation classes, and how to choose one |
| Versioning | Draft vs published, rollback as a pointer flip, lockfile shape, capability auto-bump |
| Apps | App model, delegated sessions and the signing key ring, audience policies, ingress caps, embed snippet |
| Design System Builder | Agent-authored design systems: components, tokens, docs, pipeline handoff and publication |
| Document Buddy | Co-authoring A4 Markdown and rich documents with an agent: tracked changes, templates, design systems, the Presenter Coach |
| Topology | The project manifest as a live map of services, resources, integrations and history |
| Resource Governance | Resource inventory, usage ingest, admission, cost inputs and the release plane |
| SDK / Getting Started | Author your first biome with the xema CLI |
| Manifest Reference | Generated, field-by-field contract for the current xema-biome.json schema |
| SDK / Contributions | Authoring the Contribution Protocol — *.contribution.json files |
| SDK / Lifecycle Hooks | onInstall, onUninstall, onUpgrade, onEnable, onDisable — declared, not yet invoked |
| SDK / Backend I ship | Component-based service, worker, job, adapter, content, and web artifacts |
| SDK / Storage | Declared collections, isolation, uninstallPolicy |
| SDK / Publishing | The four publishing transitions, bundle format, signing intent |
| SDK / UI I contribute | HostExtensionSlots, route contributions, nav registry |
| SDK / Events I consume | Per-service event consumers, CloudEvents envelope |
| SDK / Testing | Manifest validation, capability-stub tests, lifecycle hook tests |
Getting Started
Read in order:
- Overview — orient yourself in the conceptual layers and the four-concept runtime model.
- Objects — see how everything in Xema is a typed
XemaObject. - Spaces — where data lives and who owns it.
- Execution Environments — the trust profiles capability calls run under.
- Execution Contexts — the per-invocation envelope.
- Policy — how every invocation is decided.
- Permissions & Access — the whole access model + the agent reach-tier ceiling.
- Capabilities — the invocation surface every call uses.
- Biomes — the lifecycle every installable bundle moves through.
- Skills — teach agents domain knowledge with folder bundles.
- Agent Composition — build multi-agent pipelines with the Model Resolution Matrix.
- Shell — the command surface humans and agents share.
- CLI — install and use the
xemabinary. - Xema-as-Code — provision the platform declaratively with
xema.yamlor Terraform. - SDK / Getting Started — author your first biome.
- Manifest Reference — reference for every current manifest field.