# Astrid

> A capability-secure WebAssembly runtime where agent components get no ambient authority

- Category: Agents & Automation / Code Sandboxes & Isolation
- Language: Rust
- Licence: MIT OR Apache-2.0
- Repository: https://github.com/astrid-runtime/astrid
- Canonical page: https://ai-tldr.dev/tools/astrid/

## In short

Astrid is an operating-system project for software built from WebAssembly components it calls capsules. It sits in the Code Sandboxes & Isolation category of the Agents & Automation tools and is open-source, written in Rust and licensed MIT OR Apache-2.0. To get started: install with Homebrew.

## Overview

Astrid is an operating-system project for software built from WebAssembly components it calls capsules. It ships today as a portable user-space runtime for macOS and Linux — a daemon plus a CLI, not a bootable OS image — with a standalone operating system as the longer-term direction. Capsules run in a Wasmtime sandbox, talk to each other over an event bus through versioned typed interfaces, and can be installed, upgraded and removed while the daemon keeps running.

The design premise is that an agent is untrusted code running on your machine with access to your files, your network and your credentials, and that telling it to behave is not a security boundary. So authority is separated from intelligence: the kernel holds no LLM handles, no conversation state and no tool registry, and instead instantiates the event bus, loads capsules and routes IPC under a capability ACL. Every file path, network host and tool is a signed ed25519 grant that is scoped to a resource pattern, bound to a principal, expiry-checked and globally revocable — no grant, no access.

Isolation is per-principal rather than per-process: each identity gets its own capsule access, key-value data, secrets, home directory, quotas and audit chain, and a lookup that cannot resolve the caller fails closed. Actions are recorded in a hash-linked audit chain where each entry seals and signs the hash of the one before it, so tampering is detectable. Astrid deliberately does not pick a product, model provider, agent loop or user interface for you; a curated bundle of capsules, called a distro, supplies those choices and is pinned by BLAKE3 hash in a `Distro.lock`.

## What it does

- WebAssembly capsules run in Wasmtime with no syscalls, no file descriptors and no host memory — every external effect is a capability-checked host call over a WIT-typed ABI
- Signed ed25519 capability grants scoped to a resource pattern, bound to a principal, expiry-checked and globally revocable
- Per-principal isolation of capsule access, KV data, secrets, home directory, quotas and audit chain, failing closed when the caller cannot be resolved
- Hash-linked, signed audit chain in which each entry seals the hash of its predecessor
- Live capsule lifecycle: install, upgrade and remove capsules on a running daemon with no restart
- Content-addressed durable state with deduplication and recovery, mountable through macOS FSKit or Linux FUSE
- Distros — curated capsule bundles pinned by BLAKE3 hash in a Distro.lock so the same input reproduces the same fleet

## Getting started

Install the runtime, start an uncomposed daemon to confirm it works, then compose it by initialising a distro. A fresh uncomposed runtime carries no product capsules and needs no model account.

1. Install with Homebrew

   Homebrew is supported on both macOS and Linux.

```bash
brew tap astrid-runtime/tap
brew install astrid
```

2. Or install from crates.io or source

   A Cargo install needs Rust 1.95 or newer. Note that it is not a substitute for the signed macOS bundle, which ships only in the platform release archives along with the filesystem provider.

```bash
cargo install astrid

# or from source
git clone https://github.com/astrid-runtime/astrid
cd astrid && cargo build --release   # binary at ./target/release/astrid
```

3. Start an uncomposed runtime

   `status` reports the running daemon and `capsule list` shows what it loaded. `stop` shuts the daemon down and retires its working state into astrid.volume, which is restored the next time you start it.

```bash
astrid --version
astrid start
astrid status
astrid capsule list
astrid stop
```

4. Compose it with a distro

   `astrid init` fetches a curated capsule bundle, presents whatever selection groups it declares, prompts for its required configuration and writes a Distro.lock pinning every capsule by BLAKE3 hash. Secrets go to the per-principal secret store rather than the command line.

```bash
astrid init --distro @yourorg/your-distro          # repository distro
astrid init --distro ./Distro.toml                  # local manifest
astrid init --distro ./bundle.shuttle --offline     # signed bundle, no network
astrid init --distro @yourorg/your-distro --yes     # non-interactive defaults
```

5. Know the four binaries

   `astrid` is the CLI uplink that connects to the daemon over a Unix socket; `astrid-daemon` is the kernel process that enforces capabilities and runs the sandbox; `astrid-build` compiles and packages capsules to wasm32-unknown-unknown; `astrid-emit` bridges stdio from external hook producers onto the bus.

```bash
astrid          # CLI uplink (TUI, headless, capsule and agent management)
astrid-daemon   # kernel: capsule loading, IPC routing, capability enforcement
astrid-build    # capsule compiler and packager
astrid-emit     # stdio-to-bus bridge
```

## When to use it

- Run an agent's tools as sandboxed capsules so a prompt injection cannot reach a file, host or credential that was never granted
- Host several identities on one runtime and keep each one's data, secrets and quotas provably separate
- Produce a tamper-evident record of what an autonomous system actually did, via the signed hash-linked audit chain
- Ship a reproducible fleet of components as a hash-pinned distro that colleagues can install, upgrade and revoke without restarting the daemon