@klavy/local-bridge

Node CLI agent for the Klavy Remote Local Bridge. It connects to the Klavy ActionCable WebSocket with a bearer token, reports local Claude/Codex/Gemini health, receives invoke jobs, runs local provider CLIs, and sends job lifecycle messages back over the cable.

Install

npx @klavy/local-bridge install-service --server https://klavy.app --token <token>

Or install the command globally:

npm install -g @klavy/local-bridge

For local development in this repository:

cd packages/local-bridge-agent
npm install
npm test

Commands

npx @klavy/local-bridge install-service --server https://klavy.app --token <token>
npx @klavy/local-bridge connect --server https://klavy.app --token <token>
klavy-local-bridge connect --server https://klavy.app --token <token>
klavy-local-bridge status
klavy-local-bridge service-status
klavy-local-bridge disconnect
klavy-local-bridge uninstall-service

install-service is the recommended macOS setup. It writes the token to ~/.config/klavy-local-bridge/config.json with 0600 permissions and installs a LaunchAgent at ~/Library/LaunchAgents/app.klavy.local-bridge.plist. The plist runs the bridge with --config and does not contain the token.

connect also reads these environment variables:

| Variable | Purpose | | --- | --- | | KLAVY_CABLE_URL | Full ActionCable WebSocket URL. | | KLAVY_CABLE_ORIGIN | WebSocket Origin header; inferred from the cable URL by default. | | KLAVY_URL | Base app URL; /cable is inferred. | | KLAVY_BRIDGE_TOKEN | Bearer token sent as Authorization: Bearer .... | | KLAVY_LOCAL_BRIDGE_CHANNEL | ActionCable channel, default LocalBridgeChannel. | | KLAVY_CLAUDE_BIN | Claude Code binary, default claude. | | KLAVY_CODEX_BIN | Codex CLI binary, default codex. | | KLAVY_GEMINI_BIN | Gemini CLI binary, default gemini. | | KLAVY_CODEX_MODEL | Default Codex model, default gpt-5.4. |

Use --url wss://.../cable only when you need to pass a full ActionCable URL directly.

Wire Protocol

The agent subscribes to LocalBridgeChannel by default. Server frames with message.type, message.event, or message.action equal to invoke are treated as jobs.

An invoke job should include:

{
  "type": "invoke",
  "job": {
    "id": "job_123",
    "provider": "claude",
    "request": {
      "system": "You are helpful.",
      "messages": [{ "role": "user", "content": "Hello" }],
      "model": "gpt-5.4"
    }
  }
}

The agent performs channel actions named:

• heartbeat
• accepted
• chunk
• completed
• failed

The bridge supports claude, openai, and gemini. codex is accepted as an alias for openai.