Capsule Development

Capsule Development

A capsule is a Rust WebAssembly component that runs inside the Astrid Runtime sandbox shipped by Unicity AOS. The runtime routes IPC, enforces capabilities, mediates host access, and audits execution. Business logic belongs in capsules.

The manifest is part of the security boundary. Its [publish] and [subscribe] tables are the IPC access-control list: a topic that is not declared is denied. Capsules target wasm32-unknown-unknown, not WASI, and reach the host only through the audited SDK/WIT imports granted by the manifest.

Start from the supported scaffold

aos capsule new my-capsule
cd my-capsule

The generated project contains:

my-capsule/
├── .cargo/config.toml
├── rust-toolchain.toml
├── Cargo.toml
├── Capsule.toml
└── src/lib.rs

Do not begin from an old [[interceptor]] manifest or an ipc_publish / ipc_subscribe capability array. Those formats are obsolete.

Compiler target

.cargo/config.toml selects the capsule target and activates the SDK's custom randomness backend:

[build]
target = "wasm32-unknown-unknown"

[target.wasm32-unknown-unknown]
rustflags = ["--cfg=getrandom_backend=\"custom\""]

The getrandom_backend setting must live in the final capsule crate. Without it, dependencies such as UUID generators or randomized hash maps can fail to link.

Pin the toolchain and target in rust-toolchain.toml:

[toolchain]
channel = "1.94.0"
targets = ["wasm32-unknown-unknown"]
components = ["rustfmt", "clippy"]

Cargo package

Use a cdylib and the current 0.7 SDK surface:

[package]
name = "my-capsule"
version = "0.1.0"
edition = "2024"
publish = false

[lib]
crate-type = ["cdylib"]

[dependencies]
astrid-sdk = { version = "0.7", features = ["derive"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"

[profile.release]
opt-level = "z"
lto = true
codegen-units = 1
strip = true
panic = "abort"

Capsule manifest

This minimal tool capsule exposes one hello tool: