What is Fennec?

Fennec is an MCP (Model Context Protocol) server that bridges the gap between AI agents and your development environment. It gives your AI full-stack visibility — and, crucially, full-stack control:

• 🔍 Observe browser console logs, network requests, and performance metrics in real-time
• 🖥️ Run & watch your apps as supervised background daemons — logs, restart, health
• 🤝 Adopt processes an AI agent (or you) started via raw bash, so they're tracked instead of orphaned
• 🔐 Persist authentication sessions across conversations
• 🔗 Correlate events across layers to identify root causes automatically
• 🌐 Cross-browser support: Chromium, Firefox, WebKit
• 🪟 Cross-platform: Linux, macOS, and Windows

Installation

Global Install (Recommended)

npm install -g @plumpslabs/fennec-cli

Then (optional) install browser engines if you need browser automation:

fennec install-browsers

Note: Playwright is an optional peer dependency. Fennec works for terminal/process monitoring without it. Only install browser engines if you need browser automation features.

From Source

git clone https://github.com/plumpslabs/fennec.git
cd fennec
pnpm install
pnpm build

Browser engines (optional for source install):

pnpm add playwright
npx playwright install chromium

Quick Start

1. Configure your MCP client

Configuration format depends on your MCP client:

OpenCode (~/.config/opencode/opencode.json):

{
  "mcpServers": {
    "fennec": {
      "type": "local",
      "command": ["fennec", "start"],
      "enabled": true
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "fennec": {
      "command": "fennec",
      "args": ["start"]
    }
  }
}

Cline / Cursor / Windsurf (same standard format):

{
  "mcpServers": {
    "fennec": {
      "command": "fennec",
      "args": ["start"]
    }
  }
}

That's it — Fennec speaks stdio by default and needs no extra permissions to observe.

2. (Optional) Let the AI control processes

If you want your AI agent to start, restart, and stop apps for you, enable process permissions via environment variables in the MCP config:

{
  "mcpServers": {
    "fennec": {
      "command": "fennec",
      "args": ["start"],
      "env": {
        "FENNEC_SECURITY_ALLOW_PROCESS_SPAWN": "true",
        "FENNEC_SECURITY_ALLOW_PROCESS_KILL": "true"
      }
    }
  }
}

For OpenCode, add "env" inside the server entry:

{
  "mcpServers": {
    "fennec": {
      "type": "local",
      "command": ["fennec", "start"],
      "enabled": true,
      "env": {
        "FENNEC_SECURITY_ALLOW_PROCESS_SPAWN": "true",
        "FENNEC_SECURITY_ALLOW_PROCESS_KILL": "true"
      }
    }
  }
}

Spawn is enabled by default; kill is off by default (safer). Set both to true only in trusted, local dev environments. See Security & Environment Variables.

3. (Optional) Run the server over SSE instead of stdio

While local client connections generally use stdio, you can also run Fennec over SSE (Server-Sent Events) for remote setups. Start Fennec with --sse:

{
  "mcpServers": {
    "fennec": {
      "command": "fennec",
      "args": ["start", "--sse"]
    }
  }
}

With --sse, Fennec starts an HTTP+SSE endpoint (default http://127.0.0.1:3333/sse). Configure SSE clients as { "type": "remote", "url": "http://localhost:3333/sse" }.

For OpenCode (SSE):

{
  "mcpServers": {
    "fennec": {
      "type": "remote",
      "url": "http://localhost:3333/sse",
      "enabled": true
    }
  }
}

For Continue.dev (SSE recommended):

// config.json
{
  "experimental": {
    "mcpServers": [
      {
        "name": "fennec",
        "transport": "sse",
        "url": "http://localhost:3333/sse"
      }
    ]
  }
}

Tip: When using SSE, Fennec outputs the exact MCP config snippet on startup so you can copy-paste it directly into your client config. Run fennec start --sse and look for the MCP Config line.

4. Ask your AI to diagnose issues

"Why is my app broken?" — AI uses Fennec to check browser console, network, and server logs simultaneously.

CLI Commands

Fennec is both an MCP server and a CLI you can use directly in your terminal.

Server

| Command | Description | | ------------------------------ | ----------------------------------------------------------------------------- | | fennec start | Start the MCP server (stdio transport). Default when no app command is given. | | fennec start --sse | Start the MCP server over HTTP+SSE (experimental). | | fennec start --transport sse | Alias of --sse. |

Apps & Processes

| Command | Description | | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | fennec start <command> --name <name> [options] | Launch an app as a supervised background daemon. Alias: run. | | fennec ps [options] | List Fennec-tracked apps with live status. | | fennec status [name] | System overview + top processes (tracked and system). | | fennec log <name\|pid> [options] | Show (and follow) logs for a tracked app. | | fennec spawn [name] [name...] [--all] | Re-spawn a stopped tracked app from its saved config. Accepts MULTIPLE names at once. | | fennec stop <name\|--all> [name...] | Stop (pause) a tracked app but keep it in the registry. Accepts MULTIPLE names. Add -y/--yes to skip the confirmation prompt. | | fennec restart <name\|pid> [name...] | Stop and re-spawn a tracked app from its saved config. Accepts MULTIPLE names at once. | | fennec kill <pid\|name\|all> [name...] | Kill a process and remove it from the registry. Accepts MULTIPLE names at once. Add -y/--yes to skip the confirmation prompt. | | fennec group [name] [group] | Assign a logical group to tracked apps (or list them). Bulk: fennec group <group> <name...>. --unset to clear. Group is preserved across spawn/restart. | | fennec adopt <pid> [--name <name>] [--port <port>] | Adopt an externally-started process into Fennec tracking. | | fennec supervisor <start\|stop\|restart\|status> | Manage the background supervisor that keeps --restart apps alive. | | fennec persist <enable\|disable\|status> | Survive reboots — auto-start tracked apps after login (systemd/launchd/Windows). | | fennec dev <up\|down\|status\|restart <app>> | Orchestrate a whole dev stack from fennec.config.yaml. | | fennec inspect <name\|pid> | Compact, AI-safe snapshot (status + recent logs + error scan). | | fennec info <name> | Detailed info for a tracked app. | | fennec rename <old> <new> | Rename a tracked app. | | fennec debug <attach\|detach\|status> <name\|--group> | Attach/detach debug mode to tracked apps. Three levels: log (L), breakpoint (B), auto (A). Supports bulk via --group. |

start / run options:

| Option | Description | | ----------------- | ---------------------------------------------------------- | | --name <name> | Process name (recommended) | | --port <port> | Wait until port accepts connections | | --cwd <dir> | Working directory | | --restart | Auto-restart on crash / port-down, survives terminal close | | --group <group> | Tag for scoped bulk ops | | --debug <mode> | Start with debug mode: log, breakpoint, or auto | | --jsonl | Structured JSON-lines logs |

ps options:

| Option | Description | | ------------------------------ | ----------------------------------- | | -w / --watch | Live refresh | | --system / -a / --all | Include non-Fennec system processes | | --json | JSON output | | --name <filter> | Filter by name | | --group <g> | Show only apps in group | | --sort <cpu\|mem\|pid\|name> | Sort column |

The MEM column shows each running app's RSS cross-platform.

log options:

| Option | Description | | ---------------------------------- | ----------------------------------- | | -f / --follow | Tail logs live | | --lines N | Number of recent lines | | --since 10m\|1h\|2d | Filter by time | | --level error\|warn\|info\|debug | Filter by level | | --json | Bounded, redacted, machine-readable | | --no-redact | Skip secret redaction | | --clear | Clear log file |

inspect options:

| Option | Description | | ------------- | ------------------- | | --plain | Short human summary | | --tail N | Recent log lines | | --since 10m | Filter by time |

Logical groups & bulk operations:

| Action | Command | | -------------------------- | --------------------------------------------------------------- | | Tag when starting | fennec start <cmd> --name <n> --group <g> | | Tag existing app | fennec group <name> <g> | | Clear group tag | fennec group <name> --unset | | Bulk tag | fennec group <g> <name1> <name2> ... | | Scope ops to group | fennec kill --group <g>, stop --group <g>, ps --group <g> | | Bulk stop (multiple names) | fennec stop <name1> <name2> | | Bulk kill | fennec kill <name1> <name2> -y | | Bulk restart | fennec restart <name1> <name2> -y | | Bulk spawn | fennec spawn <name1> <name2> | | Bulk debug attach | fennec debug attach --group <g> --mode <mode> | | Bulk debug detach | fennec debug detach --group <g> |

Groups are preserved across spawn/restart. Already-running entries are never double-spawned. --all targets every tracked app.

Observation

| Command | Description | | ---------------------------- | ---------------------------------------------------- | | fennec attach <port> | Observe a running process by the port it listens on. | | fennec attach-pid <pid> | Attach to and observe a process by its PID. | | fennec attach-port <port> | Attach to and observe a process by its port. | | fennec pipe --name <name> | Pipe stdin into a Fennec log watcher. | | fennec watch --file <path> | Watch an existing log file. |

Data

| Command | Description | | ----------------------------- | ---------------------------------------------------- | | fennec export --file <path> | Export tracked apps to a file. | | fennec import <file> | Import tracked apps from a file. | | fennec cleanup | Remove dead/stale entries from the tracked registry. |

Store & Doctor

Fennec persists everything — auth sessions, tracked processes, exports, plugin/workflow state — under one global store, by default ~/.fennec (honors FENNEC_HOME / FENNEC_DATA_DIR), manageable from any directory. --local targets the per-project .fennec instead.

| Command | Description | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------ | | fennec store | Overview of everything in the global store (counts, size, age). | | fennec store --local | Same, for the project .fennec. | | fennec store session | List saved auth sessions. | | fennec store session info <name> | Show a session — cookie/localStorage values are masked; add --show-secrets to reveal. | | fennec store session rm <name> | Delete a session (confirm prompt). | | fennec doctor | Health + secret-surface checks: store permissions, synced-home leakage, embedded secrets in launch commands. |

Database

| Command | Description | | --------------------------------- | ----------------------------------------------------------------------------- | | db connect <name> [--url <url>] | Connect/reconnect (auto-starts agent; uses saved credential if --url omitted) | | db ps | Agent status + all saved connections | | db list | Alias for ps | | db disconnect <name> | Disconnect from agent (keeps credential) | | db rm <name> | Remove credential entirely | | db query <name> <sql> | Execute a SQL query | | db schema <name> | Inspect full database schema | | db tables <name> | List tables and row counts | | db ping <name> | Health check with latency | | db stats <name> | Database statistics (size, connections) | | db explain <name> <sql> | Get query execution plan | | db start | Start persistent agent (auto-started by connect) | | db stop | Stop persistent agent | | db restart | Restart persistent agent | | db update | Download/update dbTui binary | | db doctor | Check dbTui installation status |

Configuration & Misc

| Command | Description | | ------------------------- | -------------------------------------------------------------------------- | | fennec init | Generate a fennec.config.yaml in the current directory. | | fennec setup | Interactively configure your MCP client for Fennec. | | fennec install-browsers | Install Playwright browser engines. | | fennec sessions | List saved browser auth sessions (alias of fennec store session). | | fennec store | Unified view of everything Fennec persists (sessions, processes, exports). | | fennec doctor | Health + secret-surface checks for the store. | | fennec health | Health check of the Fennec environment. | | fennec help [command] | Show help, or detailed help for a command. |

Usage Examples

Run an app as a supervised daemon

# Launch and immediately return to your shell — logs go to ~/.fennec/logs/web.log
fennec start "npm run dev" --name web --port 3000

# Auto-restart if it crashes or its port stops answering (survives terminal close)
fennec start node server.js --name api --cwd ./backend --restart

# Watch it
fennec ps
fennec log web -f

Idempotent dev up

fennec dev up reads fennec.config.yaml and brings the whole stack up. It is idempotent: already-running apps with unchanged config are skipped, apps whose config changed are restarted, and an app whose port is already taken by another process is adopted instead of spawning a conflicting duplicate.

fennec dev up                 # bring the stack up (skips what's already running)
fennec dev status             # see every app's health
fennec dev restart web        # restart just one app
fennec dev down               # stop everything (keeps it in the registry)

Bulk operations & groups

# Tag apps into groups when starting (or retroactively with `fennec group`)
fennec start "npm run dev-be" --name api-service --group crm
fennec start "npm run dev-fe" --name web-app --group crm

# One-shot bulk: pass MULTIPLE names at once
fennec stop  api-service web-app          # pause both, keep them in the registry
fennec spawn api-service web-app          # re-spawn both paused apps
fennec kill  api-service web-app -y        # kill + forget both
fennec restart api-service web-app -y     # restart both from saved config

# Group-scoped bulk: only that group is touched (other groups safe)
fennec kill  --group crm -y
fennec stop  --group crm
fennec ps --group crm               # MEM column shows each app's live RSS

# Global: --all still hits EVERY tracked app across all groups
fennec stop --all

Adopt a process an AI agent started via raw bash

An AI agent (or you) sometimes launches a server with plain bash. Fennec can take ownership instead of leaving it orphaned:

# Fennec finds whatever is listening on :8130 and tracks it as "svc"
fennec adopt $(lsof -ti :8130) --name svc --port 8130

# Or let Fennec discover the PID by port:
fennec start node server.js --name svc --port 8130   # adopts the existing one

Adopted processes appear in fennec ps and gain supervised logging. (Fennec-spawned processes auto-restart on crash; adopted external processes are tracked but not respawned, since Fennec doesn't know their original command.)

Inspect & observe

fennec inspect web --plain          # one-line human summary
fennec inspect web --since 10m      # recent logs + error scan (AI-friendly)
fennec log web --json --since 10m   # bounded, redacted, machine-readable for AI

Survive reboots (persist)

fennec persist enable    # auto-start tracked apps after login (uses systemd user
                         # service / launchd / Windows startup; enables linger on Linux)
fennec persist status

Configuration

Fennec works with zero config, but supports customization:

fennec init  # Creates fennec.config.yaml

Key configuration options (see full reference):

browser:
  adapter: auto # auto, cdp, or playwright
  type: chromium # chromium, firefox, or webkit
  headless: true
  viewport:
    width: 1280
    height: 720

process:
  maxProcesses: 10
  spawnAllowlist: # only these commands may be spawned
    - npm
    - node
    - pnpm
    - yarn
    - bun
    - python
    - python3

security:
  sandbox: true
  allowProcessSpawn: true
  allowProcessKill: false # off by default — opt in explicitly
  allowJSEvaluation: true

  db:
    strict: true # Block non-localhost connections
    allowedHosts: # Allowed hosts (strict mode)
      - localhost
      - 127.0.0.1
      - ::1
    maxRows: 1000 # Default row limit
    queryTimeout: 30000 # Query timeout in ms
    allowWrite: false # Allow write queries (needs --no-strict)
    binaryPath: '' # Custom dbTui binary path

lazyContext:
  level1: true # Auto-attach summary on errors
  level2: false # Attach detail on expand
  level3: false # Attach raw data on request

correlation:
  windowMs: 500
  enableRootCauseInference: true
  minConfidence: 0.7

debug:
  allowDebug: true # Enable debug features globally
  allowDebugEval: false # Expression evaluation (high risk)
  allowedDirs: [] # Restrict breakpoints to these dirs
  allowDependencies: false # Allow breakpoints in node_modules/.venv

Security & Environment Variables

Fennec ships with sandbox mode enabled by default and conservative process permissions. Environment variables override the config file:

| Variable | Effect | | -------------------------------------------------- | ------------------------------------------------------------------------ | | FENNEC_DATA_DIR | Override where Fennec stores tracked state & logs (default ~/.fennec). | | FENNEC_SANDBOX | false disables the sandbox (permits more operations). | | FENNEC_SECURITY_ALLOW_PROCESS_SPAWN | true allows the AI to spawn new processes. | | FENNEC_SECURITY_ALLOW_PROCESS_KILL | true allows the AI to kill processes. | | FENNEC_SECURITY_ALLOW_JS_EVALUATION | true allows in-page JS evaluation. | | FENNEC_TRANSPORT_TYPE | stdio (default) or sse. | | FENNEC_PORT | Port for SSE transport (default 3333). | | FENNEC_BROWSER_TYPE | chromium | firefox | webkit. | | FENNEC_HEADLESS | false to run headed. | | FENNEC_DEFAULT_TIMEOUT | Browser default timeout (ms). | | FENNEC_VIEWPORT_WIDTH / FENNEC_VIEWPORT_HEIGHT | Viewport size. | | FENNEC_LOG_LEVEL | debug | info | warn | error. | | FENNEC_SECURITY_ALLOW_FILE_READ | true allows the AI to read files. | | FENNEC_SECURITY_ALLOW_FILE_WRITE | true allows the AI to write files. | | FENNEC_SECURITY_ALLOW_CDP_RAW_ACCESS | true allows direct CDP raw access. | | FENNEC_SECURITY_DEBUG_ALLOWED_DIRS | Restrict debug breakpoints to these directories (comma-separated). | | FENNEC_BROWSER_ADAPTER | Browser adapter: auto | cdp | playwright. | | FENNEC_SESSION_ROTATION_INTERVAL_SECS | Context rotation interval in seconds (0 = off). |

Security features:

• 🔒 Process spawn allowlist (only npm, node, pnpm, etc. allowed by default)
• 🔒 Domain allowlist/blocklist for browser navigation
• 🔒 Per-tool permissions (eval, kill, spawn)
• 🔒 Audit logging of all tool calls
• 🔒 Session data export path confinement

See Security Model for details.

Cross-Platform

Fennec runs on Linux, macOS, and Windows:

• Process discovery (findPidOnPort, command-line/cwd resolution, ps) is platform-aware: Linux uses /proc, macOS uses lsof/ps, Windows uses netstat/tasklist/wmic.
• attach/attach-port rely on lsof on macOS/Linux (install it if missing).
• On Windows, an app's cwd isn't readable via built-ins, so it shows as empty.

Cross-Browser Support

Fennec supports all three major browser engines via Playwright:

FENNEC_BROWSER_TYPE=firefox fennec start
FENNEC_BROWSER_TYPE=webkit fennec start

Documentation

• Getting Started Guide
• Full Tool Reference
• Configuration Reference
• Security Model
• GitHub Repository

Memory & Garbage Safety

Fennec is built to not leak memory or orphan processes on your machine:

• 🌳 Process-tree kills — stop/kill/spawn/restart tear down the entire process tree (npm → vite → esbuild on POSIX; taskkill /T /F on Windows), so no orphaned children are left "nyampah".
• 🧹 Browser contexts are fully torn down on session destroy (page and its BrowserContext — cookies, cache, service workers), not just the page.
• ⏳ Idle-session GC runs on a timer (not only when the session cap is hit): idle sessions and over-TTL sessions are destroyed automatically.
• 📑 Tab caps — opening many tabs (tab_new / context_new) auto-closes the oldest non-active page so contexts can't accumulate.
• ♻️ Context rotation — long-lived contexts are periodically recycled (config.session.rotationIntervalSecs, default 0 = off). The old BrowserContext is closed and a fresh one built with your cookies/localStorage preserved (via storageState) and the current URL reloaded, so a session that's open for hours can't grow unbounded in DOM/listeners/workers. Trigger on demand with the context_rotate tool too.
• 🪵 Bounded logs — app logs are rotated (10 MB × 3 files) so disk never fills.
• 🔌 Graceful shutdown — SIGTERM/SIGINT closes the browser and all tracked daemons; ps even shows a live MEM (RSS) column so you can spot leaks.

License

MIT — see LICENSE for details.