Local Agent Bridge

Local bridge CLI for InstaWebAI and Dexter. It connects a user's existing Codex, Claude Code, or OpenCode setup without sending those login credentials to InstaWebAI.

The two products share the bridge package but not their pairing state. The API assigns the product identity during pairing; the CLI cannot turn one product's pairing code into another product's connection.

InstaWebAI App Builder

The Connections page offers separate Codex, Claude Code, and OpenCode cards. Choose an agent, copy its command, and keep that terminal open while building:

npx --yes @gakim-digital/dexter-bridge@latest connect 123456 \
  --api https://api-insta.instawebai.com/iwm-api/0.0.1 \
  --runtime codex

Use --runtime claude-code or --runtime opencode for the other cards. The CLI automatically stores each connection in an isolated directory under ~/.dexter-bridge/app-builder/, so any combination of the three agents can be connected at the same time. The selected runtime must already be installed and signed in or configured on the same computer.

The pairing session is scoped to the runtime selected in InstaWebAI. A modified command cannot claim the pairing code for a different runtime.

Dexter for Framer

Dexter Framer runs are harness-first. The API sends one scoped outcome assignment to the connected Codex, Claude Code, or OpenCode runtime. That harness inspects and edits the selected Framer project directly through the official @framer/agent connection while the plugin remains the chat, progress, cancellation, and result interface.

The Framer harness receives only these project-scoped tools:

• framer_instructions and framer_context
• framer_read_project, framer_verify_interactions, and framer_apply_changes
• restricted framer_read and framer_write
• progress_update

Native shell, filesystem, web, and unrelated-project access are disabled for Framer outcome runs. Publishing is denied unless a future assignment explicitly authorizes it.

Bridges advertise framer-interaction-verification-v3, framer-behavior-contract-v1, and framer-mechanism-verification-v1 only when interaction work is declared as observable behavior, checked against the selected Framer mechanism before mutation, and verified from live canonical Framer nodes afterward. Verification is tri-state: verified, contradicted, or unknown. Unknown evidence cannot trigger a repair or reject a mechanism. Native navigation is verified from link and component control destinations instead of requiring synthetic frame events. Repeated behavior is verified on one declared representative target before the remaining targets are changed. Only a concrete contradiction may receive one scoped SET repair. Repeated unchanged evidence is bounded and exits as a partial result rather than looping.

Project connection is handled inside Dexter and completes before the model starts:

• The plugin reads the exact active project or branch URL directly from Framer.
• The user adds a Framer project API key once in Dexter. The API verifies it through Framer's documented connect(projectId, apiKey) plus getProjectInfo() flow, then encrypts and stores it only after that succeeds.
• The active hosted runtime redeems that verified credential only for the matching run and device, then installs it with Framer’s official project auth command against the authoritative 20-character project ID.
• The runtime opens an official Framer Agent session, reads the active branch back from Framer, and confirms the authoritative project ID again.
• Rejected credentials are revoked. Replacing a key creates a new credential version, so a cached runtime session cannot reuse the replacement.
• Hosted worker images bundle the Framer skills and seed them into each runtime's private writable home before processing runs.

The user never runs @framer/agent setup, project auth, or session new. The raw project credential is scoped to the matching active run and paired device, is excluded from run payloads and logs, and is never sent to the Framer plugin after the one-time authenticated submission.

The bridge reports provider token usage on terminal events, including interrupted and cancelled runs. Claude-reported dollar cost is stored when available; Codex token-only runs are priced by the API’s model cost catalog so they no longer appear as zero-cost runs.

On macOS, the bridge holds an idle-sleep assertion only while a claimed run is active, then releases it immediately afterward. Closing a laptop lid can still suspend local processes; uninterrupted lid-closed execution requires running the bridge on an always-on machine or a hosted harness runner.

For App Builder runs, planning remains server-owned. Once the workflow contract, data model, dependencies, and design direction are ready, the bridge receives one bounded product outcome plus a disposable source snapshot. The selected harness implements the complete functional outcome in that isolated workspace. The API then validates and applies the changed files and runs its own type, authorization, API-contract, browser-workflow, responsive, and visual checks. A failed verification is returned as one grouped repair brief, with at most three complete attempts before the saved workspace is paused for review.

Every supported coding harness receives the same seven tools:

• workspace_inspect and workspace_sync for the disposable source tree.
• shell_run for package installation, code generation, tests, builds, and other project commands in the isolated build worker.
• preview_control and browser_control for the live application.
• data_inspect for owner-scoped, redacted development data.
• verification_run for deterministic and browser workflow checks.

Codex receives these as native dynamic tools. Claude Code and OpenCode receive the same contract through a local, token-protected MCP bridge. Commands never run through the bridge machine's shell. The API delegates them to a project-confined build worker with an offline default; only script-disabled npm dependency commands receive registry access. The API remains the authority for project ownership, protected platform files, data access, command execution, and final verification.

When a dependency requires a lifecycle build, the harness can run npm rebuild as a separate offline command after installation. This allows package code to prepare itself without combining arbitrary script execution with internet access.

Claude Code on macOS

Dexter's Claude setup wizard uses Homebrew so the bridge starts automatically at login and the user can close Terminal after setup. The wizard fills in the pairing code, API URL, agent, and model:

brew install gakim-digital/tap/dexter-bridge \
  && dexter-bridge pair 123456 --api https://api-insta.instawebai.com/iwm-api/0.0.1 --agent claude-code --model claude-code:sonnet \
  && brew services restart gakim-digital/tap/dexter-bridge

Claude Code must already be installed and signed in on the same Mac. Pairing records the resolved Claude executable path in ~/.dexter-bridge/config.json so the background service can find installations managed by NVM or another shell-specific tool.

Useful service commands:

brew services info gakim-digital/tap/dexter-bridge
brew services restart gakim-digital/tap/dexter-bridge
brew services stop gakim-digital/tap/dexter-bridge
dexter-bridge status
dexter-bridge doctor

Users without Homebrew can select the temporary command in the wizard. That uses npx and must remain open while Dexter is using Claude Code.

Temporary CLI connection

One command pairs and goes online — the Dexter plugin's Connect wizard prints it with your pairing code and API URL filled in:

npx --yes @gakim-digital/dexter-bridge@latest connect 123456 --api https://api-insta.instawebai.com/iwm-api/0.0.1 --agent codex

Run connect with no code to reuse a saved pairing. Lower-level commands remain for support and automation:

npx @gakim-digital/dexter-bridge pair 123456 --api http://localhost:3800/iwm-api/0.0.1
npx @gakim-digital/dexter-bridge start --agent claude-code
npx @gakim-digital/dexter-bridge start --agent codex
npx @gakim-digital/dexter-bridge status
npx @gakim-digital/dexter-bridge doctor
npx @gakim-digital/dexter-bridge logout

On Windows, the bridge checks the native Claude Code install at %USERPROFILE%\.local\bin\claude.exe in addition to PATH. Before pairing, verify the same PowerShell window can run:

claude --version
claude auth status

If Claude Code is installed in a custom directory, set its absolute path for that PowerShell session before running the Dexter command:

$env:DEXTER_BRIDGE_CLAUDE_BIN = "C:\path\to\claude.exe"

dry-run verifies pairing, run polling, and event delivery without editing the canvas. claude-code executes through its local CLI. Codex uses one persistent codex app-server process for authentication, threads, usage, and cancellation:

DEXTER_BRIDGE_AGENT=claude-code npx @gakim-digital/dexter-bridge start
DEXTER_BRIDGE_AGENT=codex npx @gakim-digital/dexter-bridge start

The bridge discovers models from the signed-in local runtime instead of relying on a release-time list. Claude Code models come from the official Agent SDK's supportedModels() result, and Codex models come from every page of App Server's model/list result. The desktop bridge refreshes this catalog during its normal heartbeat loop; the CLI refreshes it every five minutes.

Codex App Server runs planning turns as a model-only engine in a dedicated empty temporary workspace. For an App Builder outcome, it receives a disposable snapshot and workspace-write access only inside that snapshot; network, app, hook, memory, multi-agent, MCP, plugin, image, and web access remain disabled. The bridge reads the effective Codex provider configuration and forwards only environment variables explicitly referenced by that provider, such as an env_key; unrelated process secrets remain excluded. The configured provider is preferred, with a cached OpenAI/ChatGPT account used as a fallback when its required provider credentials are unavailable. Planning sessions may be reused; each coding outcome uses a fresh isolated workspace. The bridge retains at most 32 recent Codex threads by default; override this with DEXTER_BRIDGE_CODEX_MAX_THREADS.

The CLI stores the device token in ~/.dexter-bridge/config.json with mode 0600 where supported. The macOS desktop app stores the token through Electron safeStorage, backed by the user’s macOS credential encryption. Dexter platform credits are not charged for companion runs; the backend records reported usage for visibility.

Production API endpoints must use HTTPS. Plain HTTP is accepted only for exact localhost loopback addresses during local development.

Claude Code planning turns run as a model-only engine. App Builder outcome runs enable local read/write/edit/search tools inside the disposable snapshot plus the strict InstaWebAI MCP tool set. Shell checks, previews, browser actions, redacted data inspection, and verification execute through the server-owned workspace boundary; local shell, network, and external-directory access stay disabled. The bridge supplies a strict JSON schema and a product-specific system prompt.

Claude Code runs use streaming JSON and Codex runs use JSONL so the bridge can report input, output, cache, and reasoning tokens even when a turn is interrupted. Claude's reported total_cost_usd is displayed as an estimated API-equivalent cost, not an amount Dexter charged. If an older or customized CLI does not support structured output, set DEXTER_BRIDGE_STRUCTURED_USAGE=false; the run will continue, but its token usage will be marked unavailable rather than estimated from text.

DEXTER_BRIDGE_AGENT_TIMEOUT_MS is the inactivity limit and resets whenever the local model produces output. DEXTER_BRIDGE_AGENT_MAX_DURATION_MS is the hard wall-clock ceiling; the API may supply a smaller per-turn ceiling from the remaining run budget. Claude defaults to low effort for the intent-planner lane and follow-up/recovery turns, and medium effort for the opening design turn. Override these with DEXTER_BRIDGE_CLAUDE_PLANNER_EFFORT, DEXTER_BRIDGE_CLAUDE_MAIN_EFFORT, DEXTER_BRIDGE_CLAUDE_FOLLOWUP_EFFORT, or DEXTER_BRIDGE_CLAUDE_EFFORT.

Debugging

The Dexter Bridge terminal is the shell where dexter-bridge start is running. For each companion run, the bridge also writes a redacted JSONL trace:

~/.dexter-bridge/logs/run-<runId>.jsonl

Set DEXTER_BRIDGE_LOG_DIR=/path/to/logs to override the location. The desktop app writes the same run traces next to its app log; use Reveal log in the desktop window to open that folder.

Useful events in a stuck run:

• model_turn / agent_process_spawn — Claude Code or Codex was invoked.
• outcome — a harness is implementing the complete bounded product outcome.
• agent_process_timeout — the local agent did not return before the timeout.
• event_post_done — the bridge returned a model completion to the shared server loop.
• run_done — the local model turn or outcome completed.

Desktop release

From framer-plugin:

npm run bridge:desktop:dev
npm run bridge:desktop:build:mac
npm run bridge:desktop:build:win
npm run bridge:desktop:dist
npm --prefix packages/dexter-bridge-desktop run verify:mac
npm --prefix packages/dexter-bridge-desktop run verify:win

The Mac build emits .dmg and .zip artifacts from packages/dexter-bridge-desktop/release.

The Windows x64 build emits an NSIS .exe installer and a .zip artifact from the same release directory. Build it on Windows directly or through .github/workflows/dexter-bridge-windows.yml; Windows packaging must not depend on a developer’s macOS environment.

Release builds automatically sign when a Developer ID identity is available to electron-builder. Notarization runs from afterSign when either App Store Connect API credentials (APPLE_API_KEY, APPLE_API_KEY_ID, APPLE_API_ISSUER) or Apple ID credentials (APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, APPLE_TEAM_ID) are configured. Set DEXTER_REQUIRE_NOTARIZATION=true in release CI so missing credentials fail the build instead of producing an unnotarized artifact.

Windows signing is configured through electron-builder’s standard certificate environment variables, such as CSC_LINK and CSC_KEY_PASSWORD. Set DEXTER_REQUIRE_WINDOWS_SIGNING=true when running verify:win for a public release. Unsigned installers are only suitable for internal testing.

The unsigned desktop app is not the public Claude setup path. Until a notarized build is available, macOS Claude users should receive the Homebrew service flow above.

Recommended release env:

FRAMER_COMPANION_DOWNLOAD_URL=https://instawebai.com/dexter-bridge
NEXT_PUBLIC_DEXTER_BRIDGE_VERSION=0.11.5
NEXT_PUBLIC_DEXTER_BRIDGE_DOWNLOAD_BASE_URL=https://instawebai.com/downloads/dexter-bridge
NEXT_PUBLIC_DEXTER_BRIDGE_MAC_ARM64_URL=https://instawebai.com/downloads/dexter-bridge/Dexter-Bridge-0.11.5-mac-arm64.dmg
NEXT_PUBLIC_DEXTER_BRIDGE_MAC_X64_URL=https://instawebai.com/downloads/dexter-bridge/Dexter-Bridge-0.11.5-mac-x64.dmg
NEXT_PUBLIC_DEXTER_BRIDGE_MAC_ZIP_URL=https://instawebai.com/downloads/dexter-bridge/Dexter-Bridge-0.11.5-mac-universal.zip
NEXT_PUBLIC_DEXTER_BRIDGE_WIN_X64_URL=https://instawebai.com/downloads/dexter-bridge/Dexter-Bridge-0.11.5-win-x64.exe