Bridge

Aptove Bridge is a stand-alone app to connect any AI Agents that support Agent Client Protocol (ACP) with the Aptove Mobile App to seamlessly manage the AI agents running in a server or computer.

Bridge is actively developed and we are still experimenting. Until the first stable version, expect breaking changes in the configuration files and how it works.

Transport Modes

Features

• 📱 QR Code Pairing: Secure one-time code pairing via QR scan
• 🔒 TLS + Certificate Pinning: Self-signed certificates with fingerprint validation
• ⚡ WebSocket Streaming: Real-time bidirectional communication
• 🌐 Multi-Transport: Local, Cloudflare, Tailscale — configure and switch between them
• 🔑 Stable Agent Identity: agent_id UUID persisted in common.toml for multi-transport dedup on mobile
• 🔔 Push Notifications: Wake the mobile app when the agent responds while backgrounded
• 🖥️ Terminal UI: Interactive TUI for setup and day-to-day management
• 🦀 Embeddable: Use as a library with StdioBridge for in-process deployment

Quick Start

# Build
cargo build --release

# Start the bridge — opens the interactive TUI (setup wizard on first run)
./target/release/bridge

# Use a custom config directory
./target/release/bridge -c ./my-config

On first launch the setup wizard runs automatically: it asks you to choose an agent command and a transport, then starts the bridge and shows a QR code for pairing.

Scan the QR code with the mobile app to connect.

Configuration — common.toml

All settings live in common.toml, created automatically by the setup wizard on first run.

Default location: .aptove-bridge/ directory inside the working directory where the bridge is launched.

Override with -c / --config-dir:

bridge -c ./my-config

Example common.toml

agent_id   = "550e8400-e29b-41d4-a716-446655440000"  # auto-generated UUID
auth_token = "base64urltoken"                         # auto-generated
agent_command = "copilot --acp"                       # set by setup wizard

keep_alive = true    # prevent system sleep while bridge is running
log_level  = "WARN"  # ERROR / WARN / INFO / DEBUG / TRACE

[transports.local]
enabled = true
port    = 8765
tls     = true

[transports.cloudflare]
enabled       = false
hostname      = "https://agent.example.com"
tunnel_id     = "abc123"
tunnel_secret = "..."
account_id    = "..."
client_id     = "client.access"
client_secret = "xxxxx"

[transports.tailscale-serve]
enabled = false

# Optional — enables push notifications (see Push Notifications section below)
[push_relay]
url           = "https://push.aptove.com"
token_url     = "https://token.aptove.com"
client_id     = "your-client-id"
client_secret = "your-client-secret"

No transports are pre-enabled. The setup wizard asks you to choose one on first run.

agent_id and auth_token are generated automatically on first run and stay stable across restarts.

Config Directory Files

All bridge state lives in the config directory. These files are created automatically on first run:

CLI

bridge [OPTIONS] [COMMAND]

bridge (default — TUI)

Running bridge with no arguments opens the interactive TUI. On first launch it runs the setup wizard:

Select an agent to run:
  [1] Copilot  (copilot --acp)
  [2] Gemini   (gemini --experimental-acp)
  [3] Goose    (goose acp)
  [4] Custom
Enter number [1]:

Select Custom to enter any ACP-compatible agent command, for example:

npx @agentclientprotocol/claude-agent-acp

After the wizard completes the bridge starts and displays a QR code for pairing.

bridge setup

Re-runs the Cloudflare Zero Trust setup wizard as a TUI flow. Use this to reconfigure your Cloudflare tunnel credentials without restarting the running bridge.

bridge setup

No flags are needed — the wizard guides you through everything interactively.

TUI slash commands

Type these in the input bar while the bridge is running:

Push Notifications

The bridge can alert the mobile app when the agent produces output while the app is backgrounded (WebSocket disconnected). The bridge never holds APNs/FCM credentials — it authenticates to a push relay service using a short-lived RS256 JWT and the relay handles APNs/FCM delivery.

How it works

Mobile app (backgrounded)          Bridge                      Push relay
                                                               (push.aptove.com)
        │                             │                              │
        │  [app backgrounds]          │                              │
        │                             │                              │
        │                             │  agent produces output       │
        │                             │◄─────────────────────       │
        │                             │                              │
        │                             │  no WebSocket receiver       │
        │                             │  (broadcast send fails)      │
        │                             │                              │
        │                             │  POST /push (JWT Bearer) ───►│
        │                             │                              │
        │◄────────────────────────── APNs/FCM notification          │
        │                             │                              │
        │  [app foregrounds]          │                              │
        │  reconnects WebSocket ─────►│                              │
        │◄── buffered messages ───────│                              │

Trigger logic

Push is triggered by passive failure detection — the bridge never polls for connectivity:

A 30-second per-client debounce prevents notification storms when the agent is verbose.

Setup

Configure push via the /push TUI command or add the [push_relay] section directly to common.toml:

[push_relay]
url           = "https://push.aptove.com"   # Push relay base URL
token_url     = "https://token.aptove.com"  # JWT token service URL
client_id     = "your-client-id"            # M2M client ID (JWT sub)
client_secret = "your-client-secret"        # M2M client secret

All four fields are required. If the section is absent or any field is empty, push is silently disabled. The push relay URL is included in the QR pairing payload so the mobile app knows where to register its device token.

Security

• Device tokens travel over the bridge's authenticated WebSocket (bearer authToken + TLS) — the same channel that carries the full LLM conversation.
• JWT credentials (client_id, client_secret) never leave the bridge process.
• The relay isolates registered devices per JWT sub (client_id) — one bridge cannot trigger pushes for another bridge's devices.
• Notification content is fixed ("Your agent has new activity") to prevent leaking agent response text.

Library usage

use aptove_bridge::push::PushRelayClient;

let push_client = PushRelayClient::new("https://push.aptove.com".into(), String::new())
    .with_jwt_credentials(
        "https://token.aptove.com".into(),
        "your-client-id".into(),
        "your-client-secret".into(),
    );

let bridge = StdioBridge::new("copilot --acp".into(), 8765)
    .with_push_relay(push_client);

Architecture

┌─────────────┐                    ┌───────────────────────┐        ┌──────────────┐
│  Client App │◄──────────────────►│  bridge binary        │◄──────►│  ACP Agent   │
│ (iOS/Android│  WebSocket (TLS)   │  (transport listener) │  stdio │  (your cmd)  │
└─────────────┘                    └───────────────────────┘        └──────────────┘

The agent process is spawned as a subprocess via stdio — StdioBridge handles the WebSocket server, TLS, auth, and pairing in-process alongside your application.

Troubleshooting

Debugging

# Change log verbosity via TUI
# Type /log-level and select DEBUG or TRACE

# Or set it permanently in common.toml
log_level = "DEBUG"

# Test agent command independently
echo '{"jsonrpc":"2.0","method":"initialize","id":1}' | copilot --acp

Testing with Other ACP-Compatible Agents

Please note that the project is extensively tested only with Copilot CLI. Open a bug report if you notice any issues with other ACP-Compatible Agents.

Run bridge and pick an agent from the setup wizard, or edit agent_command directly in common.toml.

Security

• Auth token: auto-generated 32-byte random value, stored in common.toml (0600). Transmitted to mobile during QR pairing and stored in the device Keychain.
• TLS: self-signed certificate generated on first run. Certificate fingerprint is included in the QR pairing payload and pinned by the mobile app to prevent MITM attacks.
• Pairing codes: 6-digit, single-use, expire after 60 seconds. Rate-limited to 5 attempts per code.
• common.toml: contains all secrets. Permissions are set to 0600 automatically. Keep it secure.
• Agent command: saved to agent_command in common.toml by the setup wizard. It can be changed at any time via the /agent TUI command. The bridge is an operator tool: whoever can invoke it already has local shell access, so the agent command is implicitly trusted to the same degree as any other command that user could run.

To rotate credentials (invalidates all paired devices):

rm .aptove-bridge/common.toml
bridge

Development

cargo build --release    # Build
cargo test               # Run tests

License

MIT — see LICENSE