AI Translation Notice
Translated/synchronized from the authoritative Chinese documentation (简体中文文档). Check source files or Chinese docs if subtle phrasing differs.
Overview & Setup Workflow
AgentDock Bridge is a single-owner personal remote MCP gateway. It connects remote MCP clients (such as ChatGPT) over Cloudflare Workers OAuth 2.1 + PKCE to your local workstation, waits for explicit human approval of exact arguments in a local terminal, and executes file and Bash tools inside a read-only Linux Docker container.
Runtime Scope & Platform Boundaries
| Layer | Supported Runtime | Key Boundaries |
|---|---|---|
| Cloud Edge | Cloudflare Workers + two SQLite Durable Objects (AuthCoordinator, BridgeRelay) | Production requests require HTTPS (127.0.0.1 / localhost / [::1] allowed for local tests) |
| Production Host | Windows x64 (PowerShell 5.1, DPAPI secrets.dpapi, NTFS ACL checks, Docker Desktop) | loadSecrets and windows-acl.mjs require win32; Linux/macOS supports Worker deploy and JS/cloud tests only |
| Execution Sandbox | Linux container via desktop-linux Docker context (node:24-trixie-slim, UID/GID 1000) | Mounts one explicit workspace at /workspace; approved tools can read/write project-local files |
Trust Notice: Cloudflare and your upstream AI client platform still observe
/mcparguments and results in transit. This bridge guarantees that no local action runs without owner OAuth consent and exactApprove.cmdconfirmation.Interactive Reference: Browse every OAuth endpoint,
WSS /bridgerule, and all 10 MCP tool schemas with explicit bounds in the API & Component Reference.
Prerequisites
- A Cloudflare account with HTTPS domain routing (
PUBLIC_ORIGIN) and authenticatedwrangler. - Windows x64 with Node.js 24+,
pnpm@12.6.0, and Docker Desktop (desktop-linuxcontext active overnpipe://). - An explicit workspace directory (
<workspace-path>) strictly separate from%USERPROFILE%\.agentdock-bridgeand your source checkout.
Step-by-Step Deployment Workflow
1. Validate Checkout & Prepare wrangler.jsonc
pnpm install --frozen-lockfile
pnpm run check
pnpm test
Copy-Item wrangler.jsonc.example wrangler.jsoncSet vars.PUBLIC_ORIGIN in wrangler.jsonc to your deployed HTTPS origin (for example https://<your-bridge-domain> without a trailing slash). wrangler.jsonc is ignored by Git and must never be committed.
2. Initialize Protected Host Secrets & Upload to Cloudflare
.\scripts\Setup.ps1 -Roots "<workspace-path>" -Origin "https://<your-bridge-domain>"
.\scripts\Secrets.ps1 -Action UploadSetup.ps1 generates a 32-byte URL-safe BRIDGE_TOKEN and a 24-byte OWNER_PASSWORD (stored encrypted via Windows DPAPI in %USERPROFILE%\.agentdock-bridge\secrets.dpapi) plus a 100,000-iteration PBKDF2-SHA256 OWNER_PASSWORD_HASH. Secrets.ps1 -Action Upload pipes only BRIDGE_TOKEN and OWNER_PASSWORD_HASH into wrangler secret bulk.
3. Build the Pinned Development Image
docker build -f container/Dockerfile -t agentdock-dev:2026-10-28 .4. Install the Hardened Host Copy & Deploy the Worker
.\scripts\Install-Hardened.ps1 -Workspace "<workspace-path>"
pnpm run deployInstall-Hardened.ps1 verifies ancestor ACLs, downloads and verifies pinned Windows x64 Node 24.22.1 (SHA-256 + OpenJS Authenticode signature under %USERPROFILE%\.agentdock-toolchains), pins the container sha256:... digest, copies local/ and scripts/ into a versioned runtime-* folder with frozen production dependencies, and generates trusted .cmd wrappers under %USERPROFILE%\.agentdock-bridge.
5. Start Connector, Connect MCP Client, and Approve Requests
& "$env:USERPROFILE\.agentdock-bridge\Start.cmd"
& "$env:USERPROFILE\.agentdock-bridge\Status.cmd"- Confirm
/healthzreturns200({"ok":true,"connectorOnline":true}). - Add
https://<your-bridge-domain>/mcpin your remote MCP client. - On the OAuth consent page, verify the client identity and callback URI, then enter the password shown by
%USERPROFILE%\.agentdock-bridge\Password.cmd(or rootShowPassword.cmd). - When a file or command tool returns
LOCAL_APPROVAL_REQUIRED, run%USERPROFILE%\.agentdock-bridge\Approve.cmd, inspect the escaped JSON arguments, typeAPPROVE <uuid>, and retry with identical arguments within 5 minutes.
Next Steps
- Full parameter, script, and rotation matrix: Configuration & Scripts Matrix
- Error diagnosis (
503,APPROVAL_RECORD_TOO_LARGE, ACL failures): Deployment & Runtime FAQ - HTTP/OAuth, MCP tool schemas, replay ordering & sandbox flags: Contracts & Boundaries