astrid-capsule-fs: eight filesystem tools that only work through the kernel VFS airlock

Every tool call crosses the kernel VFS airlock before touching a host path

The important sentence in this project is not about any single tool. It is 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.

That design has a direct consequence for how you evaluate the crate. It is not a filesystem library you can import into a normal Rust program and point at `/tmp`. The package description calls it the core filesystem tools for the Astrid microkernel, and the crate builds as both a `cdylib` and a `lib`, which is the shape of a module the kernel loads rather than an application you ship.

The build target confirms it. There is exactly one command here:

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

WebAssembly, not a host executable. So before you budget anything, the first question is not whether the tools are good enough, but whether your runtime is the Astrid kernel at all. On any other host, none of the eight tools are reachable, whatever the code looks like.

delete_file only removes what the session created, and whiteout is still missing

The delete tool carries its restriction in its own description: session-created files only, no whiteout support yet.

Read that as a scope limit rather than a warning. An agent working in a copy-on-write workspace cannot remove a file that was already there when the session started, which means the common cleanup step of tidying a pre-existing directory tree simply is not available. If your workflow assumes an agent can tidy up after itself across the whole workspace, that assumption breaks here.

The whiteout gap compounds it. Whatever a delete needs to record so the underlying layer reflects the removal is not implemented, so the README gives no whiteout behaviour to reason about and no error text for a rejected delete. The only documented scope is the session-created case.

For an agent author this shapes the prompt, not just the code: deletion has to be scoped to files the session itself wrote, and any cleanup routine that walks a mixed tree needs a way to tell the two apart.

move_file refuses anything over 10MB and rolls back when it fails

Move is the tool with the hardest numeric limit in the set: a 10MB size limit, plus existence checks and rollback on failure.

The existence checks mean a move against a missing target fails rather than half-completing, and the rollback means a failed move is designed to leave the workspace as it was. Both are the right instincts for an agent that may retry.

The 10MB ceiling is the part to plan around. Nothing in this project explains whether that applies to the file being moved, to the operation as a whole, or to a temporary copy made along the way, and the README does not state the error message you get when a file exceeds it. Treat it as a hard stop and check sizes before issuing the call.

Practical consequence: moving build outputs, database files, or media is out of reach for this tool. If your agent needs relocation on larger artifacts, you need a different mechanism, and this crate will not tell you which one.

replace_in_file rejects zero or multiple matches instead of picking one

The edit tool will not guess. `replace_in_file` replaces an exact string match in a file, and it rejects 0 or more than 1 occurrences.

That is a deliberate trade: an ambiguous replacement in a file the agent did not write could rewrite the wrong call site, so the tool stops instead. The cost lands on the caller, who has to make the match unique.

The recovery path uses the other tools. `read_file` takes an optional line range through `start_line` and `end_line`, so the working pattern is to read the region, widen the match string until it is unique, and issue the replace again. An agent that tries the same string three times will fail three times, and the loop has to break on the read, not on retries.

Worth noting for prompt design: exact string matching means whitespace and formatting differences between what the model thinks the file contains and what is on disk turn into 0-occurrence failures.

grep_search caps depth, file count, and match count without reporting the cut

Recursive search here comes with three limits: a depth cap, a file count cap, and a match count cap.

Those caps are what keep a search from running away inside a sandboxed agent, and the kernel airlock is what keeps it from escaping one. The side effect is that a search which returns nothing may have stopped rather than finished.

This is the sharpest gap between the tool name and its behaviour. `grep_search` returning no matches is ambiguous between the string not being there and the walk hitting a cap first, and the README says nothing about how truncation is surfaced in the output. An agent that treats an empty result as proof of absence can conclude a symbol does not exist when the traversal simply stopped early.

So the caps belong in your instructions as well as your code. Narrow the directory before searching, and treat an empty result as a prompt to read a specific path rather than to declare the file missing.

The release profile optimizes for size and turns panics into process aborts

The `Cargo.toml` release profile is unambiguous about priorities: `opt-level` is `z`, LTO is on, `codegen-units` is 1, symbols are stripped, and `panic` is set to `abort`.

Every one of those choices points the same way, at a small artifact that a microkernel can load. The crate is on edition 2024 with a pinned `rust-toolchain.toml`, and it is marked `publish = false`, so it is built from a checkout rather than pulled from a registry.

A `panic` value of `abort` has a consequence worth flagging before you adopt it. There is no unwinding, so a panic inside a tool call takes the whole module down rather than returning an error to the caller. For an interactive tool that is harsh; for a sandboxed capsule inside a microkernel it may be the correct default, since recovery state is not something the module carries.

Also note the size over speed choice is stated in configuration only, with no note about which operations it affects. If a workload leans on `grep_search` across large trees, that tradeoff is worth measuring on your own data.

The build depends on an SDK the project expects to publish later

The dependency list is short: `astrid-sdk` at version 0.7 with the `derive` feature, `serde` with derive, and `serde_json`. The interesting part is the comment attached to that dependency.

It explains that local-path overrides are in place while the per-domain WIT SDK is unpublished, referenced as the `sdk-rust` feature branch `per-domain-wit`, and that the overrides will be removed once `astrid-sdk` 0.7.0 ships to crates.io. The comment points at `CAPSULE_MIGRATION_GUIDE.md`.

Two practical consequences. First, you cannot build this from crates.io alone today; you need the SDK source locally and the path override in place. Second, that migration guide is named in a comment but does not appear among the root files, which list `.cargo/`, `Cargo.lock`, `Capsule.toml`, `LICENSE-APACHE`, `LICENSE-MIT`, `rust-toolchain.toml`, and `src/`. Expect to ask the maintainers where it lives.

There is also a `Capsule.toml` at the root, so the capsule has its own manifest for the OS to load, separate from the Cargo package.

Three names for one crate, two releases, and a dual license

Before evaluating anything else, be aware you will meet this project under three labels. The repository path is `unicity-aos/capsule-fs`, the README heading and Cargo package name are `astrid-capsule-fs`, and the operating system it targets is Astrid, linked from the README as the Astrid OS repository.

Search and issue tracking will not line up cleanly, and a reader arriving from one name may not find the other.

The release history is short. `v0.1.0` landed on 2026-06-14 and `v0.2.0` on 2026-07-09, with the last push to the default branch dated 2026-07-09. The Cargo version matches the latest tag at 0.2.0. There is no homepage set for the repository.

Licensing is the friendliest part: the crate is dual-licensed under MIT and Apache 2.0, with copyright held by Joshua J. Bouw and Unicity Labs for 2025-2026. Two permissive licenses means you can vendor it into a commercial product without the copyleft obligations that would come with the GPL or AGPL, which is a reasonable position for infrastructure code.

Editorial conclusion

Use capsule-fs if you are building an agent inside Astrid OS and want read, search, and bounded write behaviour without a raw host filesystem handle. Do not reach for it as a general Rust filesystem crate, and do not assume the tool names cover normal coreutils: deletes are limited to files the session created, moves refuse anything over 10MB, and ambiguous replaces fail rather than guess. Before committing, confirm that the local astrid-sdk path override still matches your checkout, read the release notes between v0.1.0 and v0.2.0, and verify the kernel is enforcing the capability checks you are counting on.

Frequently asked questions

Official sources

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