RelayAI Local Bridge

This package lets a local machine claim a RelayAI bridge session and process incoming app messages using a local Claude or Codex runtime.

Prerequisites

Before starting the RelayAI bridge on a machine, install and authenticate any local runtimes you want that bridge to support.

Claude Code

RelayAI does not install Claude Code for you. Install Claude Code locally first, then make sure it can start successfully from your terminal.

Official setup docs:

• Anthropic Claude Code setup

Typical install:

npm install -g @anthropic-ai/claude-code
claude

Notes:

• Anthropic's current docs list Node.js 18+ as a prerequisite.
• Run claude once and complete authentication before using Claude-backed bridge sessions.

Codex CLI

RelayAI does not install Codex for you. Install the Codex CLI locally first, then make sure it is authenticated and runnable from your terminal.

Official sources:

• OpenAI Codex GitHub repository
• Codex install docs in the repository

Typical install:

# npm
npm install -g @openai/codex

# or Homebrew on macOS
brew install --cask codex

# then start Codex and complete sign-in
codex

Notes:

• The current Codex README documents npm install -g @openai/codex and brew install --cask codex.
• Run codex once and complete either ChatGPT sign-in or API-key setup before using Codex-backed bridge sessions.
• RelayAI uses the local codex CLI and codex app-server; the bridge will report Codex as unavailable until the CLI is installed and authenticated.

What it does

1. Authenticates as a paired bridge device
2. Waits for a RelayAI bridge-session announcement from the app
3. Subscribes to /api/sessions/{id}/events/stream
4. Watches for new user messages
5. Runs Claude or Codex locally on your machine
6. Streams assistant deltas back to RelayAI
7. Returns to idle when a session is stopped in the app

Install

Recommended install for users:

python3 -m pip install --upgrade relayai-local-bridge

That installs the published RelayAI bridge package from PyPI. It does not install Claude Code or Codex CLI for you.

If you are working from a local RelayAI checkout and want the unreleased repo version instead:

cd local-bridge
python3 -m pip install .

Update an existing bridge

For most users:

python3 -m pip install --upgrade relayai-local-bridge

If you are updating from a local RelayAI checkout after pulling new repo changes:

cd /Users/alexnuccio/Documents/projects/RelayAI/local-bridge
python3 -m pip install --upgrade .

You do not need to pair again after a normal bridge update. Re-pair only if you intentionally switch to a different RelayAI account or want to clear the saved bridge credentials.

First run

Preferred launch command:

relayai-local-bridge \
  --base-url https://relay.nrsoftware.ai \
  --cwd /path/to/local/repo \
  --claude-cli-path "$(command -v claude)" \
  --codex-cli-path "$(command -v codex)"

Those CLI-path flags are optional. The bridge can still run without them, but passing the explicit local executable paths is the preferred setup because it makes the runtime choice unambiguous and avoids depending on whatever binary the SDK or shell happens to resolve by default.

Minimal launch command:

relayai-local-bridge \
  --base-url https://relay.nrsoftware.ai \
  --cwd /path/to/local/repo

If the bridge is not paired yet, it prints a one-time pairing code. Approve that code in the app under Settings -> Bridge Pairing.

After approval, the bridge stores its own credentials locally and reuses them automatically.

Re-pair to a new account or phone

If you sign into RelayAI with a different account, or you want this machine to pair again from scratch, clear the stored bridge credentials and rerun the bridge:

relayai-local-bridge \
  --base-url https://relay.nrsoftware.ai \
  --cwd /path/to/local/repo \
  --reset-auth

That removes the saved bridge authentication for this machine and starts a fresh pairing flow. Approve the new one-time pairing code in the app under Settings -> Bridge Pairing.

If an older installed bridge exits with Invalid refresh token., run the same command with --reset-auth once. Newer bridge versions clear expired bridge credentials automatically and start pairing again.

Optional flags

• --session-id to attach to an existing RelayAI session
• --ca-bundle to point Python at a specific trusted CA bundle if your local OpenSSL trust store cannot validate the RelayAI certificate chain
• --reset-auth to clear stored bridge credentials and force a new pairing flow
• --credentials-file to override the default credential storage location
• --claude-cli-path to override the Claude CLI path for bridge-backed Claude sessions
• --codex-cli-path to override the Codex CLI path for bridge-backed Codex sessions
• --verbose to enable debug-level bridge, Claude, and Codex runtime logs
• --log-level DEBUG|INFO|WARNING|ERROR to set the bridge log level explicitly

Debugging

For verbose bridge logs while debugging a stuck session:

relayai-local-bridge \
  --base-url https://relay.nrsoftware.ai \
  --cwd /path/to/local/repo \
  --verbose

You can also set RELAYAI_VERBOSE=1 or RELAYAI_LOG_LEVEL=DEBUG.

Verbose logs include:

• RelayAI event receipt for each bridge session
• Claude and Codex turn start/completion details
• first runtime text delta timing
• approval request and resolution flow
• watchdog checks and recovery reasons
• Codex app-server request/notification and stderr tracing

Notes

• --cwd should point at the local repo you want Claude or Codex to work in.
• The published bridge package version is tracked in pyproject.toml and init.py.
• Your local Claude CLI/login must already be working on that machine before you start Claude bridge sessions.
• Your local Codex CLI/login must already be working on that machine before you start Codex bridge sessions.
• The bridge updates the session cwd so RelayAI reflects the local execution path.
• On startup the bridge reports which integrations are available on the machine so the iPhone app can offer only supported bridge runtimes.
• If you omit --session-id, the bridge stays idle until you press Refresh on the app home page and the app announces active bridge sessions.
• The bridge logs when it starts, when it claims a session, and when a session is stopped/released.