Runtime Architecture
ElastOS Runtime follows a microkernel design: the Carrier layer provides mechanism (enforces tokens), the Shell provides policy (decides who gets tokens). This separation means you can upgrade the policy brain (shell) without touching the trust base.
Three-Layer Architecture
| Boundary | Component | Role |
|---|---|---|
| Hardware primitive | PC2 OS / Hardware | Physical execution environment |
| Trust enforcement + cross-capsule authority | ElastOS Carrier | Mechanism: enforces capability tokens, manages cross-capsule communication |
| Single-capsule execution + policy decisions | AppCapsule Runtime | Policy: decides who gets tokens, executes capsule code in isolation |
┌─────────────────────────────────────────────────────┐
│ Runtime (elastos binary) — minimal trusted base │
│ Isolation · Signatures · Capabilities │
└─────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────────────────────┐
│ Shell (capsule with orchestrator capability) │
│ Permission prompts · Capsule orchestration │
└─────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────────────────────┐
│ Capsules (sandboxed apps and providers) │
│ WASM · microVM · data · zero ambient authority │
└─────────────────────────────────────────────────────┘
The runtime is the small trusted base (~5,000 lines of Rust). Everything above it -- including the shell -- runs as a sandboxed capsule with explicit capability tokens. Humans and AI agents use the same capability model.
The 10 Rust Crates
The runtime is pure Rust, zero C dependencies, zero OpenSSL.
| Crate | Layer | Purpose |
|---|---|---|
elastos-server | Carrier | Binary, Axum HTTP API, CLI entry point |
elastos-runtime | Carrier | Capabilities, tokens, handlers, messaging |
elastos-common | Carrier | Shared types (CapsuleManifest, CapsuleId) |
elastos-namespace | Carrier | Content addressing, CID to path resolution |
elastos-identity | Carrier | WebAuthn, credential store, did:key |
elastos-tls | Carrier | Self-signed CA + certs (rustls, zero OpenSSL) |
elastos-storage | Carrier | Storage backends (local, IPFS, cache) |
elastos-compute | Bridge | WASM sandbox (Wasmtime) |
elastos-firecracker | Bridge | MicroVM sandbox (Firecracker/KVM) |
elastos-guest | AppCapsule | SDK capsules use; the "syscall interface" |
The Carrier layer crates form the trust enforcement core. The Bridge layer crates connect to execution substrates (WASM and microVM). The AppCapsule layer provides the SDK that capsule developers link against.
URI Namespace System
The runtime introduces a unified addressing scheme with three default WebSpaces:
| WebSpace | Purpose |
|---|---|
https:// | Backward compatibility with the web |
localhost:// | Your PC2 host -- local state, files, sites, config |
elastos:// | The Elastos ecosystem -- content-addressed files, peer surfaces, provider contracts |
Apps request resources by URI; the matching provider capsule handles them. The app doesn't know or care where data physically lives. For the detailed path tables and provider routing flow, see Spaces & Namespaces.
Security Model
- Capability tokens are Ed25519-signed by the runtime and validated on every resource access (12 validation checks per invocation)
- Epoch mechanism provides mass revocation: incrementing the monotonic epoch counter invalidates all previously issued tokens at once
- Signed code: every capsule, every binary, every update is cryptographically signed. Tampered code is refused
- Audit trail: every action is logged in an append-only trail
- Content addressing: every capsule and piece of content is identified by its cryptographic hash (CID)