Synchronex Agent Bridge

Routes AI content generation through local AI CLIs on your machine, so generation can use the provider subscription you already have instead of per-token API billing.

The bridge runs as your local user, launches official provider CLIs, and sends stdout/stderr back to the connected app. It never reads, stores, or proxies provider OAuth tokens.

Usage

npx @synchronex/agent-bridge

A browser window will open to authorize the device. Once authorized, the bridge stays running and accepts generation requests from Synchronex.

For local development:

npx @synchronex/agent-bridge --app http://localhost:3000

For Tractic:

npx @synchronex/agent-bridge --app https://tractic.io

Provider CLIs

On startup and on each heartbeat, the bridge auto-detects installed local CLIs and reports their availability as session capabilities:

• cli:claude when claude --version works
• cli:codex when codex --version works
• cli:gemini when gemini --version works

No extra setup is required in the bridge. Install whichever provider CLI matches the subscription you want to use, log in once, and the bridge auto-detects it on the next heartbeat.

Installing provider CLIs

Claude Code requires a Pro, Max, Team, Enterprise, or Console account.

| Platform | Install | Login | |---|---|---| | macOS / Linux / WSL | curl -fsSL https://claude.ai/install.sh \| bash | claude | | Windows PowerShell | irm https://claude.ai/install.ps1 \| iex | claude |

ChatGPT / OpenAI Codex CLI is included with ChatGPT Plus, Pro, Business, Edu, and Enterprise plans.

| Platform | Install | Login | |---|---|---| | macOS / Windows / Linux | npm i -g @openai/codex | codex |

Gemini CLI supports Google OAuth sign-in from the CLI.

| Platform | Install | Login | |---|---|---| | macOS / Windows / Linux | npm install -g @google/gemini-cli | gemini | | macOS / Linux with Homebrew | brew install gemini-cli | gemini |

Subcommands

npx @synchronex/agent-bridge                    # auto: connect if needed, then serve every paired account
npx @synchronex/agent-bridge connect            # only run device authorization
npx @synchronex/agent-bridge add                # pair another account onto this machine (same as connect)
npx @synchronex/agent-bridge run                # start polling for every paired account (fails if none)
npx @synchronex/agent-bridge install            # install a per-user background service at login
npx @synchronex/agent-bridge uninstall          # remove the service, revoke tokens, and clear local credentials
npx @synchronex/agent-bridge uninstall --keep-token  # remove only the service; keep paired credentials
npx @synchronex/agent-bridge status             # list every paired account and its device
npx @synchronex/agent-bridge update             # update the installed binary (verifies checksum; npx: use @latest)
npx @synchronex/agent-bridge logout             # revoke + clear ALL accounts
npx @synchronex/agent-bridge logout --account [email protected]  # revoke + remove one account

Background service

Run connect first, then install to keep the bridge online after terminal close and user login:

npx @synchronex/agent-bridge connect
npx @synchronex/agent-bridge install

The installer creates a per-user service only:

• macOS: ~/Library/LaunchAgents/ai.synchronex.agent-bridge.plist
• Windows: \Synchronex\AgentBridge scheduled task with an %APPDATA%\Synchronex\agent-bridge.cmd wrapper
• Linux: ~/.config/systemd/user/synchronex-agent-bridge.service

Use uninstall to unload the service, remove service files, revoke bridge tokens server-side, and clear local credentials. Passing --keep-token removes only the daemon service.

Multiple accounts on one machine

One bridge can serve several Synchronex accounts at once — for example your primary account for daily work plus a separate test/audit account. Each account is paired independently (add while signed into that account in the browser), and the bridge runs one session per account, each authenticated with its own token. Requests are only ever claimed by the account that owns them, so accounts stay fully isolated. Re-run npx @synchronex/agent-bridge after add so the running bridge picks up the newly paired account.

Environment variables

| Variable | Description | |---|---| | SYNCHRONEX_APP_URL | Override the target app URL (alternative to --app flag) |

Skill output files

For each generation request, the bridge creates a temporary output directory and exposes it as BRIDGE_OUTPUT_DIR. Skills should write deliverable files there. After the command exits, the bridge sends those files back to the connected app as attachment events:

• Files up to 5 MiB are sent inline as base64
• Larger files are uploaded to the bridge-attachments storage bucket with a signed URL

If BRIDGE_OUTPUT_DIR is not set, skills may fall back to ./output/ for local development.

When the app includes a brand kit in the request metadata, the bridge writes it to a temporary JSON file and exposes the path as BRIDGE_BRAND_KIT_PATH. Skills can read that file for colors, logos, fonts, and tagline data.

When the app includes metadata.needsApiKeys, the bridge writes only the requested provider API keys to a temporary JSON file and exposes it as BRIDGE_AI_KEYS_PATH. The file is deleted with the request directory after the command exits.

Requirements

• Node 20+
• At least one supported provider CLI installed and authenticated: Claude Code, OpenAI Codex CLI, or Gemini CLI