astrid-runtime/astrid: a capability-secure WASM runtime for untrusted agents

The problem Astrid solves: authority as a kernel fact, not a prompt instruction

Most agent stacks ask the model to behave. Astrid's README states the opposite position directly: an agent is untrusted code running on your machine with access to your files, your network and your credentials, and telling it to behave is not a security boundary. The project is aimed at engineers who are already running third-party or model-generated code locally and want the operating system, not the prompt, to be the thing that says no.

A component in Astrid is modelled the way an OS models a process. Every ability is a WebAssembly capsule that can be composed with other capsules, granted only explicit authority, and replaced without widening its reach. The README is explicit that the project is independent of any particular product, model provider, agent loop, user interface or distribution. That independence is the design goal and also the main adoption cost, because it means nothing useful ships turned on.

The intended audience is narrow and identifiable: platform engineers building an agent runtime for a team or a product, security-conscious operators who need an audit trail they can verify, and people who have already been burned by a tool call that reached somewhere it should not have. If you are evaluating a chat application, this is not that.

Kernel, capsules and uplinks: the actual data flow

The architecture has three moving parts. The kernel, implemented as `astrid-daemon`, is deliberately small: it instantiates an event bus, loads capsules, routes IPC bytes under a capability ACL, runs the Wasmtime sandbox and records the audit chain. The README states it holds no model, no tool schema and no business logic. All intelligence lives in capsules, so the argument goes, a capsule bug cannot corrupt shared kernel state.

Frontends are uplinks, not a trait implementation. The CLI, the HTTP gateway, Discord and anything else connect to the daemon over a Unix domain socket and speak IPC events. The README notes there is no `Frontend` trait; an uplink publishes events and receives responses like any other bus participant. This is a cleaner boundary than the callback-style frontend interfaces common in agent frameworks, and it means a new interface is a client, not a plugin.

Capsules declare what they need and what they provide in a `Capsule.toml` manifest with typed `[imports]` and `[exports]` tables. The kernel resolves the dependency graph by topological sort and boots capsules in order. Tools are an IPC convention rather than a kernel concept: a tool capsule intercepts `tool.v1.execute.<name>`, and the kernel never sees a tool schema. The host ABI is the WebAssembly component model with versioned `astrid:*` WIT packages covering `fs`, `io`, `kv`, `ipc`, `net`, `http`, `sys`, `process`, `approval`, `identity`, `elicit` and `uplink`. Guests import only what their manifest allows.

The security model is decomposed on purpose, and the README says so plainly: there is no single gate every action funnels through, and no unified interceptor orchestrating the layers. Instead, independent mechanisms each fail closed where the effect actually happens: the WASM sandbox with no syscalls, file descriptors or host memory; a manifest gate where an empty allow-list means deny-all, with path traversal and SSRF defenses; an IPC ACL limiting publish and subscribe topics per principal; and ed25519 capability tokens that are principal-bound, scoped to a resource pattern, expiry-checked and globally revocable. The README cites a five-layer gate chapter in The Astrid Book that walks each layer against the source. If you are evaluating this for a security review, that chapter is the document to read, not the README.

Install Astrid and run a first daemon

The README gives three install paths. Homebrew is the shortest for macOS and Linux:

brew tap astrid-runtime/tap
brew install astrid

From crates.io, the README states Rust 1.95 or newer is required, which matches the `rust-version` key in the workspace manifest:

cargo install astrid

Building from source produces the binary at `./target/release/astrid`:

git clone https://github.com/astrid-runtime/astrid
cd astrid && cargo build --release

Installation places four binaries, but the README is clear that you only ever invoke `astrid`. The CLI is an uplink that connects to the daemon over the Unix socket; `astrid-daemon` is the kernel process; `astrid-build` compiles and packages capsules to `wasm32-unknown-unknown`; `astrid-emit` is a stdio-to-bus bridge for external hook producers.

The first real use is the quick start, and the important detail is the `--distro` argument:

astrid init --distro @yourorg/your-distro
astrid start
astrid status
astrid capsule list

The README states that the runtime does not select or bundle a product distro, so you must pass the name of one you trust, a repository, a local `Distro.toml`, or a signed `.shuttle` archive explicitly. `astrid init` fetches that distro, presents any selection groups it declares, and prompts for what it requires. After `astrid start`, `astrid status` should report the daemon running, and `astrid capsule list` is where you confirm which capsules actually loaded. Operators running an uncomposed runtime can skip `init` and start the daemon directly, which is the fastest way to see the kernel come up with nothing attached.

Where Astrid is the wrong tool

The runtime bundles no distro, and that is not a packaging oversight, it is the stated position. If you want to install one thing and immediately have a working agent with a model provider and a set of tools, Astrid gives you a kernel, a CLI and a capsule format. You supply the rest. That is a real cost measured in days, not minutes, and it is worth saying before someone spends an afternoon on it.

The decomposed security model is a trade-off in the other direction too. Five independent mechanisms that each fail closed are harder to reason about as a whole than one interceptor, and the README acknowledges there is no unified orchestrator. A reviewer asking "where is the one place access is decided" will not get a one-line answer. The compensating argument is that a single gate is a single point of failure, but you have to accept the review complexity to get the benefit.

Platform coverage is uneven by construction. The workspace includes `astrid-storage-provider-fskit`, `astrid-storage-provider-fuse` and `astrid-storage-provider-winfsp` as separate crates, which tells you storage is provider-specific rather than uniform. The README's install instructions lead with Homebrew on macOS and Linux and cargo elsewhere; it does not document a Windows install path. If Windows is a target, treat that as unverified until you read the storage provider crate and the container directory.

Finally, the capability model only constrains what capsules can reach. A capsule that has been granted file read access to a directory can read that directory. The grants are the design, not a bug, but it means the quality of your distro's manifest review is the actual security posture you end up with.

How Astrid differs from MCP-style tool servers and LangChain-style agent loops

The closest comparison is the Model Context Protocol server model, and the difference is where trust sits. An MCP server is a process your agent connects to; once connected, the tool it exposes is callable, and the boundary is whatever the server itself decides to enforce. Astrid's equivalent is a WASM capsule with no ambient authority, no syscalls and no file descriptors, where every external effect is a capability-checked host call over a WIT-typed ABI. The workspace even contains an `astrid-mcp` crate, so the project is aware of that ecosystem rather than dismissive of it. The distinction is not the protocol, it is that a capsule cannot do anything its manifest and its grants do not name.

Against LangChain-style orchestration, the difference is what the framework owns. Those libraries own the agent loop, the tool registry and often the conversation state, all inside the same process as your application. Astrid's kernel owns none of that: no LLM handles, no conversation state, no tool registry. The loop lives in a capsule, and a bug in it cannot touch shared kernel state. You lose the convenience of a single import that wires up a working agent, and you gain the ability to replace the loop without touching the runtime.

Both comparisons come down to the same question. If your threat model is a misbehaving prompt, existing frameworks are fine and cheaper. If your threat model is code you did not write running on a machine you own, the boundary has to be below the prompt, and that is the layer Astrid is built at.

Maintenance, releases and upgrade cost

The repository is not archived, and the last push was on 2026-07-20, which is recent enough that the project is being worked on. Releases v0.10.1 on 2026-07-17, v0.10.2 on 2026-07-19 and v0.10.4 on 2026-07-20 landed within four days of each other, so the release cadence around that date was fast. The workspace manifest carries a different version string, `2026.9.2`, and the crates are versioned together at that value, which suggests the workspace and the published binaries are not on the same numbering scheme. Check both before you pin anything.

Upgrade cost has a concrete shape here. Capsules build to `wasm32-unknown-unknown` against versioned `astrid:*` WIT packages, and the README states the host ABI is the WebAssembly component model with those versioned packages. A WIT package version bump is therefore a capsule rebuild, and `astrid-build` is the tool that does it. Live capsule lifecycle is documented as a feature: install, upgrade and remove capsules on a running daemon with no restart. That reduces operational cost but does not remove the rebuild step when the interface changes.

On licensing, the repository root contains both `LICENSE-APACHE` and `LICENSE-MIT`, and the workspace manifest declares `license = "MIT OR Apache-2.0"`. The crates.io metadata shown for the repository says Apache-2.0. Dual licensing under MIT or Apache-2.0 is the common Rust convention and is permissive, but the discrepancy between the repository metadata and the manifest is worth confirming against the LICENSE files themselves before you rely on either. This is not legal advice; read the files.

Editorial conclusion

Adopt Astrid if you run untrusted or third-party agent code on machines you care about and you are willing to write or vet a distro, because the security model only pays off when capsules are actually composed and granted. Do not adopt it if you want a batteries-included agent product with a model provider and tool registry wired in: the README states the runtime bundles no product distro, no LLM handles and no tool registry, so you would be building that layer. Before committing, verify three things against the source: that your target platform is covered by the storage provider crates (fskit, fuse, winfsp), that the daemon and CLI versions you install match (the workspace manifest and the released binaries move independently), and that the five-layer gate chapter in the Book matches the crates you are pinning.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes