Runtime Capsule Model
What Are Capsules?
Capsules are the fundamental unit of execution in ElastOS Runtime. As Anders (the CTO building this) puts it: "Capsules are like DLL files, called when needed by other capsules."
Every function of the computer is a separate capsule:
- Storage = a capsule that handles files
- Networking = a capsule that handles internet connections
- The desktop = a capsule that shows the UI
- Each app = its own capsule
- Each AI agent = its own capsule
Each capsule has its own code repository, its own version number, and can be updated independently. If you fix a bug in the media player capsule, nothing else changes.
Four Capsule Types
| Type | Substrate | UI Model | Example |
|---|---|---|---|
| Executable (WASM) | Wasmtime (wasm32-wasip1) | WASI stdio | Chat, providers |
| Executable (VM) | Firecracker/crosvm (KVM) | Full TUI/Linux | Shell, complex apps |
| Data | Content + declared viewer CID | Viewer renders | Markdown viewer, GBA emulator |
| Agent | LLM + memory + tools | elastos://ai/ | AI provider |
Executable (WASM) Capsules
WASM capsules run inside Wasmtime, targeting the wasm32-wasip1 platform. They use WASI stdio for I/O. This is the most portable execution mode -- WASM capsules run on any platform without modification.
WASM capsules are the recommended default for most applications. They provide strong memory safety, platform independence, and fast startup times.
Executable (VM) Capsules
VM capsules run inside Firecracker or crosvm microVMs using KVM hardware virtualization. They get a full Linux environment with TUI capabilities. This provides stronger isolation than WASM at the cost of requiring KVM support on the host.
VM capsules are used for workloads that need a full Linux environment or stronger isolation guarantees than WASM provides. Rootless microVM execution is verified on Jetson (aarch64) and WSL.
Data Capsules
Data capsules are content bundles with a declared viewer. A .ddrm.json descriptor references encrypted content (by CID) and declares which viewer capsule can render it. The runtime loads the viewer, grants it a scoped decrypt capability, and the content plays.
This model separates content from the application that displays it. The content is encrypted and addressed by CID. The viewer capsule receives only the capability it needs to decrypt and render that specific piece of content.
Agent Capsules
Agent capsules combine an LLM with memory and tools. They interact with the runtime through the elastos://ai/ provider contract and operate under the same capability model as every other capsule. An agent must hold valid, scoped tokens for every action it takes.
Working Capsule Architecture: P2P Chat
The currently working P2P chat demonstrates how capsules compose. Five capsules work together:
| Capsule | Type | Role |
|---|---|---|
localhost-provider | Provider | Encrypted file I/O |
shell | Shell | Policy decisions (currently auto-grant) |
did-provider | Provider | Ed25519 identity (did:key) |
peer-provider | Provider | P2P networking via Iroh/QUIC |
chat | App | TUI chat application |
Chat supports three execution modes on one runtime: native binary, WASM capsule, and microVM capsule. Cross-mode interop (native to WASM, for example) is verified.
Capsule Isolation
Every capsule runs in its own sealed environment:
- Zero ambient authority: capsules start with no access to files, network, or other capsules
- Capability-gated access: every action requires a valid, signed capability token
- Signed code: the runtime verifies cryptographic signatures before loading any capsule
- Independent lifecycle: each capsule can be installed, updated, and removed independently
- Content-addressed identity: each capsule version is identified by its CID, making tampering detectable