@gluecharm-lab/bridge

Local daemon that connects the Gluecharm web app (gluecharm.com) with the Gluecharm Cursor/VS Code extension. It runs on your machine and is only reachable on localhost.

Install and run

Install from npm (published package): npm install -g @gluecharm-lab/bridge or use npx @gluecharm-lab/bridge start. See User manual: Install and run from npm for details.

Install (local development)

npm install
npm run build
npm link

Start the bridge

gluecharm-bridge start

Or without linking (e.g. from another machine or via npx):

npx gluecharm-bridge start

The bridge picks a free port (typically 7891, then 7892 if 7891 is in use) and writes it to ~/.gluecharm/bridge.lock along with an ephemeral secret. The Gluecharm extension reads this file to connect. You should see something like:

Gluecharm Bridge running on http://localhost:7891

(The port in the message is the one actually in use; check ~/.gluecharm/bridge.lock for the exact port and secret.)

• Credentials (SRS-17): The Technical Connect view in the web app can send GlueCharm API credentials to the bridge via POST /gluecharm/credentials (with X-Bridge-Secret). They are stored in ~/.gluecharm/credentials.json (mode 0600). The bridge refreshes the access token when expired (same policy as the frontend: 120 s before expiry) and uses the stored token for outbound GlueCharm API calls. The extension does not call the API directly; it goes through the bridge. To use a different auth API for refresh, set GLUECHARM_AUTH_API_URL (default: https://system-manager-api.staging.gluecharm.info:8092).

• Single instance: Only one Gluecharm Bridge runs per machine. If you start a second one while the first is still running, it exits with: Another Gluecharm Bridge is already running (PID …). Exiting.

• Idle shutdown: If no extension is connected for 5 minutes, the bridge exits and removes the lock file.

Test the bridge

With the bridge running in another terminal, from the repo root:

./scripts/test-bridge.sh

This reads ~/.gluecharm/bridge.lock for port and secret, then checks /ping and /bridge/register. If both succeed, the bridge is ready for the extension.

Or test manually (use the port from the console or from ~/.gluecharm/bridge.lock):

curl http://localhost:7891/ping
# → { "status": "pong", "version": "0.1.0" }

Run without linking (from repo)

npm run build
node bin/gluecharm-bridge.js start

Run acceptance criteria tests

From the repo root:

./scripts/run-ac-tests.sh

Teardown

npm unlink -g @gluecharm-lab/bridge