{"id":50521911,"url":"https://github.com/0xff-ai/omnifs","last_synced_at":"2026-06-19T23:00:38.148Z","repository":{"id":351345400,"uuid":"1208771097","full_name":"0xff-ai/omnifs","owner":"0xff-ai","description":"a projected filesystem that turns APIs, services, and data sources into local files and directories","archived":false,"fork":false,"pushed_at":"2026-06-14T18:07:23.000Z","size":7971,"stargazers_count":77,"open_issues_count":28,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-14T20:07:27.609Z","etag":null,"topics":["filesystem","fuse","kernel","linux"],"latest_commit_sha":null,"homepage":"https://omnifs.dev","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/0xff-ai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-12T18:12:47.000Z","updated_at":"2026-06-14T17:30:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/0xff-ai/omnifs","commit_stats":null,"previous_names":["raulk/omnifs","0xff-ai/omnifs"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/0xff-ai/omnifs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xff-ai%2Fomnifs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xff-ai%2Fomnifs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xff-ai%2Fomnifs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xff-ai%2Fomnifs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0xff-ai","download_url":"https://codeload.github.com/0xff-ai/omnifs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xff-ai%2Fomnifs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34550858,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-19T02:00:06.005Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["filesystem","fuse","kernel","linux"],"created_at":"2026-06-03T05:00:34.606Z","updated_at":"2026-06-19T23:00:38.143Z","avatar_url":"https://github.com/0xff-ai.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/omnifs-hero.png\" width=\"960\" alt=\"omnifs\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003e\u003cb\u003eomnifs\u003c/b\u003e\u003c/h1\u003e\n\u003ch4 align=\"center\"\u003eopen a path, read the world.\u003c/h4\u003e\n\u003cp align=\"center\"\u003e\u003ca href=\"#quickstart\"\u003equickstart\u003c/a\u003e | \u003ca href=\"https://omnifs.dev\"\u003ehomepage\u003c/a\u003e | \u003ca href=\"https://omnifs.dev/start\"\u003edocs\u003c/a\u003e | \u003ca href=\"#things-to-try\"\u003ethings to try\u003c/a\u003e | \u003ca href=\"#providers\"\u003eproviders\u003c/a\u003e | \u003ca href=\"#how-it-works\"\u003ehow it works\u003c/a\u003e\u003c/p\u003e\n\u003c/div\u003e\n\nomnifs 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.\n\nThe 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.\n\n\u003e 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.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/b9598ece-e772-4fdc-b5c7-8ad5ba26d39d\" alt=\"omnifs demo\" width=\"960\"\u003e\n\u003c/p\u003e\n\n## Quickstart\n\nomnifs 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.\n\n```bash\nnpm install -g @0xff-ai/omnifs\nomnifs setup\nomnifs up\nomnifs shell\n```\n\n`omnifs setup` is interactive. It pulls the Docker image and walks you through provider selection and auth.\n\n`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`.\n\n---\n\nFor a direct, scriptable path, initialize providers one at a time with `omnifs init \u003cprovider\u003e`. Each command writes a mount config under `~/.omnifs/config/mounts/`; `omnifs up` then materializes those mounts, credentials, and capability grants into the runtime container.\n\n```bash\nomnifs init github\nomnifs init dns\nomnifs status\nomnifs up\nomnifs shell\n```\n\n---\n\nUseful commands:\n\n```bash\nomnifs status      # runtime, mount, and auth state\nomnifs logs -f     # follow container and daemon logs\nomnifs inspect     # live TUI for FUSE, provider, cache, and callout activity\nomnifs down        # stop the container and clean up the session\n```\n\n## Things to try\n\nOnce you are in `omnifs shell`, use normal shell tools.\n\n```bash\n# GitHub\ncd /github/ollama/ollama\nls\ncat repo.json\ncat issues/open/12959/title\ncat pulls/all/9585/diff\n# repository trees are cloned on demand\ncd repo \u0026\u0026 ls\n\n# DNS\ncat /dns/cloudflare.com/A\ncat /dns/@google/google.com/AAAA\ncat /dns/openai.com/TXT\ncat /dns/reverse/1.1.1.1\n\n# arXiv -- \"Attention is all you need\"\nls /arxiv/papers/1706.03762\ncat /arxiv/papers/1706.03762/@latest/paper.json | jq .title\n\n# Docker\ncat /docker/system/version.json | jq .\ncat /docker/containers.json | jq .\nls /docker/containers/running\n\n# Linear -- requires a Linear API key\nls /linear/teams\ncat /linear/teams/ENG/issues/open/ENG-123/title\n\n# SQLite -- download an example db and explore the data\nwget -O /tmp/chinook.sqlite https://github.com/lerocha/chinook-database/raw/refs/heads/master/ChinookDatabase/DataSources/Chinook_Sqlite.sqlite\nomnifs init db      # provide path: /tmp/chinook.sqlite\nls /db/tables\ncat /db/tables/Album/schema.sql\ncat /db/tables/Album/sample.json | jq .\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eSSH agent troubleshooting\u003c/summary\u003e\n\nCheck the host before opening repo tree paths:\n\n```bash\necho \"$SSH_AUTH_SOCK\"\nssh-add -L\nssh -T git@github.com\n```\n\n\u003c/details\u003e\n\n## Why paths\n\nAPIs 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.\n\nomnifs makes the path the interface:\n\n```text\n/github/ollama/ollama/issues/open/12959/title\n/docker/containers/running/{name}/state\n/arxiv/papers/1706.03762/@latest/paper.json\n/dns/cloudflare.com/TXT\n```\n\nThat 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.\n\nThe 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.\n\n## Providers\n\n| Provider | Mount | What it projects |\n| --- | --- | --- |\n| GitHub | `/github` | Users, orgs, repos, issues, pull requests, Actions runs, diffs, and repo trees cloned on demand |\n| DNS | `/dns` | DNS-over-HTTPS records, resolver-scoped queries, raw answers, and reverse lookups |\n| arXiv | `/arxiv` | Paper version families, PDFs, source archives, metadata, and category paper listings |\n| Docker | `/docker` | Docker daemon system state, container listings, per-container inspect output, state, and summaries |\n| Linear | `/linear` | Teams and issues, with title, state, priority, assignee, and description files |\n| SQLite | `/db` | Read-only SQLite metadata, table schemas, indexes, row counts, and samples |\n\n### GitHub\n\n| Path | Content |\n| --- | --- |\n| `/github/{owner}` | Repositories for a user or organization |\n| `/github/{owner}/{repo}` | Repository surface |\n| `/github/{owner}/{repo}/repo/` | Source tree, cloned on demand via SSH |\n| `/github/{owner}/{repo}/issues/{open,all}/` | Issue listings |\n| `/github/{owner}/{repo}/issues/{filter}/{n}/title` | Issue title |\n| `/github/{owner}/{repo}/issues/{filter}/{n}/body` | Issue body |\n| `/github/{owner}/{repo}/pulls/{filter}/{n}/diff` | Pull request diff |\n| `/github/{owner}/{repo}/actions/runs/{id}/status` | Actions run status |\n| `/github/{owner}/{repo}/actions/runs/{id}/log` | Actions run log |\n\n### DNS\n\n| Path | Content |\n| --- | --- |\n| `/dns/{domain}/A` | A records |\n| `/dns/{domain}/AAAA` | AAAA records |\n| `/dns/{domain}/MX` | MX records |\n| `/dns/{domain}/TXT` | TXT records |\n| `/dns/{domain}/all` | Common record types |\n| `/dns/{domain}/raw` | Dig-style output |\n| `/dns/@{resolver}/{domain}/{record}` | Query through a named or IP resolver |\n| `/dns/reverse/{ip}` | Reverse lookup |\n| `/dns/resolvers` | Configured resolvers |\n\n### arXiv\n\n| Path | Content |\n| --- | --- |\n| `/arxiv/papers/{id}/` | Paper version family |\n| `/arxiv/papers/{id}/@latest/paper.pdf` | Latest version PDF |\n| `/arxiv/papers/{id}/@latest/source.tar.gz` | Latest version source bundle |\n| `/arxiv/papers/{id}/@latest/paper.atom` | Raw upstream Atom feed |\n| `/arxiv/papers/{id}/@latest/paper.json` | Rendered metadata |\n| `/arxiv/papers/{id}/v{n}/paper.pdf` | Version-pinned PDF |\n| `/arxiv/categories/{cat}/papers/` | Recent papers in a category |\n| `/arxiv/categories/{cat}/papers/{id}/@latest/...` | Category alias for the same paper version family |\n\n### Docker, Linear, and SQLite\n\n| Path | Content |\n| --- | --- |\n| `/docker/system/version.json` | Docker daemon version |\n| `/docker/containers.json` | Container listing |\n| `/docker/containers/{by-name,by-id,running,stopped}/` | Container indexes |\n| `/docker/containers/running/{name}/state` | Live container state |\n| `/docker/containers/running/{name}/inspect.json` | Docker inspect JSON |\n| `/linear/teams/` | Linear teams by key |\n| `/linear/teams/{KEY}/issues/{open,all}/` | Team issue listings |\n| `/linear/teams/{KEY}/issues/{filter}/{KEY-N}/description.md` | Issue description |\n| `/db/meta/info.json` | SQLite database metadata |\n| `/db/tables/{table}/schema.sql` | Table schema |\n| `/db/tables/{table}/sample.json` | Sample rows |\n\n## How it works\n\nomnifs runs a Linux FUSE filesystem in a runtime container. The host CLI owns setup, credentials, container lifecycle, and the user-facing commands.\n\n```text\n                                                                  +----------------+\n+-------------+          +-----------------------------+          | github.wasm    | -\u003e GitHub\n| shell, app, |   FUSE   |        omnifs host          | callouts | dns.wasm       | -\u003e DoH\n| CI, agent   | \u003c------\u003e | /github /dns /arxiv ...     | \u003c------\u003e | docker.wasm    | -\u003e Docker socket\n|             |  files   | cache, auth, git, network   |          | linear.wasm    | -\u003e Linear\n+-------------+          +-----------------------------+          +----------------+\n```\n\nProviders are WebAssembly components implementing the [`omnifs:provider` WIT interface](crates/omnifs-wit/wit/provider.wit). 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`.\n\nProviders 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.\n\nThe 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.\n\n## Development workflows\n\nUse `omnifs dev` when working from this repository. It builds the dev image, provisions credentials for the built-in dev mounts from your host (`gh` CLI, provider env vars) into a dedicated `~/.omnifs/dev` home, fetches the Chinook SQLite fixture, synthesizes dev mounts from the built-in provider manifests, and starts the container. Nothing is written into the checkout.\n\n```bash\ngit clone https://github.com/0xff-ai/omnifs\ncd omnifs\ncargo install --path crates/omnifs-cli --force\nomnifs dev -y\nomnifs shell\n```\n\nCore checks:\n\n```bash\ncargo fmt\ncargo nextest run\njust providers-check\njust providers-build\n```\n\nFor runtime behavior, validate through the container:\n\n```bash\nomnifs dev -y\ndocker exec omnifs /bin/zsh -lc 'omnifs status'\ndocker exec omnifs /bin/zsh -lc 'OMNIFS_DEMO_MODE=smoke /tmp/demo.sh'\ndocker exec omnifs /bin/zsh -lc 'tail -n 80 /tmp/omnifs.log'\n```\n\n## Roadmap\n\n### ✅ Working today\n\n- A Linux FUSE runtime you reach from macOS and Windows too, through the container and `omnifs shell`.\n- A host CLI on npm that handles setup, auth, lifecycle, logs, status, and inspection.\n- Sandboxed Wasm providers that can only reach the network, Git, sockets, and files the host hands them.\n- Host-held credentials, layered caching, and `omnifs inspect` for a live view of what the runtime is doing.\n- Six live providers: GitHub, DNS, arXiv, Docker, Linear, and SQLite.\n\n### 🚧 In progress\n\n- Making the provider SDK nicer to write against, especially for object-shaped providers.\n- Letting providers build paths from their registered routes instead of hand-formatting strings.\n- Caching polish: clearer traces, bounded disk usage, and identities that survive a remount.\n- Better behavior under stuck reads and aggressive directory walkers (shells, prompt tools, crawlers).\n- Smoother setup, auth, status, and `doctor` output, plus a hardened container test suite.\n- Provider reference docs generated straight from each provider's manifest and routes.\n\n### 🔭 Planned\n\n- Write support: stage your intent first, then apply it upstream.\n- Many more providers, including object stores, Kubernetes, Postgres, Redis, Slack, Discord, Google Drive, Gmail, Notion, Stripe, Cloudflare, Vercel, and Telegram.\n- A real provider ecosystem: standalone packaging, a community catalog, authoring docs, and sidecars for providers that need native dependencies.\n- Mount surfaces beyond Linux FUSE for environments where FUSE isn't the right fit, plus passthrough for host-backed subtrees.\n- Easier install and slimmer packaging: multi-arch runtime images, Homebrew or shell installers, and a cleaner split between the CLI and the runtime binary.\n- Going further than warm cache reads: offline snapshots, background indexing, semantic search, and DNS prefetch.\n- Trust and safety: signed provider manifests, tighter sandboxing for host-run tools, and metered filesystem access.\n\n## License\n\nMIT OR Apache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xff-ai%2Fomnifs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0xff-ai%2Fomnifs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xff-ai%2Fomnifs/lists"}