promethios-bridge

Run Promethios agent frameworks locally on your computer — with full access to your files, terminal, browser, and Native Framework Mode (run OpenClaw and other frameworks in their original interface, powered by the bridge).

Quick Start

npx promethios-bridge --token <your-setup-token>

Get your setup token from Promethios → Settings → Local Bridge → Generate Setup Token.

What it does

The bridge connects your computer to Promethios so that agent frameworks can execute tools locally instead of (or in addition to) the cloud sandbox.

Once running, open any thread in Promethios and use the Cloud / My Computer / Hybrid toggle in the thread header.

| Mode | What runs where | |---|---| | ☁️ Cloud | All tools run in Promethios cloud sandbox (default) | | 💻 My Computer | All tools run on your machine via this bridge | | ⚡ Hybrid | Agent decides per-tool — local for files/terminal, cloud for APIs |

Native Framework Mode (new in v1.5.0)

Native Framework Mode lets you run supported frameworks — like OpenClaw — in their original interface, while staying connected to Promethios for identity, memory, and cross-device sync.

How it works

When the bridge is running and a supported framework is detected on your machine, the Native button on the Promethios marketplace card turns green. Clicking it opens the framework's native UI through a secure bridge tunnel — no port forwarding, no CORS issues, no extra setup.

Promethios UI → /native/detect → Bridge → TCP probe localhost:18789
                                                      ↓ detected
                                         Native button turns green ✓
                                                      ↓ clicked
Promethios UI → /native/proxy/18789/ → Bridge → localhost:18789 (OpenClaw Gateway)

Supported frameworks

| Framework | Default Port | Notes | |---|---|---| | OpenClaw | 18789 | OpenClaw Gateway — full ClawHub plugin support | | OpenClaw (alt) | 18790 | Secondary instance | | Custom | 8080, 3000, 3001, 4000, 5000 | Any framework with an HTTP gateway |

Requirements

• Bridge v1.5.0+ (this version)
• The framework must be running locally before clicking Native
• For OpenClaw: start with openclaw start — the Gateway listens on port 18789 by default

What the bridge adds

The bridge exposes two new local endpoints that Promethios uses for Native mode:

| Endpoint | Purpose | |---|---| | GET /native/probe?port=18789&framework=openclaw | TCP + HTTP health check — powers the green/grey Native button state | | ALL /proxy/:port/* | Transparent HTTP proxy to localhost:<port> — tunnels the framework UI through the bridge |

Permissions

The first time a framework requests local execution, Promethios shows you exactly what it wants access to. You approve or deny each capability before anything runs.

Capabilities the bridge supports:

| Capability | What it allows | |---|---| | filesystem.read | Read files on your machine | | filesystem.write | Write files on your machine | | terminal.execute | Run shell commands | | terminal.readonly | Run read-only commands (ls, cat, etc.) | | browser.open | Open URLs in your browser | | network.http | Make HTTP requests (useful for localhost APIs) | | native.probe_port | Check if a framework gateway is running on a local port | | native.proxy | Forward HTTP requests to a local framework gateway |

Options

--token <token>   Setup token from Promethios (required on first run)
--api <url>       Promethios API base URL (default: https://api.promethios.ai)
--port <port>     Local port for the bridge server (default: 7823)
--dev             Verbose debug logging

Security

• The bridge only listens on 127.0.0.1 (localhost) — it is not accessible from the internet.
• All tool calls are authenticated and signed by the Promethios cloud.
• The proxy endpoint only allows a fixed allowlist of ports: 18789, 18790, 7788, 8080, 3000, 3001, 4000, 5000.
• Destructive commands (rm -rf /, mkfs, etc.) are blocked at the executor level.
• You can disconnect at any time with Ctrl+C.

Changelog

v1.5.0

• Native Framework Mode: probe_local_port tool + proxy_local_request tool
• New local HTTP endpoints: GET /native/probe and ALL /proxy/:port/*
• Capabilities manifest updated with native.probe_port and native.proxy
• OpenClaw v2026.3.22 support (ClawHub, per-agent reasoning, OpenShell, Exa/Tavily/Firecrawl search)

v1.4.1

• Desktop path resolution for Windows OneDrive sync
• Binary file read and upload-to-thread tools
• Playwright browser control with real Chrome profile support

v1.4.0

• Firestore relay polling for tool calls (works behind firewalls and NAT)
• Hybrid mode support
• local_shell, local_file_read, local_file_write tool aliases

License

MIT — Promethios