Configuration

Omnodex is configured via a config.json file in your OMNODEX_HOME directory (default: ~/.omnodex/config.json).

Configuration File

{
  "dashboard": {
    "port": 7890,
    "roots": []
  },
  "detection": {
    "ruleSets": ["community"]
  }
}

Options

dashboard.port

Type: number Default: 7890

The port the dashboard web server listens on.

dashboard.roots

Type: string[] Default: []

Additional OMNODEX_HOME directories the dashboard should tail for events. The default root (~/.omnodex or $OMNODEX_HOME) is always included automatically — list only the extra roots here.

This enables multi-source aggregation: if you run multiple agent surfaces that write to different home directories (e.g. Cowork on Windows + Claude Code in WSL), the dashboard merges events from all roots into a single unified timeline.

{
  "dashboard": {
    "roots": [
      "\\\\wsl$\\Ubuntu\\home\\you\\.omnodex",
      "/mnt/c/Users/you/.omnodex"
    ]
  }
}

Roots can also be passed via the CLI flag --roots for ad-hoc use without modifying the config file.

detection.ruleSets

Type: string[] Default: ["community"]

Which rule sets to apply during detection. The community set is always available. Additional sets are available on paid tiers.

Environment Variables

Environment variables override config file values:

Variable	Overrides	Description
OMNODEX_HOME	(base path)	Root directory for all Omnodex data

File Locations

All Omnodex data lives under OMNODEX_HOME:

$OMNODEX_HOME/
  config.json                  Configuration
  event-log/
    index.jsonl                Session index
    sessions/<id>.jsonl        Per-session event log (append-only)
  traces.db                    SQLite read model (derived, safe to delete)
  omnodex-proxy.json           MCP proxy configuration (optional)

Default paths by platform

macOS

~/.omnodex/ (e.g. /Users/you/.omnodex/)

Single location used by all tools (CLI, Cowork, Codex).

Linux

~/.omnodex/ (e.g. /home/you/.omnodex/)

Single location used by all tools.

Windows

C:\Users\<you>\.omnodex\ for Windows-native tools (Cowork, Codex Desktop UI).

If using WSL, the WSL home (/home/<user>/.omnodex/) is a separate directory. CLI tools and Codex’s agent environment use the WSL path. Use dashboard.roots in the config file to aggregate events from both locations into a single dashboard view. See the dashboard guide for details.

Next Steps

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