/omnifs
/omnifs
DOCS GITHUB CONTACT
/intro

/OMNIFS

open a /path, read the world.

omnifs lets you access the world through your filesystem. APIs and data sources become files and directories you can ls, cat, grep, pipe, and hand to an agent.

Reads land state on your machine. The first touch fetches an object once. The host stores it durably, renders every file from it, answers warm reads locally, and owns auth, caching, and egress for every provider. New systems attach as sandboxed Wasm providers built with the omnifs SDK.

omnifs shell
# read GitHub as files
# issues are files: list, count, grep, cat
/ $ ls /github/0xff-ai/omnifs
actions issues pulls repo
/ $ ls /github/0xff-ai/omnifs/issues/open | wc -l
47
/ $ grep -rl "ROCm" /github/0xff-ai/omnifs/issues/open
/github/0xff-ai/omnifs/issues/open/1432/body /github/0xff-ai/omnifs/issues/open/1450/body
/ $ cat /github/0xff-ai/omnifs/issues/open/1432/title
Crash on long context with quantized model

Reads land state on your machine. The first touch fetches an object once. The host stores it durably, renders every file from it, answers warm reads locally, and owns auth, caching, and egress for every provider. New systems attach as sandboxed Wasm providers built with the omnifs SDK.

quickstart
01 $npm install -g @0xff-ai/omnifs
02 $omnifs setup
03 $omnifs up && omnifs shell
04 $ls /github

every system already speaks omnifs
catlsgrep -rfindtail -fjqrsynctarvimdiffxargsheadwcmd5sum
/glue

One namespace to access everything.

APIs made systems and platforms programmable, but they did not give us a shared substrate. In fact, they encouraged fragmentation.

Each service exposes its own API, schema, auth model, terminology, error table, pagination rules, rate limits. Often, each requires a dedicated SDK.

Conversely, the filesystem is the most durable interface in computing. Every program, agent, language masters disk and file I/O. Semantics are strict and universally understood, and /filesystem/paths offer hierarchical addressing.

today, per vendor ts
const octokit = new Octokit({ auth })
const { data } = await octokit.rest
  .issues.get({ owner, repo, issue_number })
console.log(data.title)
// + install the sdk
// + implement the auth flow
// + paginate, retry, rate-limit
// + repeat for every other vendor
with omnifs
/ $ cat /github/0xff-ai/omnifs/issues/open/56/title
Implement object cache before provider SDK polish

How does omnifs relate to MCP? MCP gives models tools to call. omnifs gives them external state as paths. A path can be traversed, grepped, diffed, cached, piped to any other process, and read again after the session ends.

/paths

Paths are the unified interface.

/omnifs mounts systems, services, data sources (really, anything), onto the local filesystem. Instead of teaching humans, agents, and programs how to deal with every API, they can all rely on the same stable interface we've known and loved for decades: files and directories.

Every provider translates its service into directories, files, fields, rendered views, and searchable trees.

The common layer is not a universal schema. The common layer is the filesystem: paths that humans, scripts, agents, caches, and traces can all operate on without learning the upstream API.

/github provider
/ollama owner
/ollama repo
/issues collection
/open filter
/12959 object
/title field
/linear provider
/teams scope
/ENG team
/issues collection
/open filter
/ENG-204 object
/state field
/docker provider
/containers collection
/by-name index
/api object
/state field
/state

One fetch becomes a directory.

Behind every path sits an object. The first read fetches the canonical upstream payload once, stores it durably, and teaches the host every path it answers. item.json is those bytes verbatim. The other leaves render from them on your machine.

Freshness is mechanical. Mutable objects revalidate with the upstream validator, immutable versions stay trusted, and provider events invalidate exactly the paths they touch. State leaves the cache by fact instead of timer.

five reads, one fetch
/github/0xff-ai/omnifs $ cat issues/open/1432/title
Crash on long context with quantized model
network one GET · canonical stored · validator held
/github/0xff-ai/omnifs $ jq -r .state issues/open/1432/item.json
open
local the canonical body, verbatim
/github/0xff-ai/omnifs $ cat issues/open/1432/state
open
local rendered from the same bytes
/github/0xff-ai/omnifs $ cat issues/all/1432/title
Crash on long context with quantized model
local alias path, same object
# restart the runtime
/github/0xff-ai/omnifs $ cat issues/open/1432/title
Crash on long context with quantized model
revalidate durable object found · 304 · same bytes

Color marks the moments the network is touched. Every gray read was answered from your machine. An agent that re-reads its working set pays the upstream once, and the state it saw is on disk, addressed by paths it can grep, diff, and trace.

/pipe

Pipe data and state across systems.

Once services share a filesystem substrate, pipes can cross system boundaries. Read a CI run, inspect a container, grep the ticket queue, or sketch new providers for the systems you wish were files.

# provider sketch
$ cat /cloudflare/zones/0xff.ai/firewall/events/latest/client_ip \
    | xargs -I% cat /dns/reverse/%
census-12.shodan.io
cloudflarenextdns
/providers

A growing pool of providers.

The provider catalogue is the source of truth for documented provider path surfaces. Providers are the extension point: if a system has an API, socket, repository, database, object store, or control plane, it can have a path.

/ github issues, PRs, CI, and repo trees reposissuesPRsCI runsrepo tree /github/ollama/ollama/issues/open/2853/title
/ dns records over DNS-over-HTTPS, dig without dig AAAAAMXNSTXT /dns/example.com/MX
/ arxiv the arXiv corpus, by id or search papersmetadataPDFsourceversions /arxiv/papers/1706.03762/paper.json
/ docker Docker daemon metadata through a host socket containersstatesystem /docker/containers/by-name/postgres/state
/ linear teams, issues, state, and descriptions teamsissuesstateprioritydescription /linear/teams/ENG/issues/open/ENG-1421/state
/ db a read-only SQLite database schemastablessample rows /db/tables/Album/schema.sql

next up   /huggingface /kubernetes /s3 /slack /discord /redis /stripe /cloudflare /gmail /gdrive /vercel /telegram /claude /openai /notion

/architecture

Providers ask. The host acts.

Capabilities replace ambient authority. Providers answer filesystem requests inside a Wasmtime sandbox, with no ambient network, disk, environment, credentials, or access to other providers.

When a provider needs the outside world, it asks the host for a declared, capability-gated callout. The host enforces reachability, attaches credentials, performs the effect, and resumes the operation.

Every effect crosses one boundary. That is what makes the capability gate, the shared object cache, and the inspector trace the same mechanism.

user / agentshell & tools
lscatgrepfindtarrsyncvim
read(path)
OMNIFS HOSTauthority boundary
path resolutioncachecredentialsnetwork calloutsinode identityprovider lifecycle
sandbox (wasmtime)
PROVIDER .wasmno ambient authority
lookup_childlist_childrenread_filesuspended calloutseffects
capability-gated callouts
upstream resource https, unix sockets, tcp, quic, p2p
apidatabasereporegistryqueue

a provider can

  • render bytes for a path
  • request a capability-gated callout (HTTPS, git, a unix socket)
  • declare which hosts, sockets, and auth schemes it needs

a provider cannot

  • grant itself new capabilities
  • see the credential behind a call
  • open its own socket or touch the network
  • browse arbitrary host files
  • read another provider's state
/sdk

Bring your own system.

The omnifs SDK is how your world enters the filesystem.

Internal APIs, queues, deploys, incidents, databases, model gateways, billing, feature flags, customer state: mount the systems that matter to you, then let tools and agents work through paths.

Declare an object once. The host then owns its caching, identity, alias collapse, and invalidation.

github/provider.rs rust
use omnifs_sdk::{browse::FileContent, prelude::*};

#[omnifs_sdk::object(kind = "github.issue", key = IssueKey)]
#[derive(Clone, Serialize, Deserialize)]
struct Issue { title: String, state: String, body: String }

impl Issue {
    fn title(&self) -> Result<FileContent> { Ok(FileContent::new(self.title.as_bytes())) }
    fn state(&self) -> Result<FileContent> { Ok(FileContent::new(self.state.as_bytes())) }
    fn body(&self)  -> Result<FileContent> { Ok(FileContent::new(self.body.as_bytes())) }
}

#[path_captures]
struct IssueKey { owner: OwnerName, repo: RepoName, filter: Facet<StateFilter>, number: u64 }

impl Key for IssueKey {
    type Object = Issue;
    type State = State;

    async fn load(&self, cx: &Cx<State>, since: Option<Validator>) -> Result<Load<Issue>> {
        load_issue(cx, self, since).await
    }
}

#[omnifs_sdk::provider(
    metadata = "omnifs.provider.json",
    resources(endpoints = [api::GitHubApi], git = true),
)]
impl GithubProvider {
    type Config = Config;
    type State = State;

    fn start(_cfg: Config, r: &mut Router<State>) -> Result<State> {
        r.object::<Issue>("/{owner}/{repo}/issues/{filter}/{number}", |o| {
            o.representations("item", (Markdown,))?;
            o.file("title").project(Issue::title)?;
            o.file("state").project(Issue::state)?;
            o.file("body").lazy().project(Issue::body)?;
            Ok(())
        })?;
        Ok(State::default())
    }
}

/trace

Watch what your agent touches.

Agents work the same filesystem you do. Every path they read, every callout the host ran for it, and every cache decision in between lands on one typed event stream, redacted at the source, recordable, and replayable after the run.

Tool transcripts evaporate when the session ends. Paths persist, and so does their trace. omnifs is the missing primitive between agents and the external world: state they can hold, and a record you can audit.

omnifs inspect event stream
# cat issues/open/1432/title · cold
fuse.start read · /github/0xff-ai/omnifs/issues/open/1432/title
cache.event file_miss · issues/open/1432/title
provider.start github · read-file · issues/open/1432/title
provider.suspend callouts: 1
callout.start fetch · GET api.github.com/repos/0xff-ai/omnifs/issues/1432
callout.end ok
provider.resume round: 1 · results: 1
provider.end ok
fuse.end ok
# the same read, warm
fuse.start read · /github/0xff-ai/omnifs/issues/open/1432/title
cache.event file_hit · issues/open/1432/title
fuse.end ok

omnifs inspect renders the stream live as a mount activity tree, per-mount sparklines, an ops log, and a callout waterfall. The filesystem is the interface. This is the flight recorder underneath.

/write

Writes are commits.

The read model sets up the write model. Each mutable mount will present as a git repository. Edit the projected files in place, commit, and push through an omnifs:// remote. At push time the provider plans the mutations, executes them upstream, and reports partial success honestly.

Writes become diffs you can review, stage, revert, and audit before anything reaches an upstream service.

the design roadmap
$ cd /github/0xff-ai/omnifs
$ printf 'closed\n' > issues/all/1432/state
$ git status --short
  M issues/all/1432/state
$ git add issues/all/1432/state
$ git commit -m "close issue 1432"
$ git push
# push hands the committed diff to the provider to reconcile upstream

Designed in the open and tracked on the roadmap. The mount is the repo, omnifs:// is the remote, and a git-remote-omnifs helper turns committed diffs into provider mutations through a reconcile interface. Local islands like repo/ keep their own nested git semantics.

/lineage

9p, realized with modern tech.

Plan 9 made every resource a file reached through a tiny, uniform set of operations, served by a file server per resource. omnifs keeps the idea and swaps the 1990s mechanics for a sandboxed Wasm and FUSE stack, capability-gated callouts, and today's services.

Bell Labs Plan 9 everything is a file; 9P
2002 9P2000 the revision Linux v9fs speaks
2005 FUSE userspace filesystems in the kernel
2017 Wasm portable sandboxed bytecode
2020s WASI components sandboxed code, explicit capabilities
today omnifs external services, projected as files
/roadmap

Paths today. Git-shaped writes later.

shipped47%
  • providers: github dns arxiv docker linear db
  • Linux FUSE mount
  • macOS through a Linux container shell
  • sandboxed wasm32-wasip2 providers
  • capability-gated HTTP, Git, and unix-socket callouts
  • host-held credentials
  • durable object cache, derived views, event invalidation
  • canonical object model: one fetch, many rendered files
  • Linux toolbox compatibility checks
  • live inspector TUI
in progress16%
  • provider SDK ergonomics
  • cache behavior and invalidation polish
  • setup, auth, and status reporting
plannedqueued
  • Git-shaped mutations
  • more providers
  • runtime frontends beyond Linux FUSE
  • background indexing and semantic search
  • community provider catalog and provider docs
  • persistent inode identity across remounts
  • signed provider capability manifests
/roadmap
dr-- shipped/read-only · done
r-- providers: githubdnsarxivdockerlineardb
r--Linux FUSE mount
r--macOS through a Linux container shell
r--sandboxed wasm32-wasip2 providers
r--capability-gated HTTP, Git, and unix-socket callouts
r--host-held credentials
r--durable object cache, derived views, event invalidation
r--canonical object model: one fetch, many rendered files
r--Linux toolbox compatibility checks
r--live inspector TUI
drw- in-progress/being written
rw-provider SDK ergonomics
rw-cache behavior and invalidation polish
rw-setup, auth, and status reporting
d--- planned/not yet mountable
---Git-shaped mutations
---more providers
---runtime frontends beyond Linux FUSE
---background indexing and semantic search
---community provider catalog and provider docs
---persistent inode identity across remounts
---signed provider capability manifests
$ npm install -g @0xff-ai/omnifs

Open source under MIT OR Apache-2.0. If you would rather cat a path than learn another SDK, or you are shipping a provider against omnifs:[email protected], say hello.

Website inspired by commitmono.com.