Configuration

All settings live in one JSON file at ~/.opentabs/config.json. You won't need to touch it often — the side panel handles permissions, and opentabs-plugin build registers local plugins automatically. But it's worth knowing what's in there, especially if you want to configure permissions by hand or adjust the server port.

Config file location

~/.opentabs/config.json

Override the config directory with the OPENTABS_CONFIG_DIR environment variable. The file is created automatically by opentabs start on first run with 0600 permissions.

Config fields

Example config

{
  "localPlugins": [
    "../plugins/my-plugin",
    "/Users/you/projects/opentabs-plugin-jira"
  ],
  "permissions": {
    "slack": {
      "permission": "ask",
      "tools": {
        "send_message": "auto",
        "delete_message": "off"
      }
    },
    "browser": {
      "permission": "ask",
      "tools": {
        "browser_screenshot_tab": "auto",
        "browser_execute_script": "off"
      }
    }
  }
}

Field details

localPlugins

An array of filesystem paths to local plugin directories. These are plugins under active development on your machine. Paths starting with ./ or ../ are resolved relative to the config directory (~/.opentabs/). Absolute paths and ~/ paths are also supported.

Local plugins are registered automatically when you first run opentabs-plugin build in a plugin directory. You can also add them manually.

npm plugins (installed globally via npm install -g) are auto-discovered from global node_modules — they do not need to be listed here. Local plugins override npm plugins of the same name.

secret

The authentication secret is stored in ~/.opentabs/extension/auth.json, not config.json:

{
  "secret": "<64-character hex string>"
}

Auto-generated on first run. Used for authentication across all transports:

• /mcp and admin endpoints: Authorization: Bearer <secret> header
• /ws: Sec-WebSocket-Protocol header (keeps the secret out of URLs and logs)

Retrieve it for MCP client configuration:

opentabs config show --json --show-secret | jq -r .secret

The --show-secret flag is required to output the full secret value. Without it, the secret is truncated. The source of truth is always auth.json.

permissions

Controls which tools require human approval before executing. The permissions map is keyed by plugin name (or browser for browser tools). Each entry is a PluginPermissionConfig:

Resolution order: skipPermissions (OPENTABS_DANGEROUSLY_SKIP_PERMISSIONS env var) → per-tool override → plugin default → 'off'.

Example — set Slack tools to require approval by default, but auto-approve send_message and disable delete_message:

{
  "permissions": {
    "slack": {
      "permission": "ask",
      "tools": {
        "send_message": "auto",
        "delete_message": "off"
      }
    }
  }
}

Browser tools use the special plugin key browser:

{
  "permissions": {
    "browser": {
      "permission": "ask",
      "tools": {
        "browser_screenshot_tab": "auto",
        "browser_execute_script": "off"
      }
    }
  }
}

Permissions are managed through the Chrome extension side panel. The side panel provides toggle controls for each plugin and each tool, persisting changes to config.json automatically.

Bypassing permissions

Set the OPENTABS_DANGEROUSLY_SKIP_PERMISSIONS=1 environment variable to bypass approval prompts for tools in 'ask' mode (they run as 'auto'). Tools set to 'off' remain disabled. This is dangerous and intended only for CI/testing environments. In normal usage, configure per-plugin and per-tool permissions via the side panel or config.json.

Plugin discovery

The MCP server discovers plugins from two sources:

1. npm auto-discovery — scans global node_modules for packages matching opentabs-plugin-* and @*/opentabs-plugin-*. Install plugins with npm install -g <package>.
2. Local plugins — directories listed in the localPlugins array. Registered automatically by opentabs-plugin build on first build.

Local plugins override npm plugins of the same name. Discovery runs at server startup and whenever POST /reload is called.

Environment variables

Dev vs production mode

The MCP server runs in production mode by default. Dev mode is intended for platform contributors working on the server itself.

Production mode (default)

opentabs start

• Discovers plugins once at startup
• No file watchers — minimal background filesystem activity
• POST /reload is available for on-demand rediscovery (used by opentabs-plugin build)

Dev mode (contributors only)

npm run dev

• File watchers monitor local plugin dist/ directories — auto-reloads when plugins are rebuilt
• Config watching detects changes to config.json and re-discovers plugins
• Hot reload — rebuilt server files take effect without restarting

Use npm run dev:mcp for a lightweight alternative that runs the MCP server only (no tsc watch or extension build).

Dev mode is intended for platform contributors working on the server source code. Normal users and plugin developers use production mode.

The /health endpoint includes a mode field ("dev" or "production") to verify which mode the server is running in.

Config directory structure

Both config.json and auth.json are created with 0600 permissions (owner read/write only) to protect the shared secret.

The extension/ directory is managed by opentabs start. Load it as an unpacked extension from chrome://extensions. The adapters/ subdirectory holds the built adapter IIFE files for each discovered plugin — these are what the extension injects into matching tabs.

Config writes use an atomic pattern: content is written to a temp file then renamed over the target. A mutex serializes concurrent writes.

Last Updated: 10 Mar, 2026