AgentBridge

Remote Control Platform for AI Coding Agents

Control Claude Code, Codex, Gemini, and OpenCode from anywhere.
Monitor progress, handle permissions, manage sessions — from mobile or desktop.

Why AgentBridge?

AI coding agents like Claude Code and Codex are powerful — but they run in a terminal on your machine. When you step away, you lose visibility. Permission requests go unanswered. Sessions hang.

AgentBridge fixes this. It wraps your AI agents in a daemon process and syncs everything to your phone in real-time with end-to-end encryption. Your code never leaves your machine unencrypted.

Key capabilities:

Multi-Agent — One unified interface for Claude Code, OpenAI Codex, Google Gemini CLI, and OpenCode
Remote Control — Monitor progress, approve/deny permissions, send prompts from your phone
Background Daemon — Agents keep running even when your terminal closes or SSH disconnects
End-to-End Encryption — X25519 key exchange + AES-256-GCM; your code stays private
Session Persistence — Resume sessions across devices and restarts
Real-Time Sync — WebSocket-based with sub-second latency

Architecture

flowchart LR
    subgraph Phone["📱 Mobile App"]
        App["React Native<br/>(iOS / Android / Web / Desktop)"]
    end

    subgraph Cloud["☁️ Server"]
        Server["Relay Server<br/>(Fastify + Prisma)"]
    end

    subgraph Local["💻 Your Machine"]
        Daemon["Daemon<br/>(owns agent processes)"]
        CLI["CLI<br/>(terminal UI)"]
        Daemon --- CLI
        Daemon --> Claude["Claude Code"]
        Daemon --> Codex["Codex"]
        Daemon --> Gemini["Gemini CLI"]
        Daemon --> OpenCode["OpenCode"]
    end

    App <-->|"E2E Encrypted<br/>WebSocket"| Server
    Server <-->|"WebSocket"| Daemon

The daemon owns all agent processes — if your CLI crashes or you close the terminal, the agent keeps running. Reconnect anytime from the CLI or the mobile app.

Quick Start

Install CLI

npm install -g @saaskit-dev/free

Or use the install script (builds from source + installs daemon service):

curl -fsSL https://raw.githubusercontent.com/saaskit-dev/agentbridge/main/install.sh | bash

Start a Session

free                    # Claude Code (default)
free gemini             # Gemini CLI
free codex              # OpenAI Codex
free opencode           # OpenCode

A QR code appears on launch — scan it with the mobile app to connect.

Authenticate

free auth               # Account authentication
free connect gemini     # Link Google account
free connect claude     # Link Anthropic account
free connect codex      # Link OpenAI account
free connect status     # View all connection status

CLI Options

free --claude-env KEY=VALUE       # Pass env vars to Claude Code
free --no-sandbox                 # Disable sandbox

Unknown flags are passed through to the underlying agent CLI. For example, free -m sonnet -p auto forwards -m sonnet -p auto directly to Claude Code.

Daemon Management

free daemon start       # Start background daemon
free daemon stop        # Stop daemon
free daemon status      # Check status
free doctor             # System diagnostics

Project Structure

This is a pnpm monorepo with four packages:

agentbridge/
├── packages/
│   └── core/                 # @saaskit-dev/agentbridge — shared SDK
│       ├── types/            #   Type definitions (session, message, agent, ...)
│       ├── interfaces/       #   Abstract contracts (ICrypto, IStorage, IAgentBackend, ...)
│       ├── implementations/  #   Platform implementations (ACP backends, transports)
│       ├── encryption/       #   E2E encryption (SecretBox, AES-256-GCM, wire encoding)
│       ├── telemetry/        #   Structured logging with trace correlation
│       └── utils/            #   Encoding, async primitives, tmux, etc.
│
└── apps/free/
    ├── cli/                  # @saaskit-dev/free — CLI & Daemon
    │   ├── daemon/           #   Background process (SessionManager, IPC, AgentBackends)
    │   ├── backends/         #   Claude/Gemini/Codex/OpenCode backend implementations
    │   ├── client/           #   CLI renderer & input handler
    │   └── api/              #   Server communication & encryption
    │
    ├── server/               # Relay server (Fastify + Prisma)
    │   ├── api/              #   REST routes, WebSocket handlers, RPC
    │   ├── auth/             #   Challenge-response authentication
    │   └── storage/          #   Database abstraction (PostgreSQL / PGlite)
    │
    └── app/                  # Mobile/Desktop client (React Native / Expo / Tauri)
        ├── app/(app)/        #   Page components (Expo Router)
        ├── components/       #   UI components (messages, tools, markdown, ...)
        ├── sync/             #   State management, encryption, WebSocket
        └── realtime/         #   Voice assistant & WebRTC

Desktop App

The desktop app reuses the Expo web frontend and packages it with Tauri:

cd apps/free/app
pnpm tauri:dev
pnpm tauri:build:production

Self-Hosted Deployment

The relay server can be fully self-hosted. It ships with an embedded database (PGlite) — no external PostgreSQL needed:

./run build server                                    # Build Docker image
docker run -d -p 3000:3000 \
  -e FREE_MASTER_SECRET=your-secret-key \
  -v free-data:/app/data \
  kilingzhang/free-server:latest

Then point your CLI:

FREE_SERVER_URL=https://your-server.example.com free

See apps/free/server/README.md for the complete deployment guide (Docker Compose, external PostgreSQL, Nginx reverse proxy, logs, etc.).

Core SDK

The @saaskit-dev/agentbridge package provides platform-agnostic building blocks:

npm install @saaskit-dev/agentbridge

Import Path	Use Case
`@saaskit-dev/agentbridge`	Full SDK (Node.js)
`@saaskit-dev/agentbridge/common`	React Native / Browser (no `node:*` imports)
`@saaskit-dev/agentbridge/types`	Pure type definitions
`@saaskit-dev/agentbridge/encryption`	Encryption primitives
`@saaskit-dev/agentbridge/telemetry`	Structured logging

Key interfaces:

IAgentBackend — Unified agent control (startSession, sendPrompt, cancel, onMessage)
ITransportHandler — Agent-specific ACP protocol behaviors
ICrypto — TweetNaCl + AES-256-GCM encryption
IStorage — Key-value storage abstraction

All interfaces use a factory pattern for dependency injection:

import { registerCryptoFactory, createCrypto } from '@saaskit-dev/agentbridge';

registerCryptoFactory(() => new NodeCrypto());
const crypto = createCrypto();

See packages/core/README.md for full API documentation.

Security

Layer	Mechanism
Key Exchange	X25519 (Curve25519 Diffie-Hellman)
Symmetric Encryption	AES-256-GCM
Authentication	Ed25519 signatures + challenge-response
Transport	TLS + E2E encryption (double encrypted)
Storage	Private keys stored with `chmod 0600`

All data is encrypted on-device before leaving your machine
The relay server never sees plaintext — it forwards encrypted blobs
Each session uses unique encryption keys
Challenge-response auth prevents replay attacks

Development

Prerequisites

Node.js >= 20
pnpm >= 8

Full Dev Environment

All workflows are managed through the ./run script:

git clone https://github.com/saaskit-dev/agentbridge.git
cd agentbridge
pnpm install

# One-command setup: builds core + CLI, starts server + daemon + desktop
./run dev

# Or start individual services:
./run dev server            # Server + daemon only
./run dev web               # Web app only
./run dev quick             # Skip build, fast restart
./run desktop               # Desktop app (Tauri dev)

Testing

./run test unit             # Unit tests (Vitest)
./run test                  # E2E tests (Playwright)
./run test lifecycle        # Message lifecycle integration tests

Mobile Development

./run ios                   # iOS debug (connects to Metro)
./run android               # Android debug (connects to Metro)
./run ios release           # iOS release (production server, embedded bundle)
./run android release       # Android release (production server, embedded bundle)

Desktop Development

./run desktop               # Desktop debug (Tauri + Expo Web)
./run desktop build         # Build desktop production app
./run desktop build-dev     # Build desktop development app

Build & Publish

./run build core            # Build core SDK
./run build cli             # Build CLI + npm link
./run build server          # Build server Docker image
./run npm publish           # Publish to npmjs.org

Environment Variables

Variable	Description	Default
`FREE_SERVER_URL`	Backend server URL	`https://free-server.saaskit.app`
`FREE_HOME_DIR`	Data directory	`~/.free`
`FREE_DISABLE_CAFFEINATE`	Disable macOS sleep prevention	`false`

System Requirements

Agent	Requirement
Claude Code	`claude` CLI installed and authenticated
Gemini	`gemini` CLI installed (`npm i -g @google/gemini-cli`)
Codex	`codex` CLI installed
OpenCode	`opencode` CLI installed

Contributing

Contributions are welcome! Here's how to get started:

Fork the repository
Create a feature branch: git checkout -b feature/my-feature
Make your changes
Run tests: ./run test unit
Verify no circular dependencies: npx madge --circular --extensions ts,tsx packages/ apps/
Commit: git commit -m 'feat: add my feature'
Push and open a Pull Request

Code Conventions

No circular dependencies — verified with madge
Strict TypeScript — no untyped code
Logger over console.log — all debug logging via @agentbridge/core/telemetry
Named exports preferred
Tests colocated with source files (.test.ts)

Uninstall

curl -fsSL https://raw.githubusercontent.com/saaskit-dev/agentbridge/main/uninstall.sh | bash

Roadmap

Web dashboard for session management
Multiple concurrent sessions per machine
Custom MCP server configuration via mobile UI
Team collaboration features
Apple Watch companion app

License

MIT

Acknowledgments

Anthropic — Claude Code
OpenAI — Codex
Google — Gemini CLI
OpenCode — OpenCode

Name		Name	Last commit message	Last commit date
Latest commit History 351 Commits
.githooks		.githooks
.github		.github
apps/free		apps/free
docs		docs
packages/core		packages/core
patches		patches
scripts		scripts
tests		tests
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
README.zh-CN.md		README.zh-CN.md
SECURITY.md		SECURITY.md
eslint.config.mjs		eslint.config.mjs
favicon.icns		favicon.icns
install.sh		install.sh
package.json		package.json
playwright.config.ts		playwright.config.ts
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
run		run
tsconfig.json		tsconfig.json
turbo.json		turbo.json
uninstall.sh		uninstall.sh
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

AgentBridge

Why AgentBridge?

Architecture

Quick Start

Install CLI

Start a Session

Authenticate

CLI Options

Daemon Management

Project Structure

Desktop App

Self-Hosted Deployment

Core SDK

Security

Development

Prerequisites

Full Dev Environment

Testing

Mobile Development

Desktop Development

Build & Publish

Environment Variables

System Requirements

Contributing

Code Conventions

Uninstall

Roadmap

License

Acknowledgments

About

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 6

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages