remote-browser

Runs the Playwright MCP's browser headless in Docker on a stoppable AWS EC2 instance, reached through an SSH tunnel, so parallel Claude Code sessions stop opening local Chrome windows. Falls back to local headless Chromium when the tunnel is down. Every session gets an isolated browser context (--isolated).

Design: see the spec in the person-ops repo, docs/superpowers/specs/2026-10-12-remote-browser-design.md.

Install

npm install && npm link

Related MCP server: sshrew

One-time setup (AWS parts are yours to run)

# 1. IAM: create a dedicated user, attach infra/iam-policy.json, then:
aws configure --profile remote-browser
# 2. Config
mkdir -p ~/.remote-browser
echo '{ "awsProfile": "remote-browser", "region": "eu-west-1" }' > ~/.remote-browser/config.json
# 3. Provision (asks for confirmation before anything billable)
remote-browser init

Wire into Claude Code:

ln -s ~/Projects/remote-browser/skill ~/.claude/skills/remote-browser
claude mcp add --scope user playwright -- remote-browser-mcp

Disable the plugin's own Playwright MCP so two servers do not both launch browsers. Tool names change from mcp__plugin_playwright_playwright__* to mcp__playwright__*; check project skills or agents that reference the old prefix.

SessionStart hook for ~/.claude/settings.json:

{ "hooks": { "SessionStart": [ { "hooks": [ { "type": "command", "command": "node ~/Projects/remote-browser/hooks/session-start.mjs" } ] } ] } }

Cost guards

infra/iam-policy.json limits what the credential can do: only t4g.large, only eu-west-1, tagged-instance start/stop, no terminate or delete. If you change region, change aws:RequestedRegion in the policy too. IAM cannot cap how many instances or how long they run, so add a budget (console, your admin login, not the remote-browser user):

1. Billing > Budgets > Create budget > Cost budget, monthly, about $15. Alerts by email at 50% and 100% of actual spend and 100% of forecast.

2. Create a customer-managed IAM policy remote-browser-budget-deny from infra/budget-deny-policy.json. Do not attach it to the user yourself: an explicit deny overrides every allow, so attaching it by hand blocks init and up immediately. Only the budget action (step 3) should attach it. It denies RunInstances and StartInstances but not StopInstances, so remote-browser down still works.

3. On the 100% actual alert, add a budget action: "Apply IAM policy" > remote-browser-budget-deny > the remote-browser IAM user. Optionally add a second action on the same threshold, "Stop EC2 instances", for the instance id from ~/.remote-browser/config.json (instanceId). Both need an execution role that budgets.amazonaws.com can assume; the console offers to create it. Choose automatic execution, not manual approval, or it will not protect you while you sleep.

4. After a trigger, remove the deny policy from the user to use the tool again.

Budgets use billing data that lags by roughly 8-12 hours, so this is a backstop for runaway spend, not a real-time limit. Still check remote-browser status at the end of the day for the first week.

Commands

remote-browser init | up | down | status. Usage details live in skill/SKILL.md.

Config: ~/.remote-browser/config.json (ports, region, profile, idle minutes). REMOTE_BROWSER_HOME overrides the directory.

Tests

npm test for unit tests; npm run test:e2e needs Docker and internet (isolation check against a local container).

Manual end-to-end checklist (record results here)

1. Tunnel closed: start a session. Banner says LOCAL FALLBACK. Navigate to http://localhost:3000; it works, headless.

2. remote-browser up. Reconnect /mcp. New session banner says REMOTE. Navigate to http://localhost:3000; it loads the laptop's app.

3. Open 3 sessions; set a cookie in one on http://localhost:3000; the others must not see it.

4. Activity Monitor shows no new Chrome processes during steps 2-3.

5. ssh into the instance and confirm docker ps lists rb-chrome.

6. Close all sessions, wait 30+ minutes: instance becomes stopped without down.

7. remote-browser down twice: second run reports already stopped, no error.

8. Change networks, run up: aws ec2 describe-security-groups shows exactly one port-22 rule.

Results: not yet run.