Cowork Desktop Setup

Omnodex integrates with Cowork through a plugin that routes MCP tool calls through the Omnodex proxy. Every call to an MCP server you route through Omnodex is recorded in your local event log.

How this differs from Claude Code

The Claude Code integration uses hooks and records built-in tools such as file reads, edits, and shell commands. The Cowork integration uses the MCP proxy on your desktop, so it records MCP tool calls. A Cowork task’s built-in tools run in a cloud container instead, which only the plugin’s own files reach. A personal plugin from the hosted dashboard records those too; the shared plugin does not.

Where the proxy runs

The plugin’s MCP server runs on your desktop, including for Cowork tasks you start from the cloud: those tasks start plugin MCP servers on the desktop linked to your account. Everything below happens on that desktop. On Windows, that is native Windows, not WSL.

Before you start

On the desktop:

1. Install Node.js 24+ natively. The plugin starts the proxy with the system Node.js. On Windows, a Node.js install that exists only inside WSL does not work.
2. Install Omnodex from npm, or from source. On Windows, do this in PowerShell.

Check Node.js:

Windows (PowerShell)

where.exe node
where.exe npx

macOS / Linux / WSL

which node
which npx

Installation

1. Install the plugin.

   Download omnodex-cowork.plugin, then drag it onto the Cowork window, or install it from a file in Settings > Plugins. Confirm omnodex-cowork appears in the installed plugins list and is enabled.

   To also record built-in tools in cloud-hosted tasks, install your personal plugin from the hosted dashboard instead of this file. It is the same plugin with your stream’s details added: see Cloud-hosted tasks.

2. Create the proxy configuration.

   Create omnodex-proxy.json in your Omnodex home. upstream_servers lists the MCP servers to route through Omnodex:

   Windows (PowerShell)

   C:\Users\<you>\.omnodex\omnodex-proxy.json:

   {
     "version": 1,
     "redact_parameters": false,
     "upstream_servers": [
       {
         "name": "filesystem",
         "transport": "stdio",
         "command": "C:\\Program Files\\nodejs\\npx.cmd",
         "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\<you>\\Documents\\project"]
       }
     ]
   }

   Use the paths where.exe printed, and Windows paths throughout. JSON strings need escaped backslashes.

   macOS / Linux / WSL

   ~/.omnodex/omnodex-proxy.json:

   {
     "version": 1,
     "redact_parameters": false,
     "upstream_servers": [
       {
         "name": "filesystem",
         "transport": "stdio",
         "command": "/absolute/path/to/npx",
         "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/<you>/project"]
       }
     ]
   }

   Replace the example upstream with the MCP servers you use. Put secrets in environment variables and reference them as ${VAR} in an upstream’s env. See Configuration.

   Installed from npm

   That is all: the plugin finds the npm install on its own.

   Installed from source

   Also add proxy_bin, the path to your build’s proxy, for example "proxy_bin": "C:\\path\\to\\omnodex\\packages\\mcp-proxy\\dist\\bin\\omnodex-mcp-proxy.js" on Windows or "proxy_bin": "/path/to/omnodex/packages/mcp-proxy/dist/bin/omnodex-mcp-proxy.js" elsewhere. Use proxy_bin rather than an environment variable: Cowork does not pass user environment variables to plugin MCP servers.

3. Fully quit and reopen Cowork.

   Quit the app completely (on Windows, also from the system tray), then open it again. Cowork does not retry a plugin MCP server that failed to start until the app restarts.

4. Verify in a new task.

   Type /omnodex in a new task, or ask Cowork to call omnodex_status. Then ask it to use one of the routed tools. Routed tools appear as <server>__<tool>, for example filesystem__list_directory.

   Cowork asks for approval the first time each tool is used. Choose to allow it for all tasks if you do not want to be asked again.

5. Connect to the hosted dashboard (optional).

   Type /omnodex connect, or ask Cowork to call omnodex_connect. If this desktop has no API token yet, you get a short code and a URL: open the URL, sign in at dashboard.omnodex.com, and enter the code. The stream secret is transferred end-to-end encrypted.

What gets traced

Activity	Recorded	Notes
Calls to MCP servers routed through Omnodex	Yes	Tool name, parameters (unless redacted), timing, status, and response size
Proxy session start and end	Yes	The session ends when Cowork stops the proxy, for example when the app quits
Cowork built-in tools (read, write, shell)	With a personal plugin	They run in a cloud container. A personal plugin records them and sends them, encrypted, to the hosted dashboard. The shared plugin does not
The model the session uses	No	The proxy is not told which model Cowork uses
MCP servers or connectors not routed through Omnodex	No	Only upstreams in omnodex-proxy.json pass through the proxy

Cowork’s only path to Omnodex is the proxy, so in guardrails mode the proxy is also where calls are stopped. See Stopping calls.

Cloud-hosted tasks

A Cowork task runs its built-in tools in a cloud container, even when the task is linked to your desktop. Only the plugin’s files reach that container, so to record those tools the plugin needs to know where to send events. A personal plugin carries that: a token that can only add events to your stream, and your stream’s public key. Events are encrypted to that key inside the container, so Omnodex stores them without being able to read them.

This needs the hosted dashboard on the Hosted plan or above.

1. Download your personal plugin. In the hosted dashboard, open Activity. Under Record Cowork’s cloud tasks, at the top, choose the stream to record to and select Download personal Cowork plugin. Tick Redact tool parameters first if parameter values should be replaced with [REDACTED] before they are encrypted.

2. Replace the shared plugin with it. In Settings > Plugins, remove omnodex-cowork, then install the downloaded file as in Installation, step 1. Its version ends in +personal. It keeps everything the shared plugin does, so the proxy on your desktop is unchanged.

3. Run a task. Events arrive at the end of each turn and show up in that stream as a Cowork cloud machine. Record Cowork’s cloud tasks shows when the plugin last sent events.

Keep it to yourself

Install a personal plugin for your own account only. Anyone who can read the file can add events to your stream, though not read any, and an organization-wide install would send everyone’s events to your stream. If the file is shared by mistake, choose Revoke under Record Cowork’s cloud tasks: its events are refused from then on, and events it already sent stay in your dashboard.

An account has one personal plugin, since Cowork installs one omnodex-cowork plugin and Claude shares plugins across your devices. Downloading again replaces it: the previous file’s token stops working, so install the new one. Adding a stream changes nothing. Record Cowork’s cloud tasks says when the plugin needs replacing, for example when its stream is revoked or paused, or a newer plugin is out.

On your desktop and in local Claude Code, the personal plugin’s hook does nothing, since the proxy and local hooks already record there.

Viewing events

Cowork writes events to the Omnodex home on the desktop: C:\Users\<you>\.omnodex\ on Windows, ~/.omnodex/ on macOS and Linux.

Windows (PowerShell)

omnodex dashboard

macOS / Linux

omnodex dashboard

From WSL

WSL has its own Omnodex home, so add the Windows one as an extra root:

omnodex dashboard --roots /mnt/c/Users/<you>/.omnodex

See Windows and WSL.

Updating

1. Update Omnodex on the desktop: run omnodex update in PowerShell on Windows, or your terminal on macOS. It updates an npm install or a source build. See Updating.

2. Check whether the plugin changed. The current version is cowork.version in latest.json. If you already have that version, skip to step 5.

3. Remove the old plugin. In Settings > Plugins, remove omnodex-cowork. Do this before installing the new one, so only one copy of the Omnodex server is registered.

4. Install the new plugin. Download the latest omnodex-cowork.plugin and install it as in Installation, step 1. Your omnodex-proxy.json is outside the plugin, so it is kept. If you use a personal plugin, download it again from the hosted dashboard instead, which builds it from the latest shared plugin and retires the old one.

5. Fully quit and reopen Cowork, including from the system tray on Windows, then start a new task. Tasks that were already open keep the tools they started with.

To check the result, ask Cowork to call omnodex_status in the new task.

Troubleshooting

Only the omnodex_* tools appear, but your routed tools are missing:

Ask Cowork to call omnodex_status. Starting with omnodex 0.10.0, the proxy gives an upstream without a cached tool list up to 45 seconds to connect before sending its first list. Cached tools are still listed immediately. A first package download or a changed upstream configuration can need that extra time.

If the list was sent while an uncached upstream was still connecting, status names that server and tells you to restart the agent app once it connects. The proxy also writes one warning to stderr. Fully quit and reopen Cowork once the upstream is connected, including from the Windows system tray, then start a new task. Opening another task alone does not refresh the list: Cowork keeps the same proxy process and ignores tool-list change notifications.

For a consistently slow upstream, see Sizing the discovery window. If status reports a failure, fix that first; a longer discovery window does not fix a failed connection.

omnodex_status is not available in Cowork:

1. Check launcher.log in .omnodex under your user home (C:\Users\<you>\.omnodex\launcher.log on Windows). The plugin’s launcher records startup failures there:

   Log entry	Cause
   FATAL: binary not found	The launcher could not find Omnodex. For an npm install, check npm install -g omnodex ran in PowerShell on this desktop, not only in WSL. For a source install, proxy_bin is missing or points to a file that does not exist, or omnodex-proxy.json is not in .omnodex under your user home
   FATAL: spawn error	Node.js could not start the proxy

   The launcher writes only failures, so a log with no new entries does not mean something went wrong.

2. Check that the proxy starts on its own with your config. It should start and wait for input (press Ctrl+C to stop). A config error prints a message and exits.

   Installed from npm

   omnodex-mcp-proxy --config C:\Users\<you>\.omnodex\omnodex-proxy.json

   Installed from source

   node C:\path\to\omnodex\packages\mcp-proxy\dist\bin\omnodex-mcp-proxy.js --config C:\Users\<you>\.omnodex\omnodex-proxy.json

3. Fully quit and reopen Cowork after any fix.

4. On Windows, the Claude desktop app log at %LOCALAPPDATA%\Claude\logs\main.log shows each attempt to start the plugin’s server. Search for omnodex-cowork: a working setup logs Connected to plugin:omnodex-cowork:omnodex, and a failing one logs Failed to connect.

The proxy fails with ERR_MODULE_NOT_FOUND for an @omnodex/... package (Windows): the build was installed from WSL. See Windows and WSL for the fix.

Routed tools fail with requires approval, or approval only offers “once”: update Omnodex. Earlier builds named routed tools <server>/<tool>, which Cowork cannot approve. Rebuild, fully restart Cowork, and start a new task.

Events appear in the wrong place (Windows): Cowork writes to the Windows Omnodex home. A dashboard started in WSL reads the WSL home unless you add the Windows one with --roots.

Next steps

• Windows and WSL
• Running Detection
• Choosing a Dashboard
• Configuration Reference