Quickstart

Install

omnifs ships as an npm package. Node 18 or later is required.

npm install -g @0xff-ai/omnifs

Verify the install:

omnifs --version

Platform support

Linux is the primary target. macOS is supported via a dev container today because FUSE requires macFUSE or FUSE-T, which are not yet bundled automatically. The container approach works end-to-end; native macOS support is on the roadmap.

Mount

Pick a mount point, then start the runtime:

mkdir -p /tmp/omni
omnifs mount /tmp/omni

The process stays in the foreground and logs provider activity to stderr. Open a second terminal for the reads below. To unmount, press Ctrl-C or run umount /tmp/omni.

Providers read credentials from environment variables. Export any you need before mounting, or set them in a config file (see CLI reference):

export GITHUB_TOKEN=ghp_...
export LINEAR_TOKEN=lin_api_...
omnifs mount /tmp/omni

First reads

GitHub issues

List open issues on a repo:

ls /tmp/omni/github/0xff-ai/omnifs/_issues/_open

1  2  5  12  23  2853

Read the title of one:

cat /tmp/omni/github/0xff-ai/omnifs/_issues/_open/2853/title

Auth tokens expire mid-session

Read the body or check the state:

cat /tmp/omni/github/0xff-ai/omnifs/_issues/_open/2853/state
cat /tmp/omni/github/0xff-ai/omnifs/_issues/_open/2853/body

Pull a PR diff:

cat /tmp/omni/github/0xff-ai/omnifs/_prs/_open/41/diff

DNS records

No credentials needed. The dns provider uses DNS-over-HTTPS with Cloudflare and Google preconfigured:

ls /tmp/omni/dns/example.com

A  AAAA  MX  NS  TXT  CNAME  SOA  _all  _raw

cat /tmp/omni/dns/example.com/MX

10 mail.example.com.
20 mail2.example.com.

Query via a specific resolver:

cat /tmp/omni/dns/@1.1.1.1/example.com/A

Docker container state

The docker provider reads the local daemon socket, no credentials required:

ls /tmp/omni/docker/containers/_running

nginx  postgres  redis

cat /tmp/omni/docker/containers/by-name/postgres/state

running

What just happened

Each cat or ls above issued a read() or readdir() to the kernel, which FUSE routed to the omnifs host runtime. The runtime resolved the path, checked its event-invalidated cache, and dispatched the request to the relevant WASM provider component (github, dns, or docker). The provider answered one of three operations (lookup-child, list-children, or read-file) and the host made a single capability-gated callout on its behalf. The provider never holds credentials and never opens its own socket; the host does both.

On a cache hit, the bytes return without leaving your machine.

Compose providers

The mount point is a single filesystem. grep, diff, jq, and find reach across providers naturally:

# open GitHub issues from one repo, compared against Linear issues for a team
diff \
  <(ls /tmp/omni/github/0xff-ai/omnifs/_issues/_open) \
  <(ls /tmp/omni/linear/teams/ENG/issues/_open)

# watch a CI run status while it runs
watch -n5 cat /tmp/omni/github/0xff-ai/omnifs/_actions/runs/12345678/status

# pull arXiv paper metadata with jq
cat /tmp/omni/arxiv/papers/1706.03762/metadata.json | jq .title

"Attention Is All You Need"

Five live providers

Provider	What it exposes	Credentials
github	repos, issues, PRs, CI runs	GITHUB_TOKEN
docker	container state, compose projects	none (local socket)
arxiv	papers, metadata, source archives	none
linear	issues, state, priority	LINEAR_TOKEN
dns	A, AAAA, MX, TXT, and other record types	none

Thirteen more providers are in progress. They appear in the catalogue with // wip and are not mounted by default.

Next steps

• The projection model: how paths map to WASM provider ops and what the runtime owns.
• Provider catalogue: path schemes for all five live providers plus the in-progress list.
• Build a provider: implement lookup-child, list-children, and read-file as a WASM component and load it without rebuilding the runtime.