AGENTS.md

Subagent definitions for automating ngrok setup on Linux/WSL2. The MCP server needs ngrok to expose localhost:8000 publicly for Claude Desktop and remote clients.

ngrok-detect

Checks whether ngrok is installed and reports its path and version. Read-only — no side effects.

Instructions

1. Run which ngrok to find the binary path
2. If found, run ngrok version to get the version string
3. Report: installed (yes/no), path, version
4. If not found, report that ngrok is not installed and suggest running the ngrok-install agent

Tools

• Bash (read-only commands only: which, ngrok version)

---

ngrok-install

Installs ngrok via the official apt repository. Falls back to direct download if apt fails (e.g., missing sudo permissions).

Instructions

1. First run the ngrok-detect agent logic — skip install if already present
2. Primary method (apt repo):

   curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null
   echo "deb https://ngrok-agent.s3.amazonaws.com buster main" | sudo tee /etc/apt/sources.list.d/ngrok.list
   sudo apt-get update && sudo apt-get install -y ngrok

3. Fallback (direct download): If apt fails, download the binary directly:

   curl -sSL https://bin.equinox.io/c/bNyj1mQVY4c/ngrok-v3-stable-linux-amd64.tgz | tar xz -C /usr/local/bin

4. Verify installation with ngrok version
5. Do NOT use snap — it is unreliable on WSL2

Tools

• Bash

---

ngrok-validate

Verifies that ngrok is properly configured: correct version, valid config file, and authtoken status. Never displays or stores the authtoken value.

Instructions

1. Run ngrok version — confirm v3+
2. Run ngrok config check — report whether the config file is valid
3. Check if an authtoken is configured: inspect the config YAML at ~/.config/ngrok/ngrok.yml (or ~/.ngrok2/ngrok.yml for older setups). Report only whether a token is present (yes/no) — never print the token value
4. If no authtoken is found, instruct the user to run ngrok config add-authtoken <TOKEN> with their token from https://dashboard.ngrok.com/get-started/your-authtoken
5. Summarize: version, config status, authtoken configured (yes/no)

Tools

• Bash (ngrok version, ngrok config check)
• Read (config YAML — redact any token values in output)

---

ngrok-test-tunnel

Starts an ngrok tunnel on port 8000, verifies connectivity via the local API, then tears it down.

Instructions

1. Confirm port 8000 is not already in use: lsof -i :8000
2. Start ngrok in the background: ngrok http 8000 &
3. Wait briefly (2-3 seconds) for the tunnel to establish
4. Query the local ngrok API to get the public URL:

   curl -s http://localhost:4040/api/tunnels | python3 -m json.tool

5. Report the public HTTPS URL
6. Clean up: Kill the background ngrok process (kill %1 or pkill -f 'ngrok http 8000')
7. Confirm the process is terminated

Tools

• Bash

---

ngrok-setup-orchestrator

Runs the full ngrok setup pipeline: detect → install → validate → test. Stops on failure and reports remediation steps.

Instructions

1. Detect: Run ngrok-detect logic. If ngrok is found, skip to step 3
2. Install: Run ngrok-install logic. If installation fails, stop and report the error with remediation steps
3. Validate: Run ngrok-validate logic. If authtoken is missing, stop and ask the user to configure it before proceeding
4. Test tunnel: Run ngrok-test-tunnel logic. Report the public URL on success
5. Summary: Print a final status table:

   Step	Status
   Detection	OK / Not found
   Installation	OK / Skipped / Failed
   Validation	OK / Needs authtoken
   Tunnel test	OK / Failed

If any step fails, stop immediately and provide clear remediation instructions. Do not continue to subsequent steps.

Tools

• Agent (invokes the four agents above in sequence)
• Bash (for any direct verification)