capsule-fs: the coreutils capsule for Astrid OS agents

What capsule-fs is for inside Astrid OS

Astrid OS is a microkernel-style agent runtime. Its README frames capsule-fs as the coreutils package for that OS: the small set of primitives every agent needs before it can do anything useful with a workspace. The audience is therefore narrow and specific. It is for people writing or operating agents on Astrid OS who need those agents to touch files, and who want that access mediated by the kernel rather than granted as a raw host path.

The eight tools cover the operations you would otherwise improvise: read_file with optional start_line and end_line, write_file, replace_in_file, list_directory, grep_search, create_directory, delete_file and move_file. There is no rename, no copy, no stat, no chmod and no symlink tool. That is a deliberate-looking surface. An agent that can only express these eight operations is easier to reason about than one holding a general shell.

The design point is the airlock. The README states that all operations go through the VFS airlock, and that the kernel enforces path boundaries, copy-on-write isolation and capability checks before any host filesystem access occurs. So capsule-fs is not a filesystem implementation. It is a client of one, with the enforcement living elsewhere. If you are evaluating it, the interesting question is not what read_file does, but what the kernel refuses on its behalf.

How the VFS airlock shapes every call

The data flow is one-directional and mediated. An agent invokes a tool; the tool marshals the request through the airlock; the kernel applies its checks; only then does anything reach the host filesystem. Because the checks sit in the kernel, an agent cannot route around them by choosing a different tool. Path boundaries, copy-on-write isolation and capability checks apply uniformly across all eight operations.

Copy-on-write isolation is the piece with the largest practical consequence. An agent's writes are not necessarily the host's writes. That gives you a workspace where an agent can be wrong without being destructive, which is the whole reason to put a kernel between an agent and a disk.

Some of the constraints are visible in the tool table itself rather than in the kernel. replace_in_file rejects a match that occurs zero times or more than once, so it is an exact single-occurrence edit and not a regex substitution. grep_search is capped on depth, file count and match count, which bounds the cost of a runaway search. move_file carries a 10MB size limit, existence checks, and rollback on failure. Each of those is a place where the capsule chose a bounded operation over an open-ended one.

Building capsule-fs and calling read_file

The README gives one development command. The crate targets wasm32-unknown-unknown, which is consistent with a capsule that runs inside a host rather than as a native binary:

cargo build --target wasm32-unknown-unknown --release

The Cargo.toml confirms the shape of the thing. The library crate type is both cdylib and lib, the release profile sets opt-level = "z", lto = true, codegen-units = 1, strip = true and panic = "abort", and the package is marked publish = false. This is a component built to be loaded, not a crate you add to your dependency list.

For an actual first use, the tool surface is what you call. The README lists the argument names read_file accepts, including start_line and end_line for a line range, and the same table names the arguments for the other seven tools. The repository does not publish a request or response schema, so there is no example payload to copy. What you can rely on is the argument vocabulary: a path plus an optional line range for read_file, an exact string for replace_in_file, a pattern for grep_search, and a source and destination for move_file, which the README notes is capped at 10MB with existence checks and rollback on failure.

Where capsule-fs is the wrong tool

The clearest limitation is stated in the tool table. delete_file works on session-created files only, and the README notes there is no whiteout support yet. If your agent needs to remove a file that existed before the session, this capsule will not do it for you, and the phrasing suggests the gap is known rather than intended as a permanent boundary.

move_file has a 10MB size limit. That is fine for source files and configuration and wrong for datasets, logs or build artifacts. If your agent's job is moving large blobs around a workspace, this tool will refuse, and you will need a different mechanism.

replace_in_file rejecting zero or multiple occurrences is a constraint that reads as a safety feature and behaves as one, but it also means the tool cannot express an edit you might reasonably want: replace every occurrence, or insert where nothing yet matches. An agent doing bulk refactors will find it too strict.

Finally, the whole thing is scoped to Astrid OS. Outside that runtime there is no airlock to talk to. The package is publish = false and depends on astrid-sdk 0.7, and the Cargo.toml carries a note that local-path overrides exist while the per-domain WIT SDK is unpublished, to be removed once astrid-sdk 0.7.0 ships to crates.io. That comment describes a dependency situation still in motion. If you are not already on Astrid, capsule-fs gives you nothing.

How capsule-fs differs from giving an agent shell access

The obvious alternative is to hand the agent a shell, or a general-purpose filesystem API, and let it run commands. That is what most agent frameworks do, and the difference is not capability but where the boundary lives. With a shell, the boundary is the sandbox or container the process runs in, plus whatever policy you wrap around it. With capsule-fs, the boundary is the kernel airlock, and every one of the eight tools goes through it.

The practical consequence is that the tool list is the policy. An agent holding capsule-fs cannot delete a pre-existing file because delete_file will not do it, not because a rule said no. An agent cannot move something over 10MB because move_file will not do it. An agent cannot exhaust a search because grep_search is capped. Compare that to a shell, where the equivalent guarantees require you to reason about every command the agent might construct.

The trade is expressiveness. A shell can do anything a shell can do, and this capsule can do eight things. If your agent needs to compile, pipe, or chain operations, capsule-fs is the wrong layer and you want a build or exec capsule alongside it. The README describes capsule-fs as the coreutils package, which is the right mental model: coreutils is not a shell either.

Version, licence and what upgrades will cost

The repository ships two releases: v0.1.0 on 2026-06-14 and v0.2.0 on 2026-07-09. The last push to the default branch was on 2026-07-09, which is the same day v0.2.0 was tagged. The Cargo.toml version is 0.2.0, matching the tag. The repository is not archived.

Because the package is publish = false, you do not upgrade it by bumping a version in your Cargo.toml. You rebuild the capsule and redeploy it. The command is the same one the README gives, and the release profile is tuned for size rather than build speed, so expect the build to take a while.

The dependency comment in Cargo.toml is the upgrade cost worth flagging. It says local-path overrides are in place while the per-domain WIT SDK is unpublished, referencing a branch and noting they will be removed once astrid-sdk 0.7.0 ships to crates.io. That means the current build depends on a path override against an unpublished SDK. When that changes, your build setup changes with it. Check the Cargo.toml and the referenced migration guide before pinning anything.

On licensing, the README badge and the repository files disagree in a way worth noticing. The badge says MIT OR Apache-2.0, the README text says dual-licensed under MIT and Apache 2.0, and both LICENSE-MIT and LICENSE-APACHE are present at the top level. The repository metadata, however, lists Apache-2.0 alone. If the distinction matters to your organisation, read both licence files rather than the metadata field. This is not legal advice.

Editorial conclusion

Adopt capsule-fs if you are building or running agents on Astrid OS and want their filesystem access to pass through the kernel's VFS airlock rather than a host path you hand them directly. Do not adopt it as a general-purpose file library, and do not adopt it if you are not on Astrid OS: the crate is marked publish = false and depends on astrid-sdk 0.7, so it is a capsule, not a standalone utility. Before you build anything on it, verify which Astrid SDK version your toolchain resolves, whether your agent runtime already supplies an equivalent filesystem capsule, and whether your workflow needs deletion of files the session did not create, since the README states delete_file is limited to session-created files and has no whiteout support yet.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. unicity-aos/capsule-fs on GitHub