Quickstart

This page gets you from install to a live read. It uses the CLI, starts the runtime, opens the omnifs shell, and reads provider paths with normal Unix tools.

Install

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

npm install -g @0xff-ai/omnifs
omnifs --version

Platform support

The FUSE mount is Linux. On macOS, omnifs runs the Linux runtime in a container and you read paths from omnifs shell. Windows support and native non-Linux mounts are outside the supported runtime path.

Configure a provider

The guided setup is the fastest path:

omnifs setup

You can also configure one provider at a time:

omnifs init dns
omnifs init github

Providers that need credentials prompt for them. Credential and local-resource requirements vary by provider; use the provider catalogue and the provider pages as the source of truth.

Start the runtime

omnifs up
omnifs shell

Inside the shell, the mount root is /omnifs. Each configured provider appears as a directory beneath it:

ls /omnifs

Read a path

Try a provider that needs no credentials:

cat /omnifs/dns/example.com/MX

Use normal tools on the result:

cat /omnifs/dns/example.com/raw | jq .

If you configured GitHub, list open issues and read a field:

ls /omnifs/github/0xff-ai/omnifs/issues/open
cat /omnifs/github/0xff-ai/omnifs/issues/open/42/title

The first read may perform a host-mediated callout. Later reads can hit the view cache or render from cached canonical object bytes.

Inspect what happened

Use status, logs, and inspect when a path surprises you:

omnifs status
omnifs logs -f
omnifs inspect --plain

inspect shows local runtime events: provider calls, callouts, cache behavior, and errors. It is the fastest way to see whether a read came from cache or reached an upstream system.

Stop the runtime

exit
omnifs down

Next, read Architecture for the host/provider boundary or Provider catalogue for provider path examples.