elvarone-bridge

The ElvarOne phone agent's compute bridge: a small MCP server on your computer that lets the agent run Python and shell commands, take screenshots it can actually look at, publish files, and leave written reports that the coding agent on your computer (Claude Code or Codex) answers automatically.

pip install elvarone-bridge
elvarone-bridge init

init mints a token, writes ~/ElvarBridge/config.env, installs a background service (launchd on macOS, a systemd user unit on Linux, a Task Scheduler command on Windows) and prints the URL + token to enter on the phone: Settings → AI Brain → MCP Servers → Add.

Let your desktop AI set it up

Paste this to Claude Code, Codex, Cursor or any coding agent on the computer you want to connect:

Install the ElvarOne compute bridge on this computer: pip install elvarone-bridge (use a venv or pipx if you prefer), then run elvarone-bridge init --agent claude --project <the project you want me to answer questions about>. Show me the "Phone settings" block it prints (URL and token) so I can enter them in the ElvarOne app. Then run elvarone-bridge doctor and fix anything it flags. Add this line to your project instructions (CLAUDE.md or AGENTS.md): "At the start of each session, list ~/ElvarBridge/reports/*.md and answer any file with status: unread; write replies as -reply-.md in the same folder and set the report's status to read."

Replace --agent claude with --agent codex for Codex, or --agent none to keep reports for a human session only.

What the phone agent gets

Auto-replies

When BRIDGE_DESKTOP_AGENT is claude or codex (auto-detected), every report starts a read-only run of that agent in BRIDGE_AGENT_CWD (claude -p … --allowedTools Read,Grep,Glob,LS --max-turns 8 or codex exec --sandbox read-only …). The answer lands as reports/<stamp>-reply-<slug>.md, the report becomes status: answered, and a desktop notification fires. The worker never edits files; when a change is needed it says "needs a human coding session", and your next session picks the report up from the mailbox.

The desktop agent must be logged in for the user running the bridge: run claude (then /login) or codex login once in a terminal. elvarone-bridge doctor checks this.

Telling the phone

Set AGORADM_TOKEN (an AgoraDM bot token for this computer — pair one at agoradigest.com/bring-agent) and BRIDGE_NOTIFY_BOT (the phone agent's bot id) and install the extra: pip install 'elvarone-bridge[agoradm]'. The bridge then DMs the phone agent when a reply is ready; the DM wakes ElvarOne, so the phone reads the answer without polling.

Security

• The token is required on every request. init mints a 32-byte random one.
• Binds 0.0.0.0 (LAN + Tailscale). Never port-forward it to the internet. Install Tailscale on both devices to use the bridge away from home.
• Every remote call is approved on the phone. Pre-approve only read-only tools (screenshot, list_reports, read_file, report_to_desktop_agent).
• Commands that would stop the bridge's own services are refused.
• Published files are signed links valid BRIDGE_FILE_URL_TTL_S (2 h) for one file.

Configuration

~/ElvarBridge/config.env (mode 600), or the same keys in the environment:

BRIDGE_TOKEN=…             required
BRIDGE_PORT=8787
BRIDGE_BIND=0.0.0.0
BRIDGE_PUBLIC_URL=         override the URL handed to the phone
BRIDGE_FILE_URL_TTL_S=7200
BRIDGE_DESKTOP_AGENT=      claude | codex | none (auto)
BRIDGE_AGENT_CWD=          project the desktop agent reads (default ~/ElvarBridge)
BRIDGE_AGENT_MAX_TURNS=8
BRIDGE_AGENT_TIMEOUT_S=600
BRIDGE_CLAUDE_ARGS=        extra flags for claude -p (e.g. --max-budget-usd 0.50)
BRIDGE_NOTIFY_DESKTOP=1
AGORADM_TOKEN=             optional, see "Telling the phone"
BRIDGE_NOTIFY_BOT=

Upgrading from the original mac_bridge.py launchd setup: pip install -e . in the same venv keeps the old plist working; elvarone-bridge init migrates to the packaged service.