Hypha Debugger

A lightweight, injectable debugger for web pages and Python processes, powered by Hypha RPC. Designed for AI agent workflows — inject a debugger, get a URL, call it remotely.

No browser extension required. Just import and start.

┌─────────────────────────┐         ┌──────────────┐         ┌─────────────────────────┐
│  Target (Browser/Python) │ ──WS──▶ │ Hypha Server │ ◀──WS── │  Remote Client           │
│                          │         │              │         │  (curl / Python / Agent)  │
│  - Registers debug svc   │         │  Routes RPC  │         │  - Calls debug functions  │
│  - Executes remote code  │         │  messages    │         │  - Takes screenshots      │
│  - Returns results       │         │              │         │  - Queries DOM/state      │
└─────────────────────────┘         └──────────────┘         └─────────────────────────┘

The hyd CLI — talk to any remote with minimal overhead

Installing this package also gives you the hyd command — the low-overhead way for an agent (or you) to drive a remote target. Store the connection once as a profile, then every command is a short hyd sh '…' / hyd js '…' with the connection + working directory remembered — far fewer tokens than re-sending authenticated curl. One CLI drives both target types:

pip install hypha-debugger            # or: pipx install hypha-debugger  (always on PATH)

# Terminal target (a Python process running this debugger):
hyd profile add box "<py-debugger-service-url>"          # type inferred = terminal
export HYD_PROFILE=box
hyd sh 'uname -a && pwd'              # remote shell   | hyd 'ls -la' (bare form)
hyd py 'import sys; sys.version'      # remote Python via execute_code

# Browser target (a Hypha Navigator web service):
hyd profile add web "<navigator-service-url>" --type browser
export HYD_PROFILE=web
hyd 'document.title'                 # bare form runs JavaScript on a browser profile
hyd nav 'https://example.com'        # navigate   | hyd shot page.png  (screenshot)
hyd call get_browser_state           # call any service function

hyd status                           # confirm the connection

The current profile + directory live in the HYD_PROFILE / HYD_CWD environment variables (per-terminal, nothing session-specific on disk); the remote stays stateless. If hyd isn't on your PATH after a --user install, use python -m hypha_debugger.cli (identical arguments). Run hyd with no args for help.

Any debugger's GET <service-url>/get_skill_md includes these same bootstrap instructions, so an AI agent can self-install and connect from the URL alone.

JavaScript (Browser)

Inject into any web page to enable remote DOM inspection, screenshots, JavaScript execution, and React component tree inspection.

Quick Start

Via CDN (easiest):

<script src="https://cdn.jsdelivr.net/npm/hypha-rpc@0.20.97/dist/hypha-rpc-websocket.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/hypha-debugger/dist/hypha-debugger.min.js"></script>
<script>
  hyphaDebugger.startDebugger({ server_url: 'https://hypha.aicell.io' });
</script>

Via npm:

npm install hypha-debugger hypha-rpc

import { startDebugger } from 'hypha-debugger';

const session = await startDebugger({
  server_url: 'https://hypha.aicell.io',
});

console.log(session.service_url); // HTTP endpoint for remote calls
console.log(session.token);       // JWT token for authentication

What You Get

After starting, the debugger prints:

[hypha-debugger] Connected to https://hypha.aicell.io
[hypha-debugger] Service URL: https://hypha.aicell.io/ws-xxx/services/clientId:web-debugger
[hypha-debugger] Token: eyJ...
[hypha-debugger] Test it:
  curl 'https://hypha.aicell.io/ws-xxx/services/clientId:web-debugger/get_page_info' -H 'Authorization: Bearer eyJ...'

A floating debug overlay (🐛) appears on the page with connection status, service URL (with copy button), and a live log of remote operations.

Service Functions (JavaScript)

All functions are callable via the HTTP URL or Hypha RPC:

Calling via curl

# Get page info
curl 'SERVICE_URL/get_page_info' -H 'Authorization: Bearer TOKEN'

# Take a screenshot
curl 'SERVICE_URL/take_screenshot' -H 'Authorization: Bearer TOKEN'

# Execute JavaScript
curl -X POST 'SERVICE_URL/execute_script' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"code": "document.title"}'

# Query DOM
curl -X POST 'SERVICE_URL/query_dom' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"selector": "button"}'

# Click a button
curl -X POST 'SERVICE_URL/click_element' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"selector": "#submit-btn"}'

Calling via Python

from hypha_rpc import connect_to_server

server = await connect_to_server({
    "server_url": "https://hypha.aicell.io",
    "workspace": "WORKSPACE",
    "token": "TOKEN",
})
debugger = await server.get_service("web-debugger")

info = await debugger.get_page_info()
screenshot = await debugger.take_screenshot()
result = await debugger.execute_script(code="document.title")
tree = await debugger.get_react_tree()

Configuration

await startDebugger({
  server_url: 'https://hypha.aicell.io', // Required
  workspace: 'my-workspace',              // Optional, auto-assigned
  token: 'jwt-token',                     // Optional
  service_id: 'web-debugger',             // Default: 'web-debugger'
  service_name: 'Web Debugger',           // Default: 'Web Debugger'
  show_ui: true,                          // Default: true (floating overlay)
  visibility: 'public',                   // 'public' | 'protected' | 'unlisted'
});

Python

Inject into any Python process to enable remote code execution, variable inspection, file browsing, and process monitoring.

Quick Start

pip install hypha-debugger

CLI (simplest — just run and get instructions):

hypha-debugger

Or with options:

hypha-debugger --server-url https://hypha.aicell.io --service-id my-debugger
hypha-debugger --no-token  # URL-secret mode, no auth needed
python -m hypha_debugger   # alternative

Async:

import asyncio
from hypha_debugger import start_debugger

async def main():
    session = await start_debugger(server_url="https://hypha.aicell.io")
    session.print_instructions()  # print instructions anytime
    await session.serve_forever()

asyncio.run(main())

Sync (scripts, notebooks):

from hypha_debugger import start_debugger_sync

session = start_debugger_sync(server_url="https://hypha.aicell.io")
session.print_instructions()  # print instructions anytime

What You Get

The debugger prints copy-paste instructions on startup:

[hypha-debugger] Connected to https://hypha.aicell.io
[hypha-debugger] Service ID: ws-xxx/clientId:py-debugger
[hypha-debugger] Service URL: https://hypha.aicell.io/ws-xxx/services/py-debugger

SERVICE_URL="https://hypha.aicell.io/ws-xxx/services/py-debugger"
TOKEN="eyJ..."

# Quick test:
curl "$SERVICE_URL/get_process_info?_mode=last" -H "Authorization: Bearer $TOKEN"

# Execute code:
curl -X POST "$SERVICE_URL/execute_code?_mode=last" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"code": "import sys; sys.version"}'

Call session.print_instructions() anytime to reprint them.

Service Functions (Python)

Calling via curl

# Get process info
curl 'SERVICE_URL/get_process_info' -H 'Authorization: Bearer TOKEN'

# Execute Python code
curl -X POST 'SERVICE_URL/execute_code' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"code": "2 + 2"}'

# List files
curl 'SERVICE_URL/list_files' -H 'Authorization: Bearer TOKEN'

# Read a file
curl -X POST 'SERVICE_URL/read_file' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"path": "main.py"}'

Calling via Python (remote client)

from hypha_rpc import connect_to_server

server = await connect_to_server({
    "server_url": "https://hypha.aicell.io",
    "workspace": "WORKSPACE",
    "token": "TOKEN",
})
debugger = await server.get_service("py-debugger")

info = await debugger.get_process_info()
result = await debugger.execute_code(code="import sys; sys.version")
files = await debugger.list_files()

How It Works

1. Your target (browser page or Python process) connects to a Hypha server via WebSocket
2. It registers an RPC service with schema-annotated functions
3. The debugger prints a Service URL and Token
4. Remote clients call service functions via HTTP REST or Hypha RPC WebSocket
5. All functions have JSON Schema annotations, making them compatible with LLM/AI agent tool calling

License

MIT