From bb1ff79e485999f36ac3a81873e16b4b68be5123 Mon Sep 17 00:00:00 2001 From: unnipv Date: Mon, 5 Oct 2026 20:13:39 +0530 Subject: [PATCH] docs: add AGENTS.md so a coding agent can set Devdooth up A single AGENTS.md (read by opencode, Codex, and others) with the exact local setup commands, the MCP launcher, guardrails, and a copy-paste task. README and landing link to it. --- AGENTS.md | 71 +++++++++++++++++++++++++++++++++++++++ README.md | 6 ++++ docs/index.html | 5 +++ internal/webui/index.html | 5 +++ 4 files changed, 87 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..f58945f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,71 @@ +# AGENTS.md + +Instructions for coding agents setting up or working in this repository. + +## What it is + +Devdooth turns machines you own into a browser pool. One Go binary (`devdooth`) +contains a coordinator, a worker, and a CLI. Workers dial out; each leased +browser's debug port stays on loopback; profiles stay on the worker. + +Layout: `cmd/devdooth` (CLI), `internal/coordinator` (control plane + CDP relay), +`internal/worker` (launches browsers), `docs/` (architecture, deployment, +threat model). + +## Run it locally + +Prerequisites: Go 1.26+ (or a release binary from GitHub Releases) and an +installed Chrome/Chromium. Node/npx is only needed for the MCP launcher. + +```bash +go build -o bin/devdooth ./cmd/devdooth + +# 1. Coordinator. It prints an admin token on first start; capture it. +bin/devdooth coordinator --addr 127.0.0.1:8080 --store /tmp/devdooth.db > /tmp/devdooth-coordinator.log 2>&1 & +ADMIN=$(grep -o 'DEVDOOTH_ADMIN_TOKEN=.*' /tmp/devdooth-coordinator.log | cut -d= -f2) # or pass --admin-token yourself + +# 2. Enroll this machine and run a worker on it. +TOKEN=$(bin/devdooth enroll-token --url http://127.0.0.1:8080 --token "$ADMIN" --label local 2>/dev/null) +bin/devdooth join --coordinator http://127.0.0.1:8080 --enroll-token "$TOKEN" --name local --data-dir /tmp/devdooth-worker +bin/devdooth worker --coordinator http://127.0.0.1:8080 --data-dir /tmp/devdooth-worker --headful --profiles demo > /tmp/devdooth-worker.log 2>&1 & + +# 3. Lease a browser and verify it. +bin/devdooth nodes --url http://127.0.0.1:8080 --token "$ADMIN" +LEASE=$(bin/devdooth lease --url http://127.0.0.1:8080 --token "$ADMIN" --node local --ttl 600 2>/dev/null) +echo "$LEASE" # contains "endpoint": a ws:// CDP URL + +# 4. Release when done. +bin/devdooth release --url http://127.0.0.1:8080 --token "$ADMIN" --lease "$(echo "$LEASE" | grep -o '"lease_id": *"[^"]*"' | cut -d'"' -f4)" +``` + +Connect a client to the printed `endpoint` with +`playwright.chromium.connect_over_cdp(endpoint)`, or use any CDP/Puppeteer +client. `go test ./internal/...` runs the fast suite; `make e2e` runs the +real-browser tests (needs Chrome). + +## Drive it from another agent + +The shortest path is the built-in MCP launcher: it leases a browser, starts +Playwright MCP against it, and releases the lease on exit. + +```bash +bin/devdooth mcp --url http://127.0.0.1:8080 --token "$ADMIN" --node local +``` + +Point an MCP client at that command over stdio, or call the HTTP API directly +(`/v1/leases`, `/v1/lease/{id}/cdp?token=...`). `scripts/browse.mjs` is a small +Playwright CLI for driving a lease one action at a time. + +## Copy-paste task for an agent + +> Set up Devdooth from AGENTS.md on this machine: build it, start a coordinator +> and a worker, lease a browser, open https://example.com, confirm the page +> title, release the lease, and stop the processes you started. + +## Rules + +- Never print, log, or commit tokens, device identities, or profile contents. +- Keep browser debug ports on loopback; never expose them. +- Devdooth is not an anti-bot, CAPTCHA, or stealth tool. Do not add such work. +- Single owner: do not introduce multi-tenant assumptions. +- Do not commit build output (`bin/`), local stores (`*.db`), or data dirs. diff --git a/README.md b/README.md index 3c53167..d073ac6 100644 --- a/README.md +++ b/README.md @@ -278,6 +278,12 @@ MCP client config: Then ask the agent: *"Go to the site, find X, and report back."* The browser it drives is running on your Mac, using your profile's login state. +### Let a coding agent set it up + +Point your coding agent at [AGENTS.md](AGENTS.md). It contains a copy-paste task +that builds Devdooth, starts a coordinator and a worker, leases a browser, and +verifies the page — no other instructions needed. + ### Browser Use / Stagehand / anything CDP Point the library at the lease endpoint: diff --git a/docs/index.html b/docs/index.html index de80f01..b713589 100644 --- a/docs/index.html +++ b/docs/index.html @@ -400,6 +400,11 @@

Use it from an AI agent

from browser_use import Browser browser = Browser(cdp_url=session.endpoint) +

+ Using a coding agent to set things up? Point it at + AGENTS.md — + it has a copy-paste task that builds, starts, leases, and verifies. +

diff --git a/internal/webui/index.html b/internal/webui/index.html index de80f01..b713589 100644 --- a/internal/webui/index.html +++ b/internal/webui/index.html @@ -400,6 +400,11 @@

Use it from an AI agent

from browser_use import Browser browser = Browser(cdp_url=session.endpoint) +

+ Using a coding agent to set things up? Point it at + AGENTS.md — + it has a copy-paste task that builds, starts, leases, and verifies. +