@synchronex/agent-bridge

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.

Most Synchronex users do not need the auto-start daemon. The managed web app is the default path, and foreground run is the reliable local bridge path when you want subscription routing from your machine.

Usage

npx @synchronex/agent-bridge@latest setup

Setup checks Node, validates local AI provider CLIs, opens browser pairing when needed, and ends with a clear checklist. If a provider install or login is blocked, setup tells you the exact next command and leaves Synchronex on managed cloud generation instead of dead-ending.

When setup is complete, start the bridge in the foreground:

npx @synchronex/agent-bridge@latest run

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, the bridge validates installed local CLIs before reporting them as session capabilities. Presence and credential files are not enough: each provider must pass a bounded headless request so stale logins or interactive prompts fall back to managed compute cleanly.

• cli:claude when Claude Code is installed, signed in, and validates
• cli:codex when Codex CLI is installed, signed in, and validates
• cli:gemini when Gemini CLI is installed, signed in, and validates
• cli:cursor when Cursor CLI is installed, signed in, and validates

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 validates it before connect. Heartbeats reuse a short-lived validation cache to avoid repeatedly spending provider requests.

The canonical setup command is npx @synchronex/agent-bridge@latest setup. Copy-paste setup details for Node, Claude Code, Codex CLI, Gemini CLI, Cursor CLI, and the bridge are in docs/SETUP.md.

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 run in the foreground
npx @synchronex/agent-bridge setup              # check Node, vendor CLIs, auth, pairing, and fallback path
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            # show the foreground-run path and advanced daemon instructions
npx @synchronex/agent-bridge install --daemon   # advanced: 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 [e-mail]  # revoke + remove one account

Foreground bridge

Run connect first, then run when you want local subscription routing:

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

Advanced background service

Auto-start is optional and advanced. It is useful only if you explicitly want the bridge to run at every login without a terminal open:

npx @synchronex/agent-bridge install --daemon

The daemon installer creates a per-user service only:

• macOS: ~/Library/LaunchAgents/ai.synchronex.agent-bridge.plist
• Windows: %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\SynchronexAgentBridge.cmd launching 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.

Advanced setup and Windows troubleshooting: docs/agent-bridge-setup.md.

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)
SYNCHRONEX_BRIDGE_AUTH_VALIDATION_TIMEOUT_MS	Timeout for provider validation probes. Default: 8000
SYNCHRONEX_BRIDGE_AUTH_VALIDATION_CACHE_MS	Cache duration for provider validation results during a bridge session. Default: 600000
AGENT_BRIDGE_HEADLESS_TIMEOUT_MS	Timeout for non-interactive provider requests. Default: 240000

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+
• Optional for managed compute, required for local subscription routing: at least one supported provider CLI installed, signed in, and validated. Supported providers are Claude Code, OpenAI Codex CLI, Gemini CLI, and Cursor CLI.