🎯 What is CodeTether?

CodeTether is a production-ready Agent-to-Agent (A2A) platform that is officially A2A Protocol v0.3 compliant. Build AI agent systems that actually work in the real world—connect any LLM to any tool, orchestrate complex multi-agent workflows, and deploy with confidence. Our implementation uses the official a2a-sdk from Google, ensuring full interoperability with any A2A-compliant client or agent.

┌─────────────────────────────────────────────────────────────────┐
│                         CodeTether                               │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │   Claude    │  │   GPT-4     │  │   Gemini    │   LLMs       │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘              │
│         │                │                │                      │
│         └────────────────┼────────────────┘                      │
│                          ▼                                       │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                 A2A Protocol v0.3 Layer                   │  │
│  │  ┌─────────────────┐  ┌─────────────┐  ┌───────────────┐  │  │
│  │  │ /.well-known/   │  │ /a2a/jsonrpc│  │  /a2a/rest/*  │  │  │
│  │  │ agent-card.json │  │   (RPC)     │  │  (REST API)   │  │  │
│  │  └─────────────────┘  └─────────────┘  └───────────────┘  │  │
│  └───────────────────────────────────────────────────────────┘  │
│                          │                                       │
│              ┌───────────────────────┐                           │
│              │    Message Broker     │   Standard Communication  │
│              │    (Redis/Memory)     │                           │
│              └───────────┬───────────┘                           │
│                          │                                       │
│         ┌────────────────┼────────────────┐                      │
│         ▼                ▼                ▼                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │  OpenCode   │  │ MCP Tools   │  │  Your APIs  │   Actions    │
│  │  (Coding)   │  │  (100+)     │  │             │              │
│  └─────────────┘  └─────────────┘  └─────────────┘              │
└─────────────────────────────────────────────────────────────────┘

✨ Why CodeTether?

🔗 A2A Protocol Compliance

CodeTether implements the A2A Protocol v0.3 specification using the official a2a-sdk from Google, ensuring full interoperability with any A2A-compliant client or agent.

Standard Endpoints

Interoperability

• Any A2A Client: Connect using standard A2A protocol clients from any language or platform
• Agent Discovery: Automatic capability discovery via well-known endpoint
• Cross-Platform: Seamlessly communicate with other A2A-compliant agents
• SDK Support: Built on Google's official a2a-sdk for guaranteed compatibility

# Discover agent capabilities
curl https://api.codetether.run/.well-known/agent-card.json

# Send A2A message via JSON-RPC
curl -X POST https://api.codetether.run/a2a/jsonrpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "message/send", "params": {...}, "id": 1}'

🚀 Quick Start

Install from PyPI

pip install codetether

Or Install from Source

git clone https://github.com/rileyseaburg/codetether.git
cd A2A-Server-MCP && pip install -e .

# For production (PostgreSQL persistence):
export DATABASE_URL=postgresql://user:password@host:5432/a2a_server

# Start the server (defaults to `run`)
codetether --port 8000

Docker

docker run -p 8000:8000 registry.quantum-forge.net/library/a2a-server-mcp:latest

Kubernetes (Production)

helm install codetether oci://registry.quantum-forge.net/library/a2a-server \
  --namespace codetether --create-namespace

Distributed Workers (Scale Anywhere)

Run agents on any machine with the CodeTether Worker:

git clone https://github.com/rileyseaburg/codetether.git
cd codetether && sudo ./agent_worker/install.sh

Learn more in the Distributed Workers Guide.

🚀 Production Worker Setup

To connect a local worker to the production CodeTether service:

1. Install the worker:

   sudo ./agent_worker/install.sh
   

2. Configure for production: Edit /etc/a2a-worker/env:

   A2A_SERVER_URL=https://api.codetether.run
   

3. Authenticate models: Ensure your models are authenticated in ~/.local/share/opencode/auth.json. The worker will only register models it has credentials for.

4. Restart the service:

   sudo systemctl restart a2a-agent-worker
   

   # Or use the makefile shortcut:
   make local-worker-restart
   

How it works:

• Worker discovers local OpenCode sessions from ~/.local/share/opencode/storage/
• Worker syncs sessions to PostgreSQL via /v1/opencode/codebases/{id}/sessions/sync
• Worker syncs session messages via /v1/opencode/codebases/{id}/sessions/{id}/messages/sync
• Monitor UI and production API read sessions from PostgreSQL
• Use make local-worker-restart to restart the worker service

That's it. Your agent platform is running at http://localhost:8000

🎬 See It In Action

Talk to Your Agents

curl -X POST http://localhost:8000/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "message/send",
    "params": {"message": {"parts": [{"type": "text", "content": "Calculate 25 * 4"}]}}
  }'

Deploy AI Coding Agents

# Register a codebase
curl -X POST http://localhost:8000/v1/opencode/codebases \
  -H "Content-Type: application/json" \
  -d '{"name": "my-app", "path": "/home/user/my-app"}'

# Trigger an agent task
curl -X POST http://localhost:8000/v1/opencode/codebases/{id}/trigger \
  -d '{"prompt": "Add unit tests for the auth module", "agent": "build"}'

Stream Real-Time Output

curl http://localhost:8000/v1/opencode/codebases/{id}/events

📧 Email Reply to Continue Tasks

When a task completes, workers send you an email. Just reply to continue the conversation—no dashboard, no CLI, just email.

From: noreply@codetether.run
To: you@example.com
Subject: [A2A] Task completed: Add unit tests
Reply-To: task+sess_abc123@inbound.codetether.run

✓ COMPLETED

Your task "Add unit tests" finished successfully.
Reply to this email to continue the conversation.

---
You: "Great, now add integration tests too"
→ Agent picks up and continues working

How it works:

1. Worker completes task → sends email with special reply-to address
2. You reply to the email with follow-up instructions
3. SendGrid forwards your reply to CodeTether
4. Server creates a continuation task with your message
5. Worker resumes the same session and keeps working

Zero friction. Check your email, reply, done.

🏗️ Architecture

CodeTether is built on five core pillars:

Platform Components

codetether/
├── 🌐 API Server          # A2A protocol + REST APIs
├── 🖥️ Monitor UI          # Real-time agent dashboard
├── 👷 [Agent Workers](https://docs.codetether.run/features/distributed-workers/)       # Distributed task execution
├── 🤖 OpenCode Fork       # Maintained AI coding agent
├── 📚 Documentation       # MkDocs Material site
└── 🏠 Marketing Site      # Next.js landing page

Data Flow:

OpenCode Storage (local) → Worker → PostgreSQL → Bridge/API → Monitor UI

Workers sync sessions from local OpenCode storage to PostgreSQL. The OpenCode bridge and Monitor UI read from PostgreSQL, providing a consistent view across server replicas and restarts.

📦 What's Included

Core Platform

• ✅ Full A2A Protocol implementation
• ✅ MCP tool integration
• ✅ Redis message broker
• ✅ PostgreSQL durable storage (sessions, codebases, tasks)
• ✅ SSE real-time streaming
• ✅ Worker sync to PostgreSQL from OpenCode storage

Enterprise Features

• ✅ Keycloak SSO integration
• ✅ Role-based access control
• ✅ Audit logging
• ✅ Network policies

DevOps Ready

• ✅ Unified Helm chart (server + marketing + docs)
• ✅ Blue-green deployments
• ✅ Horizontal pod autoscaling
• ✅ Health checks & metrics

Developer Experience

• ✅ Real-time Monitor UI
• ✅ Swift iOS/macOS app
• ✅ CLI tools
• ✅ Comprehensive API docs
• ✅ Voice agent with LiveKit
• ✅ Marketing coordinator for task orchestration
• ✅ Worker SSE push notifications
• ✅ 27 marketing MCP tools (creative, campaigns, analytics)
• ✅ Email reply continuation - reply to task emails to keep working

🛠️ Deployment Options

Production Deployment

# Build and deploy everything
make k8s-prod

# This builds & deploys:
# ✅ API Server (api.codetether.run)
# ✅ Marketing Site (codetether.run)
# ✅ Documentation (docs.codetether.run)
# ✅ Redis cluster

🔧 Environment Variables

Setting DATABASE_URL:

# Local development (with PostgreSQL):
export DATABASE_URL=postgresql://a2a:a2a_password@localhost:5432/a2a_server

# Production:
export DATABASE_URL=postgresql://user:password@prod-db:5432/a2a_server

🐛 Troubleshooting

Sessions Not Appearing in UI?

If you don't see sessions in the production API for a codebase (like "spotlessbinco"):

1. Check worker is running:

   sudo systemctl status a2a-agent-worker
   

2. Check worker logs for sync errors:

   sudo journalctl -fu a2a-agent-worker | grep -i "session\|sync"
   

3. Verify sessions are in PostgreSQL:

   # Via API:
   curl http://localhost:8000/v1/opencode/database/sessions
   
   # Or via psql:
   psql -d a2a_server -c "SELECT id, codebase_id, title FROM sessions ORDER BY updated_at DESC LIMIT 10;"
   

4. Restart worker to force re-sync:

   make local-worker-restart
   

How it works:

• Workers read local OpenCode storage from ~/.local/share/opencode/
• Workers POST sessions to /v1/opencode/codebases/{id}/sessions/sync
• Server persists to PostgreSQL via db_upsert_session()
• Monitor UI reads from PostgreSQL via db_list_sessions()
• No SQLite involved! All data goes through PostgreSQL

Worker Not Connecting?

1. Check DATABASE_URL in worker env:

   cat /etc/a2a-worker/env
   # Should contain: DATABASE_URL=postgresql://...
   

2. Check network connectivity:

   curl -v https://api.codetether.run/v1/health
   

3. Verify worker is registered:

   curl http://localhost:8000/v1/opencode/database/workers
   

For more troubleshooting, see docs.codetether.run/troubleshooting

Production Deployment

🔌 Integrations

📚 Documentation

For detailed technical documentation, see DEVELOPMENT.md.

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

# Setup development environment
git clone https://github.com/rileyseaburg/codetether.git
cd A2A-Server-MCP
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt -r requirements-test.txt

# Run tests
pytest tests/

# Start development server (Python + Next.js)
make dev

📄 License

Apache License 2.0 - See LICENSE for details.