Architecture overview

omnifs turns APIs and data sources into paths. The provider catalogue describes documented path surfaces. Existing tools can read mounted resources with ls, cat, grep, jq, find, and shell pipelines.

The design is simple at the surface and strict at the boundary: providers describe a filesystem projection; the host performs the privileged work.

The path is the interface

A path names the system, the resource, and the representation you want:

cat /omnifs/github/0xff-ai/omnifs/issues/open/42/title
cat /omnifs/docker/containers/by-name/postgres/state
cat /omnifs/arxiv/papers/1706.03762/paper.json | jq .title
cat /omnifs/dns/example.com/MX

There is no service client to initialize inside the calling program. The shell opens a file. The kernel routes that operation to the omnifs FUSE mount. The host resolves the path, checks cache, and asks the mounted provider for the missing piece.

Host and provider

The host owns the filesystem, credentials, cache, callouts, and runtime lifecycle. A provider is a wasm32-wasip2 component that owns domain projection: which paths exist, which objects they represent, and how canonical service payloads render as files.

shell tool
  │  open/read/readdir
  ▼
Linux FUSE mount
  │
  ▼
host runtime
  │  cache lookup, credential injection, callout execution
  ▼
WASM provider
  │  route matching, object load/render, effects
  ▼
API or data source

On macOS, the FUSE mount lives inside the Linux runtime container and you enter it with omnifs shell. Windows support and native host mounts outside Linux are outside the supported runtime path.

Operations, callouts, and effects

The provider WIT surface is operation-oriented. The host calls lifecycle and namespace functions such as initialize, lookup-child, list-children, read-file, open-file, read-chunk, resume, cancel, and on-event.

A provider operation either returns a final answer or suspends with callouts for the host to run. Callouts are request/response: HTTP requests, git handoffs, blob reads, archive access, and similar host-mediated work. They do not mutate host state by themselves.

The terminal return carries effects:

canonical: store upstream object bytes under a logical identity.
fs: materialize derived files and directories in the view cache.
invalidations: evict stale object or listing paths.

Effects are the mutation channel between provider and host. They are not background jobs and they are not ambient access.

Cache model

omnifs has three host-owned caches.

Cache	Role	Persistence
Object cache	Canonical upstream bytes keyed by opaque object identity	Durable
View cache	Derived filesystem records that tools read	Recreated on startup
Blob cache	Large bytes served by host handles, including archives and fetched blobs	Host disk

On a warm object read, the host can push cached canonical bytes back into the provider. The SDK renders the requested view from those bytes only if the pushed identity matches the route-derived identity. That keeps object meaning in provider code while letting the host own storage and invalidation mechanics.

Authority boundary

A provider has no ambient authority: no direct network, credentials, or arbitrary disk access except through host-mediated capabilities. GitHub can request api.github.com callouts and git repo handoffs because its manifest declares them. Docker can request the configured Unix socket. The db provider receives a read-only WASI preopen for the selected database file’s parent directory and opens the configured file inside it. Credentials stay with the host and are injected into approved callouts.