ACP Bridge

A bridge between stdio-based Agent Client Protocol (ACP) agents and mobile applications.

Transport Modes

Multiple transports can run simultaneously — the bridge runs one listener per enabled transport.

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 — all at once
• 🔑 Stable Agent Identity: agent_id UUID persisted in common.toml for multi-transport dedup on mobile
• 🦀 Rust Performance: Low-latency, high-throughput implementation

Quick Start

# Build
cargo build --release

# Start with local transport (default — no config needed)
./target/release/bridge run \
  --agent-command "gemini --experimental-acp" \
  --qr

Scan the QR code with the Aptove mobile app to connect.

Configuration — common.toml

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

Default location (depends on how you run the bridge):

When using aptove run, this config is shared across all workspaces.

Override with --config-dir:

bridge --config-dir ./my-config start --agent-command "gemini --experimental-acp"

Example common.toml

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

[transports.tailscale-ip]
enabled = true
port    = 8765
tls     = true

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

Commands

start — Run the bridge

bridge run --agent-command "<your-agent-command>"

Transport selection, ports, TLS, and auth tokens are all read from common.toml.

show-qr — Show QR code for a second device

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 the bridge.

To show the QR at initial startup, pass --qr to bridge run instead:

bridge run --agent-command "aptove stdio" --qr

setup — Provision Cloudflare infrastructure

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.

status — Check configuration

bridge status

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

Architecture

┌─────────────┐                    ┌──────────────────────┐        ┌──────────────┐
│  Mobile App │◄──────────────────►│  Bridge (per-transport│◄──────►│  ACP Agent   │
│ (iOS/Android│  WebSocket (TLS)   │  local / CF / TS)    │  stdio │  (your cmd)  │
└─────────────┘                    └──────────────────────┘        └──────────────┘

Multiple transport listeners share the same agent process.

Troubleshooting

Connection Issues

Debugging

# Enable verbose logging
bridge run --agent-command "gemini --experimental-acp" --verbose

# Check which transports are configured
bridge status

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

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.

To rotate credentials (invalidates all paired devices):

# Using aptove run (embedded bridge):
rm ~/Library/Application\ Support/Aptove/common.toml   # macOS
rm ~/.config/Aptove/common.toml                        # Linux
aptove run --qr

# Using standalone bridge binary:
rm ~/Library/Application\ Support/com.aptove.bridge/common.toml   # macOS
rm ~/.config/bridge/common.toml                                    # Linux
bridge run --agent-command "aptove stdio" --qr

Development

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

License

Apache 2.0 — see LICENSE