A bridge library and application between Agent Client Protocol (ACP) agents and clients.

aptove-bridge can be used in two ways:

• Standalone binary — run bridge as a separate process that spawns your ACP agent over stdio and exposes it over WebSocket to mobile or desktop clients.
• Embedded library — add aptove-bridge as a Rust dependency and run the bridge server in-process alongside your agent, with no subprocess or stdio pipe required.

One transport is active at a time. When multiple are enabled in common.toml, the bridge prompts you to select one at startup.

• 📱 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
• 🦀 Embeddable: Use as a library with StdioBridge for in-process deployment

Add to your Cargo.toml:

[dependencies]
aptove-bridge = "0.2"

use aptove_bridge::{
    bridge::StdioBridge,
    common_config::CommonConfig,
    tls::TlsConfig,
};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Load (or initialise) shared config — generates agent_id and auth_token on first run
    let mut config = CommonConfig::load()?;
    config.ensure_agent_id();
    config.ensure_auth_token();
    config.save()?;

    // Generate (or load) a self-signed TLS cert
    let tls = TlsConfig::load_or_generate(&CommonConfig::config_dir(), &[])?;

    StdioBridge::new("copilot --acp".to_string(), 8765)
        .with_auth_token(Some(config.auth_token.clone()))
        .with_tls(tls)
        .start()
        .await
}

# Build
cargo build --release

# Start the bridge — interactive agent selection menu
./target/release/bridge

# Or specify the agent directly
./target/release/bridge run --agent-command "copilot --acp"

Running bridge with no subcommand defaults to run. When --agent-command is omitted, an interactive menu lets you pick from known agents (Copilot, Gemini, Goose) or enter a custom command.

Scan the QR code with the mobile app to connect.

All transport settings live in common.toml. The file is created automatically with local transport enabled on first run.

Default location:

Override with -c / --config-dir:

bridge -c ./my-config run --agent-command "copilot --acp"

agent_id   = "550e8400-e29b-41d4-a716-446655440000"  # auto-generated UUID
auth_token = "base64urltoken"                         # auto-generated

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

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

[transports.tailscale-serve]
enabled = true

# 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"

Enable only the transports you need. agent_id and auth_token are generated automatically on first run and stay stable across restarts.

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

run is the default subcommand — running bridge with no arguments is equivalent to bridge run.

# Interactive agent selection
bridge

# Or specify the agent directly
bridge run --agent-command "copilot --acp"

When --agent-command is omitted, the bridge presents an interactive menu:

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

The QR code for pairing is always displayed at startup.

Transport selection, port, TLS, and auth token are all read from common.toml.

bridge show-qr

Displays the connection QR code for the currently active transport. The bridge must already be running. Use this to pair an additional device without restarting.

bridge setup \
  --api-token  "your-api-token" \
  --account-id "your-account-id" \
  --domain     "example.com" \
  --subdomain  "agent"

Creates the Cloudflare tunnel, DNS record, Access Application, and Service Token. Saves credentials to common.toml under [transports.cloudflare]. Only needed once.

bridge status

Prints the active common.toml path, agent_id, enabled transports, and Tailscale availability.

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.

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 ───────│                              │

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.

On bridge run, after transport selection, the bridge prompts for push credentials if not yet configured:

Enable push notifications? [y/N]: y
  Token service URL [https://token.aptove.com]:
  Push service URL [https://push.aptove.com]:
  Client ID: your-client-id
  Client secret: xxxxxxxxxxxxxxxx

Saved to the [push_relay] section of common.toml. To skip prompts, pass credentials as flags:

bridge run --push-client-id your-client-id --push-client-secret xxxxxxxx

URL prompts still appear (with defaults) even when flags are provided.

[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. Push relay URL is included in the QR pairing payload so the mobile app knows where to register its device token.

• 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.

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);

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

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

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

# Enable verbose logging
bridge run --verbose

# Check which transports are configured
bridge status

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

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.

The easiest way to test any supported agent is to run bridge and pick it from the interactive menu. Alternatively, pass the command directly:

bridge run -a "gemini --experimental-acp" --verbose
bridge run -a "goose acp" --verbose

• 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: the --agent-command value (or interactive menu selection) is validated at startup — the binary must exist and be executable before the server accepts connections. The command is never persisted to common.toml; it must be supplied each time the bridge is started. 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):

# macOS
rm ~/Library/Application\ Support/com.aptove.bridge/common.toml
# Linux
rm ~/.config/bridge/common.toml

bridge

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

Apache 2.0 — see LICENSE