Configuration

Omnodex keeps its configuration in your Omnodex home: ~/.omnodex/ by default, C:\Users\<you>\.omnodex\ on native Windows, or the directory set in OMNODEX_HOME. Each file below is optional; create only the ones you need.

File	Purpose
config.json	Dashboard roots and machine label
omnodex-config.json	Where hooks find their handlers (source installs), and extra workspace roots
omnodex-proxy.json	MCP proxy upstream servers
stream-config.json	Hosted dashboard connection, written by omnodex connect

config.json

{
  "dashboard": {
    "roots": ["/mnt/c/Users/<you>/.omnodex"]
  },
  "machine": {
    "label": "Work Laptop"
  }
}

dashboard.roots

Type: string[] Default: []

Additional Omnodex home directories the local dashboard reads. The dashboard’s own home is always included, so list only the extra ones. Paths that do not exist are skipped.

Use this to see several hosts in one dashboard, for example native Windows and WSL on the same machine. See Windows and WSL. For one-off use, pass omnodex dashboard --roots <path> instead.

machine.label

Type: string Default: (none)

A readable name for this host, shown in the hosted dashboard’s machine selector. Without it, the dashboard shows an ID derived from the hostname. The label is display only; storage uses the derived ID.

omnodex-config.json

Tells hook launchers where the hook handlers of your Omnodex build are, and optionally which extra folders count as part of your workspace. shim_paths is required for source installs; an npm install does not need it, because the launchers find the npm package on their own.

{
  "shim_paths": {
    "claude-code": "/path/to/omnodex/packages/hooks-provider/dist/bin/claude-hook-shim.js",
    "codex": "/path/to/omnodex/packages/codex-provider/dist/bin/codex-hook-shim.js",
    "antigravity": "/path/to/omnodex/packages/antigravity-provider/dist/bin/antigravity-hook-shim.js"
  }
}

Use absolute paths in the host’s path style, with escaped backslashes on Windows. An entry is used only if the file exists. See Installation.

workspace_roots

Risk detection flags writes outside a session’s workspace. The workspace is the folder the session started in and its current folder, the git repositories those belong to (including every worktree of the same repository), and any folders you list here. Add folders your agents are meant to write to across projects, such as a shared notes folder:

{
  "shim_paths": { "claude-code": "/path/to/omnodex/packages/hooks-provider/dist/bin/claude-hook-shim.js" },
  "workspace_roots": ["~/notes", "/srv/shared-docs"]
}

A leading ~ is your home folder. Your home folder itself and the filesystem root are never treated as a workspace, even when a session starts there.

MCP proxy configuration

omnodex-proxy.json lists the upstream MCP servers the proxy routes. The proxy reads it from --config <path> if given, otherwise from the Omnodex home.

{
  "version": 1,
  "redact_parameters": false,
  "upstream_servers": [
    {
      "name": "filesystem",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
    },
    {
      "name": "github",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" },
      "redact_parameters": true
    }
  ],
  "upstream_connection": {
    "discovery_window_ms": 15000
  }
}

Field	Type	Default	Description
version	1	required	Config schema version
redact_parameters	boolean	false	Replace every parameter value with [REDACTED] in the event log. Parameter names are kept.
proxy_bin	string	(none)	Source installs: path to your build’s proxy script, for the Cowork, Codex, and Antigravity plugin launchers. Not needed for an npm install, which the launchers find on their own, or when a client starts the proxy directly with node and --config.
upstream_servers	array	[]	Upstream servers to route. May be empty: the proxy still serves its built-in omnodex_* tools.
upstream_servers[].name	string	required	Identifier, used as the tool name prefix
upstream_servers[].transport	"stdio"	required	Only stdio is supported
upstream_servers[].command	string	required	Executable to start. Use an absolute path for desktop apps.
upstream_servers[].args	string[]	[]	Arguments for the command
upstream_servers[].env	object	(none)	Environment variables for the upstream. Values can reference the proxy’s environment as ${VAR}.
upstream_servers[].cwd	string	proxy’s directory	Working directory for the upstream
upstream_servers[].name_override	string	(none)	Prefix to use instead of name
upstream_servers[].redact_parameters	boolean	inherits top level	Per-server redaction
upstream_connection.discovery_window_ms	number	15000	Ceiling on how long the first tool listing waits for upstreams that are still starting and whose tools the proxy has not seen before. See Sizing the discovery window.
upstream_connection.connect_timeout_ms	number	30000	Limit for one attempt to start an upstream and read its tools
upstream_connection.retry_initial_delay_ms	number	1000	Delay before the first retry of a failed upstream. Doubles on each retry.
upstream_connection.retry_give_up_delay_ms	number	180000	Retries stop once the next delay would reach this. With the defaults that is 9 attempts over about 4 minutes.

Tools from each upstream are exposed as <prefix>__<tool>, for example filesystem__read_file. Keep secrets out of this file: put them in environment variables and reference them with ${VAR}.

How upstreams connect

The proxy answers your agent straight away and connects upstream servers in the background, each one independently. A slow or broken upstream does not stop the others, and does not stop the built-in omnodex_* tools. A failed upstream is retried with a delay that doubles each time, until the next delay would reach retry_give_up_delay_ms; after that it stays failed. Ask your agent to call omnodex_status to see each upstream’s state, last error and next retry, or to call it with retry_failed: true to retry the failed ones immediately.

The proxy remembers each upstream’s tool list between runs, so from the second run on an upstream’s tools are listed straight away, even while it is still starting. If your agent calls one of those tools before the upstream is ready, the call waits for it. The lists are kept in proxy-tool-cache/ in your Omnodex home, hold tool definitions only (names, descriptions and parameters, never environment values or credentials), and are safe to delete. Changing an upstream’s entry in this file starts it fresh.

Sizing the discovery window

Most agent clients read the tool list once, when they start the proxy. Claude Code is the exception: it acts on the MCP tools/list_changed notification and picks up an upstream that connects later in the session. ChatGPT Desktop, Codex CLI and Cowork do not. The proxy covers this by listing the tools it remembers from earlier runs, so the window matters only the first time an upstream runs, or after you change its entry. In that session, an upstream that connects after the discovery window is missing until the agent restarts, even though omnodex_status shows it connected. After a restart its tools are listed at once.

Set discovery_window_ms above the time your slowest upstream needs on its first run. The wait ends as soon as every upstream has settled, so this is a ceiling, not a delay you always pay.

{
  "upstream_connection": { "discovery_window_ms": 25000 }
}

How long upstreams take:

• A local server started from an installed binary: well under a second.
• A first run of npx -y or uvx, which downloads the package: several seconds, and longer on a slow network. Later runs are faster because the package is cached.
• A server that signs in over the network at startup: as long as that call takes.

To check yours, ask your agent to call omnodex_status right after it starts. Any upstream still connecting, or any missing <prefix>__<tool>, means the window is too short.

Raising it costs nothing while upstreams are healthy. It costs time only when one is slow or hanging: the first tool listing can block for up to the window. Your agent still starts, because the proxy answers the MCP handshake immediately.

Lowering it gets a first run’s tool listing sooner, at the risk of dropping a new, slow upstream for that session. Use a low value when every upstream is a fast local process, or when you would rather start with fewer tools than wait.

connect_timeout_ms is a separate, longer limit on a single connection attempt. A new upstream can still be connecting when the window closes; it is simply missing from the first listing.

Test a new upstream by running the proxy yourself before adding it to a desktop app: omnodex-mcp-proxy --config <path> for an npm install, or node <proxy_bin> --config <path> for a source install.

MCP proxy with Claude Code

To add the proxy to a project, put it in the project’s .mcp.json. The proxy script is <global node_modules>/omnodex/bin/omnodex-mcp-proxy.js for an npm install (npm root -g prints the folder), or <repo>/packages/mcp-proxy/dist/bin/omnodex-mcp-proxy.js for a source install:

.mcp.json

{
  "mcpServers": {
    "omnodex": {
      "command": "/absolute/path/to/node",
      "args": [
        "/usr/local/lib/node_modules/omnodex/bin/omnodex-mcp-proxy.js",
        "--config",
        "/home/<you>/.omnodex/omnodex-proxy.json"
      ],
      "alwaysLoad": true
    }
  }
}

alwaysLoad is optional. Claude Code defers MCP tools until a tool search finds them; with alwaysLoad, the Omnodex tools are available from the start of the session.

stream-config.json

Written by omnodex connect. Holds the hosted dashboard connection for this host.

{
  "passphrase": "word1 word2 word3 word4 word5 word6",
  "api_url": "https://api.omnodex.com",
  "api_token": "omx_..."
}

Field	Description
passphrase	Sync passphrase for zero-knowledge encryption. Generated as six random words on first connect.
api_url	Omnodex cloud API endpoint
api_token	API token for cloud features

OMNODEX_API_TOKEN and OMNODEX_SYNC_PASSPHRASE take precedence over the values in this file. The file contains credentials; do not commit or share it.

Automatic sync settings

A connected host refreshes the hosted dashboard’s encrypted blob on its own. See Automatic sync for what runs where. These optional fields in the same file tune it; the defaults suit almost everyone.

Field	Type	Default	Description
auto_sync	boolean	true	Set to false to turn automatic sync off. omnodex sync still works by hand.
auto_sync_min_interval_seconds	number	60	Shortest gap between two syncs. Stops back-to-back sessions each starting one.
auto_sync_interval_seconds	number	900	How often a running MCP proxy syncs. Values under 30 are ignored. Does not apply to hook platforms, which sync when a session ends.

OMNODEX_AUTO_SYNC=0 in the environment turns automatic sync off without editing the file.

Environment variables

Variable	Description
OMNODEX_HOME	Omnodex home directory (default ~/.omnodex)
OMNODEX_API_TOKEN	API token for cloud features
OMNODEX_SYNC_PASSPHRASE	Sync passphrase
OMNODEX_AUTO_SYNC	Set to 0 to turn automatic sync off on this host
OMNODEX_DEBUG	Set to 1 for detailed hook launcher logging in launcher.log
OMNODEX_NO_UPDATE_CHECK	Set to 1 to disable the background update check

Desktop apps such as Cowork do not always pass user environment variables to the MCP servers they start. Use the config files above for anything a desktop app needs.

File locations

$OMNODEX_HOME/
  config.json                  Dashboard roots, machine label
  omnodex-config.json          Hook handler locations
  omnodex-proxy.json           MCP proxy configuration
  stream-config.json           Hosted dashboard connection
  installations.json           Projects where hooks are installed
  auto-sync-state.json         Last automatic sync: time, blob, error
  auto-sync.lock               Held while a sync runs; ignored after 10 minutes
  streaming-key-cache.json     Cached streaming key, so each push skips the KDF
  event-log/
    index.jsonl                Session index
    sessions/<id>.jsonl        Per-session event log (append-only)
  traces.db                    SQLite read model (derived, safe to delete)
  bin/                         Hook launchers
  launcher.log                 Launcher failures

Default paths by platform

macOS

~/.omnodex/ (for example /Users/you/.omnodex/), used by every agent on the Mac.

Linux

~/.omnodex/ (for example /home/you/.omnodex/), used by every agent on the machine.

Windows

C:\Users\<you>\.omnodex\ for agents running natively on Windows, including Cowork and ChatGPT Desktop.

WSL has its own home, /home/<you>/.omnodex/, used by agents you run inside WSL. See Windows and WSL.

Next steps

• CLI Commands - Command reference
• Event Schema - Event data format