codetether 1.4.2

CodeTether: A2A Protocol v0.3 compliant agent orchestration platform with MCP + OpenCode integration

🔗 CodeTether

Turn AI Agents into Production Systems

The open-source platform for building, deploying, and orchestrating AI agent systems at scale.

🎉 v1.4.0 Production Release - Now with Ralph autonomous development and Zapier integration at api.codetether.run

🚀 Quick Start • 📖 Documentation • 💬 Discord • 🐦 Twitter

---

🎯 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?

🤖 Ralph: Autonomous Development Ralph implements entire PRDs with zero human intervention. Define user stories, Ralph writes the code, runs tests, and commits—autonomously iterating until all acceptance criteria pass. 🛠️ MCP Tool Integration Connect to 100+ tools via Model Context Protocol. File systems, databases, APIs, and more. 💻 AI Coding at Scale Deploy AI coding agents across your infrastructure using our maintained OpenCode fork. Automated code generation, refactoring, and testing. 🔄 RLM (Recursive Language Models) Process arbitrarily long contexts through recursive LLM calls in a Python REPL. Analyze entire monorepos without context limits using programmatic sub-LLM queries. 📧 Email Reply to Continue Tasks Workers send email notifications when tasks complete. Reply directly to the email to continue the conversation—the agent picks up right where it left off. No dashboard needed. ⚡ Zapier Integration Connect CodeTether to 5,000+ apps with our native Zapier integration. OAuth2 authentication, triggers, actions, and searches—no code required.

🎤 Voice Agent Real-time voice interactions with AI agents through LiveKit integration. Multi-model support and session playback. 📡 Real-Time Streaming Watch agents think in real-time. SSE streaming for instant feedback and human intervention. 🚀 Production Ready Connect workers to https://api.codetether.run for live task execution. Helm charts and horizontal scaling included. 🔐 Enterprise Ready Keycloak SSO, RBAC, audit logs, and network policies. Security that enterprises demand. ☸️ Deploy Anywhere Helm charts, horizontal scaling, blue-green deployments. Production from day one on any cloud or on-premise infrastructure.

🔗 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

Endpoint	Description
/.well-known/agent-card.json	Agent capability discovery and metadata
/a2a/jsonrpc	JSON-RPC 2.0 endpoint for A2A protocol messages
/a2a/rest/*	RESTful API endpoints for task and agent management

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: [e-mail]
To: [e-mail]
Subject: [A2A] Task completed: Add unit tests
Reply-To: [e-mail]

✓ 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:

Component	Purpose	Technology
A2A Protocol Server	Agent communication & orchestration	Python, FastAPI, Redis
Distributed Workers	Scale agent execution across machines	Python, Redis, Systemd/K8s
MCP Integration	Tool access & resource management	Model Context Protocol
PostgreSQL Database	Durable storage for sessions, codebases, tasks	PostgreSQL, asyncpg
OpenCode Bridge	AI-powered code generation	Local OpenCode fork, Claude/GPT-4
RLM Engine	Recursive context processing	Python REPL, sub-LLM calls

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

Environment	Command	Description
Local	python run_server.py or make run	Development mode
Production	DATABASE_URL=... make k8s-prod	Full PostgreSQL persistence
Docker	docker-compose up	Single container
Kubernetes	make k8s-prod	Full production stack

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

Variable	Description	Default	Required
DATABASE_URL	PostgreSQL connection string	postgresql://user:pass@host:5432/db	Yes (production)
A2A_REDIS_URL	Redis URL for message broker	redis://localhost:6379	No
A2A_AUTH_TOKENS	Comma-separated auth tokens (format: name:token,name2:token2)	""	No
OPENCODE_HOST	Host where OpenCode API is running (container→host)	localhost	No
OPENCODE_PORT	Default OpenCode server port	9777	No
A2A_SERVER_URL	Production server URL (for workers)	http://localhost:8000	No

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

LLMs	Tools	Infrastructure
Claude (Anthropic) GPT-4 (OpenAI) Gemini (Google) DeepSeek Grok (xAI)	File systems Databases Git repositories REST APIs Custom MCP servers	Kubernetes Docker Redis Keycloak Any cloud

📚 Documentation

Resource	Link
📖 Full Documentation	docs.codetether.run
🚀 Quick Start Guide	Getting Started
🔧 API Reference	API Docs
🤖 Ralph Guide	Ralph Autonomous Development
👷 Agent Worker Guide	Agent Worker
🔄 RLM Guide	RLM (Recursive Language Models)
⚡ Zapier Integration	Zapier
🎤 Voice Agent	Voice Agent
📊 Marketing Tools	Marketing Tools
🤖 Marketing Coordinator	Marketing Coordinator
🔔 Worker SSE	Worker SSE
☸️ Kubernetes Deployment	Helm Charts
🔐 Authentication	Keycloak Setup

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.

---

Built with ❤️ by the CodeTether Team

Website • Documentation • GitHub