Skip to content
PEN Docs

Running PEN

Your IDE spawns PEN automatically via the MCP config that pen init wrote. You don't run PEN by hand unless you're using HTTP transport or debugging.

Flags

FlagDefaultPurpose
--cdp-urlhttp://localhost:9222CDP endpoint
--transportstdiostdio, http, or sse
--addrlocalhost:6100Bind address for HTTP/SSE
--allow-evalfalseEnable pen_evaluate (runs JS in browser)
--statelessfalseDisable session tracking for HTTP transport (no Mcp-Session-Id required)
--auto-launchtrueAuto-launch a debug browser if CDP not found
--project-root.Sandbox for source file paths
--log-levelinfodebug / info / warn / error
--versionPrint version and exit

IDE Config

pen init writes this for you. Manual setup if needed:

VS Code — .vscode/mcp.json
json 
{
  "servers": {
    "pen": {
      "command": "pen",
      "args": ["--project-root", "${workspaceFolder}"]
    }
  }
}
Cursor — .cursor/mcp.json
json 
{
  "mcpServers": {
    "pen": {
      "command": "pen",
      "args": ["--project-root", "${workspaceFolder}"]
    }
  }
}
Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

json 
{
  "mcpServers": {
    "pen": {
      "command": "pen",
      "args": ["--project-root", "/absolute/path/to/project"]
    }
  }
}

Browser Setup

By default (--auto-launch=true), PEN launches a separate debug browser automatically. Your existing browser is untouched.

Manual browser launch commands
bash 
# macOS
open -a "Google Chrome" --args --remote-debugging-port=9222 --user-data-dir=/tmp/pen-debug --no-first-run

# Windows
& "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="$env:TEMP\pen-debug" --no-first-run

# Linux
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/pen-debug --no-first-run &

Use --user-data-dir so it runs alongside your regular browser. Verify with http://localhost:9222/json.

HTTP Transport

bash 
pen --transport http --addr localhost:6100

Serves MCP at http://localhost:6100/mcp. Use this for shared or remote setups instead of stdio.

Docker & CI

Docker setup
dockerfile 
FROM golang:1.24-bookworm AS builder
WORKDIR /app
COPY . .
RUN go build -o pen ./cmd/pen

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y google-chrome-stable --no-install-recommends \
    && rm -rf /var/lib/apt/lists/*
COPY --from=builder /app/pen /usr/local/bin/pen
CMD ["sh", "-c", "google-chrome --headless --no-sandbox --disable-gpu --remote-debugging-port=9222 --remote-debugging-address=127.0.0.1 & sleep 2 && exec pen --cdp-url http://127.0.0.1:9222"]
Headless / CI
bash 
google-chrome --headless --no-sandbox --disable-gpu \
  --remote-debugging-port=9222 --remote-debugging-address=127.0.0.1 &
pen --cdp-url http://127.0.0.1:9222

For remote browsers, tunnel with SSH: ssh -L 9222:localhost:9222 user@server

Security Notes

  • Never expose port 9222 to the network
  • --no-sandbox only in containers, not bare metal
  • --allow-eval only in trusted environments
  • Always set --project-root in production

Lighthouse

pen_lighthouse needs the Lighthouse CLI. All other tools work without it.

bash 
npm install -g lighthouse