Runtime Capsule Development
Capsules are the fundamental unit of execution in ElastOS Runtime. This guide covers the SDK, build targets, and manifest format for building your own capsules.
The elastos-guest SDK
The elastos-guest crate is the SDK that capsule developers link against. It provides the "syscall interface" between capsules and the runtime.
Key components:
| Component | Purpose |
|---|---|
CapsuleInfo | Capsule identity and metadata, populated from environment variables |
RuntimeClient | Communication interface with the runtime |
RuntimeRequest / RuntimeResponse | Structured messages between capsule and runtime |
LaunchConfig | Capsule launch configuration |
CapabilityConstraints | Requested capability scopes |
Capsule identity is established through environment variables set by the runtime at launch:
| Variable | Purpose |
|---|---|
ELASTOS_CAPSULE_NAME | The capsule's registered name |
ELASTOS_CAPSULE_ID | The capsule's unique instance identifier |
Build Targets
Capsules can target two execution substrates:
WASM (Recommended Default)
Target: wasm32-wasip1
WASM capsules run inside Wasmtime with WASI stdio for I/O. They are platform-independent, provide strong memory safety, and have fast startup times. This is the recommended default for most applications.
cargo build --target wasm32-wasip1 --release
Native (VM Capsules)
Native capsules run inside Firecracker or crosvm microVMs with KVM hardware virtualization. They get a full Linux environment. This is used for workloads that need stronger isolation or a full TUI.
cargo build --release
Native capsules require KVM support on the host and a rootfs image built via the runtime's build tooling.
Capsule Manifest
Every capsule includes a manifest that declares its identity, type, permissions, and resource requirements. The manifest is part of the capsule's signed artifact.
Key manifest fields:
| Field | Purpose |
|---|---|
name | Capsule name (unique identifier) |
version | Semantic version |
type | Capsule type: wasm, vm, data, agent |
entry | Entry point (WASM module path or native binary) |
permissions | Requested capability scopes |
resource_limits | CPU, memory, storage, and network limits |
microvm_config | VM-specific configuration (for VM capsules) |
dependencies | Other capsules this capsule requires |
Capability Requests
Capsules request capabilities through the RuntimeClient. The request specifies the resource, action, and desired scope. The shell capsule decides whether to grant the request, and the runtime enforces the resulting token.
The capsule never directly accesses resources. Every interaction goes through the runtime boundary:
- Capsule sends a
RuntimeRequestto the runtime - Runtime validates the capsule's existing capability tokens
- If a new capability is needed, the shell is consulted
- The runtime issues (or denies) the capability token
- The capsule uses the token to access the resource
Content Addressing
Every capsule version is identified by its CID (Content Identifier) -- a cryptographic hash of the capsule artifact. This means:
- Capsule identity is tied to content, not to a mutable name
- Tampering is detectable (the hash changes)
- Distribution is verifiable (fetch by CID, verify hash)
- Updates are explicit (new version = new CID)
Signed Artifacts
All capsule artifacts must be cryptographically signed before the runtime will load them. The signing pipeline uses Ed25519 keys and SHA-256 checksums.
The runtime verifies signatures before loading any capsule. If the signature is missing, invalid, or does not match a recognized publisher, the capsule is refused.