omnifs projects external systems into local filesystem paths. GitHub, DNS, arXiv, Docker, Linear, and SQLite become directories and files you can cd, ls, cat, grep, find, jq, and script against.

The goal is simple: if a tool can read files, it can read the outside world without learning another SDK, auth flow, pagination model, or response schema.

Alpha status: omnifs is real and usable, but the read surface is still early. The filesystem is exposed through FUSE, and omnifs runs in a Docker container in supported environments for compatibility, rootless execution, and simpler setup across Linux, macOS, and Windows. NFSv4 and FSKit support are planned, and we will remove the Docker requirement when native mounts are ready.

omnifs is written in Rust. We build prebuilt binaries for all platforms and ship them through the npm registry. During alpha, you need Node.js, npm, and a Docker-compatible container engine such as Docker, OrbStack, or Podman.

npm install -g @0xff-ai/omnifs
omnifs setup
omnifs up
omnifs shell

omnifs setup is interactive. It pulls the Docker image and walks you through provider selection and auth.

omnifs shell opens a shell against the running container. Inside the container, the filesystem is mounted at /omnifs, with convenience symlinks for every mount at the root, such as /github, /dns, and /arxiv.

For a direct, scriptable path, initialize providers one at a time with omnifs init <provider>. Each command writes a mount config under ~/.omnifs/config/mounts/; omnifs up then materializes those mounts, credentials, and capability grants into the runtime container.

omnifs init github
omnifs init dns
omnifs status
omnifs up
omnifs shell

Useful commands:

omnifs status      # runtime, mount, and auth state
omnifs logs -f     # follow container and daemon logs
omnifs inspect     # live TUI for FUSE, provider, cache, and callout activity
omnifs down        # stop the container and clean up the session

Once you are in omnifs shell, use normal shell tools.

# GitHub
cd /github/ollama/ollama
ls
cat repo.json
cat issues/open/12959/title
cat pulls/all/9585/diff
# repository trees are cloned on demand
cd repo && ls

# DNS
cat /dns/cloudflare.com/A
cat /dns/@google/google.com/AAAA
cat /dns/openai.com/TXT
cat /dns/reverse/1.1.1.1

# arXiv -- "Attention is all you need"
ls /arxiv/papers/1706.03762
cat /arxiv/papers/1706.03762/@latest/paper.json | jq .title

# Docker
cat /docker/system/version.json | jq .
cat /docker/containers.json | jq .
ls /docker/containers/running

# Linear -- requires a Linear API key
ls /linear/teams
cat /linear/teams/ENG/issues/open/ENG-123/title

# SQLite -- download an example db and explore the data
wget -O /tmp/chinook.sqlite https://github.com/lerocha/chinook-database/raw/refs/heads/master/ChinookDatabase/DataSources/Chinook_Sqlite.sqlite
omnifs init db      # provide path: /tmp/chinook.sqlite
ls /db/tables
cat /db/tables/Album/schema.sql
cat /db/tables/Album/sample.json | jq .

echo "$SSH_AUTH_SOCK"
ssh-add -L
ssh -T git@github.com

APIs are good boundaries for applications. They are a bad default interface for every script, terminal session, CI job, editor, and agent that only needs to read state.

omnifs makes the path the interface:

/github/ollama/ollama/issues/open/12959/title
/docker/containers/running/{name}/state
/arxiv/papers/1706.03762/@latest/paper.json
/dns/cloudflare.com/TXT

That gives existing tools a common substrate. grep -r, find, jq, tar, diff, head, tail, and editors can all operate without provider-specific clients. Agents get the same benefit: open a path and read bytes.

The current surface is read-only. Write-back is designed around explicit staged transactions, but projected issue, PR, container, and DNS files are not directly writable today.

omnifs runs a Linux FUSE filesystem in a runtime container. The host CLI owns setup, credentials, container lifecycle, and the user-facing commands.

                                                                  +----------------+
+-------------+          +-----------------------------+          | github.wasm    | -> GitHub
| shell, app, |   FUSE   |        omnifs host          | callouts | dns.wasm       | -> DoH
| CI, agent   | <------> | /github /dns /arxiv ...     | <------> | docker.wasm    | -> Docker socket
|             |  files   | cache, auth, git, network   |          | linear.wasm    | -> Linear
+-------------+          +-----------------------------+          +----------------+

Providers are WebAssembly components implementing the omnifs:provider WIT interface. Providers are self-contained: they declare required capabilities and offer an introspection surface via omnifs.provider.json, embedded in the Wasm bytecode. A provider's main job is to answer filesystem operations via entrypoint methods lookup_child, list_children, and read_file.

Providers do not hold tokens, open sockets, or run Git themselves. They return callout requests such as HTTP fetches, blob downloads, archive opens, or repo tree handoffs. The host executes those requests, attaches credentials at the boundary, enforces declared capabilities, and owns caching.

The cache is host-owned plain byte storage. Providers can return canonical upstream bytes and derived filesystem entries together, so one upstream payload can populate multiple files and child entries. Invalidations come from explicit provider effects and runtime events.

Use omnifs dev when working from this repository. It builds the dev image, captures gh auth token, fetches the Chinook SQLite fixture, synthesizes dev mounts from the built-in provider manifests, and starts the container.

git clone https://github.com/0xff-ai/omnifs
cd omnifs
cargo install --path crates/omnifs-cli --force
omnifs dev -y
omnifs shell

Core checks:

cargo fmt
cargo nextest run
just providers-check
just providers-build

For runtime behavior, validate through the container:

omnifs dev -y
docker exec omnifs /bin/zsh -lc 'omnifs status'
docker exec omnifs /bin/zsh -lc 'OMNIFS_DEMO_MODE=smoke /tmp/demo.sh'
docker exec omnifs /bin/zsh -lc 'tail -n 80 /tmp/omnifs.log'

• A Linux FUSE runtime you reach from macOS and Windows too, through the container and omnifs shell.
• A host CLI on npm that handles setup, auth, lifecycle, logs, status, and inspection.
• Sandboxed Wasm providers that can only reach the network, Git, sockets, and files the host hands them.
• Host-held credentials, layered caching, and omnifs inspect for a live view of what the runtime is doing.
• Six live providers: GitHub, DNS, arXiv, Docker, Linear, and SQLite.

• Making the provider SDK nicer to write against, especially for object-shaped providers.
• Letting providers build paths from their registered routes instead of hand-formatting strings.
• Caching polish: clearer traces, bounded disk usage, and identities that survive a remount.
• Better behavior under stuck reads and aggressive directory walkers (shells, prompt tools, crawlers).
• Smoother setup, auth, status, and doctor output, plus a hardened container test suite.
• Provider reference docs generated straight from each provider's manifest and routes.

• Write support: stage your intent first, then apply it upstream.
• Many more providers, including object stores, Kubernetes, Postgres, Redis, Slack, Discord, Google Drive, Gmail, Notion, Stripe, Cloudflare, Vercel, and Telegram.
• A real provider ecosystem: standalone packaging, a community catalog, authoring docs, and sidecars for providers that need native dependencies.
• Mount surfaces beyond Linux FUSE for environments where FUSE isn't the right fit, plus passthrough for host-backed subtrees.
• Easier install and slimmer packaging: multi-arch runtime images, Homebrew or shell installers, and a cleaner split between the CLI and the runtime binary.
• Going further than warm cache reads: offline snapshots, background indexing, semantic search, and DNS prefetch.
• Trust and safety: signed provider manifests, tighter sandboxing for host-run tools, and metered filesystem access.

MIT OR Apache-2.0