astrid

Astrid

Software should compose without inheriting each other's authority.

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 · Write a capsule · Read the Book · Release notes

Quick start

Install Astrid using one of the options below, then start an uncomposed runtime—no model account or distribution required:

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, 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 for repository, local-manifest, and signed-bundle inputs.

Start with the Book for the architecture or the Contributor 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.

…

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.

…

These mechanisms are real and independently tested. There is no unified interceptor orchestrating them. The five-layer gate chapter of The Astrid Book walks each layer against the source.

Install

Release archives:

Download the archive for your machine from GitHub Releases. Keep its companion binaries and platform files together when extracting it; add the extracted directory to your PATH.

The 2026.9.0 release targets are:

Windows is tested in CI but is not included in this release's archives. For migration and platform limitations, read the 2026.9.0 upgrade notes. Versions now follow year.month.patch.

Homebrew (macOS and Linux):

brew tap astrid-runtime/tap
brew install astrid

From crates.io (requires Rust 1.95+):

cargo install astrid

From source:

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.

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.

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:

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

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

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:

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.

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.

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](htt