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 Framer MCP while the plugin remains the chat, progress, cancellation, and result interface.
The Framer harness receives only these project-scoped tools:
framer_readandframer_editframer_instructionsandframer_view_imageframer_plan_task,framer_verify_interactions, andframer_read_website
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-v4. Dexter does not model
Framer's interaction features: the model builds behaviors with any capability
the Framer guidance documents, declares each behavior with the nodes that
should carry it, and then names the Framer property that carries it on each
node (for example loopEffect or link). The bridge confirms that property on
the live node. Results are verified, contradicted (the value differs), or
unknown (the property was not found). Unknown never blocks edits and is
reported as unverified; an unchecked target or a contradiction leaves the run
incomplete.
Account connection is handled inside Dexter and completes before the model starts:
- The user connects a Framer account once. Dexter stores the refresh token encrypted and gives the bridge only a short-lived access token.
- The bridge opens the project through Framer MCP. Edits on a published project land on a Framer branch, and Dexter says so.
- Disconnecting in Dexter, or revoking Dexter in Framer, stops later runs until the account is connected again.
The user never creates a project API key. The refresh token stays on the API.
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_inspectandworkspace_syncfor the disposable source tree.shell_runfor package installation, code generation, tests, builds, and other project commands in the isolated build worker.preview_controlandbrowser_controlfor the live application.data_inspectfor owner-scoped, redacted development data.verification_runfor 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.
The service keeps itself current. When Dexter names a newer bridge release and
no run is in progress, it runs brew update and brew upgrade, then restarts
on the new version. It tries at most once an hour and keeps running the current
version if the upgrade fails. Logs are in $(brew --prefix)/var/log/dexter-bridge.log.
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 start --agent cursor
npx @gakim-digital/dexter-bridge status
npx @gakim-digital/dexter-bridge doctor
npx @gakim-digital/dexter-bridge logout
Cursor needs the Cursor CLI signed in on the same computer
(curl https://cursor.com/install -fsS | bash, then cursor-agent login).
The bridge runs cursor-agent acp with Cursor's shell, file, and web tools
denied, so Cursor can use only Dexter's Framer tools. Set
DEXTER_BRIDGE_CURSOR_BIN if cursor-agent is installed elsewhere.
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