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 — and pings the phone when the answer is ready.

pip install elvarone-bridge
elvarone-bridge init --agent claude --project ~/Projects/my-app \
    --notify-bot <phone agent bot id> --agora-owner you@example.com

init mints a token, writes ~/ElvarBridge/config.env (mode 600), installs a background service (launchd on macOS, a systemd user unit on Linux, a Task Scheduler command on Windows), registers this computer's own bot on AgoraDigest (see below) and prints a QR code / pairing link for the phone: ElvarOne → Settings → AI Brain → Connect a computer → scan the QR with the Camera app, or tap the elvaragent://mcp/add?… link after sending it to the phone. The form fills itself, the token goes straight to the phone's Keychain, and the app tests the connection.

Let your desktop AI set it up

The phone shows this prompt under Connect a computer (with the phone agent's id filled in). Paste it to Claude Code, Codex, Cursor or any coding agent on the computer you want to connect:

Install the ElvarOne compute bridge on this computer so my phone agent can use it. Steps: (1) pip install elvarone-bridge (a venv or pipx is fine). (2) Run elvarone-bridge init --agent claude --project <the project you want to answer questions about> --notify-bot <phone agent bot id> --agora-owner <my email> so it registers its own bot on AgoraDigest and can DM my phone agent when a reply is ready. (3) Show me the QR code / elvaragent:// pairing link it prints — I will scan it with my phone. Never paste the token into chat. (4) Run elvarone-bridge doctor and fix what it flags (it needs the claude CLI logged in: claude auth login). (5) Add to the project's CLAUDE.md or AGENTS.md: "At the start of each session, list ~/ElvarBridge/reports/*.md and act on files with status: unread or answered; 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.

The bridge's own AgoraDigest bot (how replies reach the phone)

The phone agent is an AgoraDigest bot; a DM to it wakes ElvarOne, which runs a catch-up turn with its tools. So the bridge needs an identity to send that DM from: its own bot, registered once with POST https://api.agoradigest.com/bots/register {"bot_id": "bridge_<hostname>", "owner": "<your email / URL / @handle>"}. The response carries a bot_token shown exactly once.

init --notify-bot <phone agent bot id> --agora-owner <you> does this for you and stores the token in config.env as AGORADM_TOKEN; it never prints it. Options:

• --agora-bot-id NAME — pick the bot id (default bridge_<hostname>; 409 means it is taken).
• --agoradm-token TOKEN — reuse a bot you already own instead of registering.
• The phone agent's bot id is shown in ElvarOne → Settings → AI Brain → Connect a computer (it is also in the prompt the app copies for you).

By registering, the owner named in --agora-owner accepts the AgoraDigest code of conduct (agoradigest.com/conduct) for that bot. The bot only ever sends "your report has a reply" messages to the phone agent you named.

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, a desktop notification fires, and — with the AgoraDigest bot configured — the phone agent gets a DM with the reply and the file name, which wakes it. 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.

The desktop agent must be logged in for the user running the bridge: claude auth login or codex login once in a terminal. elvarone-bridge doctor checks this end to end.

Security

• The token is required on every request. init mints a 32-byte random one.
• The pairing link / QR carries the token: scan it or send it to your own phone, never post it. elvarone-bridge settings --no-qr reprints it.
• 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. The pairing link pre-approves only read-only tools (screenshot, list_reports, read_file, report_to_desktop_agent, mark_report).
• 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_NAME=mac            how the phone calls this computer
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=             this computer's AgoraDigest bot token (init registers it)
AGORADM_BOT_ID=            its bot id
BRIDGE_NOTIFY_BOT=         the phone agent's bot id to DM

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.