discover · compare · collections · requirements · contribute · feed · watching · stats · help with your tokens
astrid-runtime/astrid · source
Snapshot 0 · 2026-11-04T12:47:28Z · Rust · Apache-2.0
Content fingerprint
9c2b3cf3e0a7b6e2cb7e88d3e63c74eb2e6f0a8906ae702a6e4b79370db1a07dGitHub description at capture
Astrid is a portable, capability-secure operating system for composable software.
README at capture
# Astrid
**Software should compose without inheriting each other's authority.**
[](https://github.com/astrid-runtime/astrid/actions/workflows/ci.yml)
[](https://github.com/astrid-runtime/astrid/actions/workflows/codeql.yml)
[](#license)
[](https://www.rust-lang.org)
[](https://www.rust-lang.org)
[](https://github.com/astrid-runtime/book)
---
Astrid is an operating-system project for software built from WebAssembly
**capsules**. Today it runs as a portable user-space runtime on macOS and Linux;
the direction is a standalone operating system. This release is the hosted
runtime, not a bootable OS image.
Run components in a sandbox, connect them through typed interfaces, and give
each principal its own capabilities and durable state. Install, upgrade, and
remove capsules while the runtime is running.
Use it to build agent systems, tools, services, or your own distribution. Astrid
does not choose a product, model provider, agent loop, or user interface for you.
Agents make the problem urgent: a model can choose what to do, but that should
not make the model the authority that permits it. Astrid separates those jobs.
The same foundation serves software without an LLM—components can be replaced
and composed without putting application policy into the kernel.
- **Compose behavior:** capsules communicate through an event bus and versioned
interfaces; the kernel routes requests rather than owning application logic.
- **Make authority explicit:** filesystem, network, process, and IPC access are
checked at runtime boundaries, not entrusted to prompts.
- **Keep state portable:** content-addressed storage, deduplication, and recovery
back principal-owned data. Mount it through macOS FSKit or Linux FUSE.
[Get started](#quick-start) · [Write a capsule](#write-a-capsule) ·
[Read the Book](https://github.com/astrid-runtime/book) ·
[Release notes](CHANGELOG.md)
## Quick start
Install Astrid using one of the [options below](#install), then start an
uncomposed runtime—no model account or distribution required:
```bash
astrid --version
astrid start
astrid status
astrid capsule list
astrid stop
```
`status` reports the running daemon; a fresh uncomposed runtime has no product
capsules. `stop` shuts it down and retires its working state into
`astrid.volume`. Starting again restores the working projection.
Next, [build your first capsule](#write-a-capsule), or choose a distribution you
trust with `astrid init --distro <source>`. A distribution supplies the capsule
composition and configuration; Astrid does not select one implicitly. See
[initial setup](#initial-setup) for repository, local-manifest, and signed-bundle
inputs.
Start with [the Book](https://github.com/astrid-runtime/book) for the
architecture or the [Contributor Handbook](https://github.com/astrid-runtime/handbook)
to contribute.
## Why Astrid exists
Agent frameworks put trust in the prompt. Astrid puts it in the runtime. An agent is untrusted code
executing on your machine with access to your files, your network, and your credentials. Telling it
to behave is not a security boundary. An OS-grade boundary is.
- **Cryptographic capability model.** Every file path, network host, and tool is a signed ed25519
grant scoped to a resource pattern, principal-bound, expiry-checked, and globally revocable. No
grant, no access.
- **WASM sandbox with no ambient authority.** 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.
- **The kernel is dumb.** It instantiates an event bus, loads capsules, and routes IPC bytes under a
capability ACL. It has no LLM handles, no conversation state, and no tool registry. All
intelligence lives in capsules, so a capsule bug cannot corrupt shared kernel state.
- **Per-principal everything.** Each identity gets isolated capsule access, KV data, secrets, home
directory, quotas, and audit chain. One principal can never read another's namespace, and it fails
closed if the caller cannot be resolved.
- **Signed, hash-linked audit chain.** Each entry seals the hash of the one before it and is signed.
Break the chain and the tampering shows.
- **Live capsule lifecycle.** Install, upgrade, and remove capsules on a running daemon. No restart.
## How it works
Frontends (the CLI, the HTTP gateway, Discord, and so on) are **uplinks**: protocol clients that
connect to the daemon over a Unix domain socket and speak in IPC events. There is no `Frontend`
trait. An uplink publishes events and receives responses like any other bus participant.
```mermaid
flowchart TB
CLI[CLI] -->|IPC events over Unix socket| Kernel
HTTP[HTTP gateway] -->|IPC events| Kernel
Discord[Discord] -->|IPC events| Kernel
Uplinks[Other uplinks] -->|IPC events| Kernel
subgraph Runtime[Astrid]
Kernel[Kernel: astrid-daemon<br/>dumb event router<br/>event bus - capability ACL - audit chain - Wasmtime sandbox]
Capsules[WASM Component capsules: wasm32-unknown-unknown<br/>providers - orchestrators - tools - fs - http - sessions - registry - identity]
end
Kernel -->|capability-checked host calls<br/>astrid:* WIT ABI| Capsules
```
Capsules communicate exclusively through the bus. Each declares what it needs and what it provides
in a `Capsule.toml` manifest with typed `[imports]`/`[exports]` tables; the kernel resolves the
dependency graph by topological sort and boots capsules in order. Tools are an IPC convention, not 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:
`fs`, `io`, `kv`, `ipc`, `net`, `http`, `sys`, `process`, `approval`, `identity`, `elicit`, and
`uplink`. Guests import only what their manifest allows, and every call is capability-gated at the
boundary.
## The security model
Astrid's security is decomposed. There is no single gate every action funnels through. A capsule has
no ambient authority, and authorization is enforced by independent, per-area mechanisms, each
fail-closed and each enforced where the effect actually happens.
```mermaid
flowchart TB
Action[A capsule action] --> Sandbox[WASM sandbox<br/>no syscalls, file descriptors, or host memory<br/>external resources are capability-checked host calls]
Action --> Manifest[Manifest gate<br/>declared file, network, and process allow-list<br/>empty is deny-all; path traversal and SSRF defenses]
Action --> IPC[IPC ACL<br/>declared publish and subscribe topics only<br/>per-principal routing]
Action --> Capability[Capability token<br/>ed25519, principal-bound, scoped, expiring, revocable<br/>per-device tokens can be subset-scoped]
Action --> Approval[Approval gate<br/>once - session - always - deny<br/>allow always mints a token; local egress elicits consent]
Action --> OS[OS sandbox<br/>bwrap on Linux - seatbelt on macOS for native subprocesses]
Action --> Audit[Audit chain<br/>signed, hash-linked JSONL decisions and calls<br/>split per principal and independently verifiable]
```
These mechanisms are real and independently tested. There is no unified interceptor orchestrating
them. The [five-layer gate](https://github.com/astrid-runtime/book) chapter of The Astrid Book walks
each layer against the source.
## Install
**Release archives:**
Download the archive for your machine from
[GitHub Releases](https://github.com/astrid-runtime/astrid/releases). Keep its
companion binaries and platform files together when extracting it; add the
extracted directory to your `PATH`.
The current stable release, [v2026.10.0](https://github.com/astrid-runtime/astrid/releases/tag/v2026.10.0),
publishes these targets:
| Platform | Architectures | Filesystem frontend |
|---|---|---|
| macOS | Apple Silicon, Intel | FSKit on macOS 26+; signed app and extension approval required |
| Linux GNU | x86_64, ARM64 | FUSE |
| Linux MUSL | x86_64, ARM64 | FUSE |
Windows is tested in CI but is **not included in the release archives**.
For older runtime-layout migration and platform limitations, read the
[2026.9.0 upgrade notes](release/UPGRADING-2026.9.0.md); for changes in this
release, read the [2026.10.0 changelog](CHANGELOG.md).
Versions follow [year.month.patch](release/VERSIONING.md).
Existing self-managed installations can run `astrid update --check` to inspect
their signed channel, then `astrid update` to apply an available update.
Homebrew and Cargo installations are updated by their respective package
managers.
**Homebrew (macOS and Linux):**
```bash
brew tap astrid-runtime/tap
brew install astrid
```
**From crates.io (requires Rust 1.95+):**
```bash
cargo install astrid
```
**From source:**
```bash
git clone https://github.com/astrid-runtime/astrid
cd astrid && cargo build --release # binary at ./target/release/astrid
```
The core tools are listed below. Platform release archives additionally include
their filesystem provider and, on macOS, the signed AstridFS app and management
scripts. A Cargo install is not a substitute for that signed macOS bundle.
| Binary | Role |
|---|---|
| `astrid` | CLI uplink. Connects to the daemon over the Unix socket. TUI, headless mode, capsule and agent management. |
| `astrid-daemon` | The kernel process. Loads capsules, routes IPC, enforces capabilities, runs the sandbox. |
| `astrid-build` | Capsule compiler and packager. Builds to `wasm32-unknown-unknown`. |
| `astrid-emit` | Stdio-to-bus bridge for external hook producers. |
## Initial setup
`astrid init --distro <source>` fetches a *distro* (a curated capsule bundle), presents any selection
groups declared by that distro, and prompts for its required configuration. Secrets are stored per
principal in the secret store, never passed on the command line. `init` writes a `Distro.lock`
pinning every capsule by BLAKE3 hash, so the same explicit distro input reproduces the same fleet.
```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
```
When a distro includes an LLM provider, onboarding can discover that provider's live model list from
its `/v1/models` endpoint. If the distro also includes an agent loop, confirm that it is ready before
starting a session:
```bash
astrid doctor # daemon up? capsules ready? an LLM available?
astrid chat # interactive session; the daemon auto-starts on first use
astrid models # list the current provider's models (a registry-capsule verb)
```
### Headless and scripting
```bash
astrid -p "summarize the git log" # single prompt, prints and exits
git diff HEAD~1 | astrid -p "write a commit message" # stdin is appended to the prompt
astrid -p "fix all failing tests" --yes # auto-approve tool requests
astrid -p "continue" --session "$SID" # resume by id or name
```
### Daemon lifecycle
```bash
astrid start # persistent daemon (survives terminal close)
astrid status # PID, uptime, connected clients, loaded capsules
astrid ps # loaded capsules and their lifecycle state
astrid stop # graceful shutdown
astrid update # authenticate, verify, and install the latest release
```
An explicit `astrid start` is persistent. Automatically started MCP gateways
and ephemeral daemons instead follow client-connection lifetime: quiet connected
clients keep them alive, and they retire after the final client disconnects.
### Mount durable state
Once the platform filesystem frontend is installed and enabled, a principal can
mount its view through the CLI:
```bash
astrid start
mkdir -p /tmp/astrid-view
astrid --principal default storage mount --as default /tmp/astrid-view
astrid --principal default storage status /tmp/astrid-view
astrid --principal default storage sync /tmp/astrid-view
astrid --principal default storage unmount /tmp/astrid-view
astrid stop
```
Use an empty mountpoint. Principal views and the administrative runtime view
have different authority; mounting does not grant access to other principals.
The files live in Astrid's storage, backed by the host filesystem—not in a new
disk partition. Release binaries remain outside the runtime's mutable volume.
macOS archives include `macos/manage-macos-fskit.sh` for app installation and
enablement; follow its macOS permission guidance. Linux uses its FUSE frontend
and host FUSE setup, without Apple's signing or extension-approval steps.
## Per-principal isolation
Each principal (agent identity) is a fully isolated tenant: its own capsule access, KV namespace,
secrets, home directory, quotas, and audit chain. New principals inherit nothing by default.
```bash
astrid agent create ci-bot # clean-slate, least-privilege agent
astrid agent create staging --clone production # full profile + state replica
astrid agent modify ci-bot \
--add-capsule astrid-capsule-fs # grant access to a capsule's tools
astrid caps show ci-bot # inspect capability grants
astrid quota set -a ci-bot --memory 128MB # per-principal resource limits
astrid pair-device issue --scope use-only # scope a device token to a subset
```
Capsule access is enforced kernel-side at dispatch. A principal can only invoke capsules explicitly
granted to it, and two principals installing the same capsule bytes share one content-addressed
on-disk artifact while getting separate in-memory runtime instances.
## Write a capsule
A capsule is a WASM process described by a manifest. The scaffold generates a first-try-compiling
project targeting `wasm32-unknown-unknown`, plus an `AUTHORING.md` guide.
```bash
astrid capsule new my-capsule # scaffold Capsule.toml, Cargo.toml, src/lib.rs, .cargo/config.toml
cd my-capsule
astrid capsule build # compile and package
astrid capsule install . # hot-loaded into the running daemon, no restart
```
Capsule authors depend on [`astrid-sdk`](https://github.com/astrid-runtime/sdk-rust), which mirrors
the `std` module layout (`fs`, `net`, `process`, `env`, `time`, `log`) and adds Astrid modules
(`ipc`, `kv`, `http`, `hooks`, `uplink`, `identity`, `approval`). The `#[capsule]` proc macro
generates the WASM ABI boilerplate: exports, serialization, and dispatch for tools, commands, hooks,
and lifecycle entry points.
```rust
use astrid_sdk::prelude::*;
#[derive(Default)]
struct Weather;
#[capsule]
impl Weather {
#[astrid::tool]
fn forecast(&self, args: ForecastArgs) -> Result<Forecast, SysError> {
let key = env::var("WEATHER_API_KEY")?;
let body = http::get(&format!("https://api.example.com/wx?q={}", args.city))?;
Ok(serde_json::from_slice(&body)?)
}
}
```
Building capsules is a first-class workflow in Astrid. The Forge (`astrid capsule new` plus authoring
tools and runtime-served guidance) is the on-ramp; the direction is an agent that writes, builds, and
installs its own capsules within the capability sandbox.
Reproducible builds and deterministic tests are consumers of
[Muninn's verified computation memory](docs/astrid-forge-muninn.md): complete source and toolchain
closures become derivation inputs, so an unchanged fleet build is a verified lookup while install,
signing, and publication remain fresh authorized effects.
### Live capsule lifecycle
```bash
astrid capsule install @org/capsule-name # install and hot-load
astrid capsule update my-capsule # hot-swap the running instance
astrid capsule remove my-capsule # live-unload, no restart
astrid capsule list --verbose # installed capsules with capability metadata
astrid capsule tree # imports/exports dependency graph
```
## What's new in 2026.10.1
- **Native-tool readiness:** Linux setup now checks ordinary-user Bubblewrap
and FUSE prerequisites and explains repairs before approved tools fail.
Multiple Unix users can start their own runtimes on a shared host.
- **Workspace reliability:** macOS Node can resolve authorized script files,
and populated-workspace renames preserve pending content during the atomic
transaction.
- **Sandbox and dependencies:** native process grants no longer expose runtime
backing media; Rustls and Wasmtime include upstream security fixes.
See the [full 2026.10.1 changelog](CHANGELOG.md) for the exact fixes and
operational limits.
## What's new in 2026.10.0
- **Accountable user budgets:** operators can configure an optional shared WASM
fuel-rate budget per accountable user in `[resources]`, applied on restart.
Principal-level `astrid quota set --cpu-rate` remains separate.
- **Capsule update discovery:** `astrid capsule update --check --json` reports
available releases without installing them or granting new authority.
- **Audit evidence:** signed audit-head snapshots and paged exports make chain
history inspectable; opt-in v2 entries add deterministic CBOR and committed
fields while retaining existing v1 history.
- **Release and recovery work:** numbered dev-channel release candidates,
corrected update notices, and repairs to storage migration, native mounts,
nested capsule failures, and concurrent runtime work.
See the [full 2026.10.0 changelog](CHANGELOG.md) for
the exact changes and migration limits.
## Documentation
- **[The Astrid Book](https://github.com/astrid-runtime/book)** is the canonical reference: the
kernel, the capsule model, the host ABI, the bus, and the security model, grounded in the source
with file and line anchors. Start with [Getting Started](https://github.com/astrid-runtime/book)
to go from nothing to a working agent in a few minutes.
- **Operator guides** live in [`docs/`](docs/): the [unified config schema](docs/config.md),
[LLM model selection](docs/models.md), [distro signing](docs/distro-signing.md), the
[gateway deployment runbook](docs/gateway-deployment.md), and
[generating a gateway client](docs/gateway-client.md). Architecture programs include
[conservation of computation](docs/astrid-conservation-of-computation.md),
[Muninn](docs/astrid-muninn.md), [Huginn](docs/astrid-huginn.md), and the
[Refinery](docs/astrid-refinery.md).
## Development
```bash
cargo build --workspace
cargo test --workspace -- --quiet
cargo clippy --workspace --all-features -- -D warnings
cargo fmt --all -- --check
```
All crates enforce `#![deny(unsafe_code)]` except `astrid-sys` and `astrid-sdk`, where WASM FFI
requires it. Clippy runs at pedantic level and integer-overflow arithmetic is a lint error. Release
binaries for macOS and GNU/musl Linux (x86_64 and aarch64) are built on tag push and signed with keyless
Sigstore. Self-managed updates authenticate the exact archive and its pinned Astrid release-workflow
identity before independently checking the BLAKE3 manifest and extracting any bytes. Homebrew and
Cargo remain responsible for updates they install; signed SHA-256 manifests remain available for
their compatibility requirements. GitHub build-provenance attestations are published as additional
evidence and are not substituted for the updater's release-archive signature. See the
[self-update security model](docs/self-update-security.md).
## Contributing
Contributions are welcome. Astrid uses a tiered contributor system that protects security-critical
code while keeping the door open to new contributors. Every pull request must be linked to a GitHub
issue. See [CONTRIBUTING.md](CONTRIBUTING.md) for the issue-first workflow and tier descriptions.
Changes to any contract surface (the host ABI, the IPC protocol, the capability model, the manifest
schema, or the SDK public API) go through the RFC process in the
[RFCs repository](https://github.com/astrid-runtime/rfcs) before implementation.
## License
Dual-licensed under [MIT](LICENSE-MIT) and [Apache 2.0](LICENSE-APACHE), at your option.
Copyright (c) 2025-2026 Joshua J. Bouw and Unicity Labs.