HotPlex Worker Gateway is a high-performance, unified access layer for managing AI Coding Agent sessions. It abstracts protocol differences across agents and provides a standardized, stateful WebSocket interface.
- Unified Protocol — AEP v1 (Agent Exchange Protocol) over WebSockets
- 5 Worker Adapters — Claude Code, OpenCode CLI, OpenCode Server, ACPX, Pi-mono
- Session Lifecycle — Create / Resume / Terminate / GC with SQLite persistence and UUIDv5 session IDs
- Process Isolation — PGID isolation with layered SIGTERM → SIGKILL termination
- Security — ES256 JWT, SSRF protection, command whitelist, env isolation, AI tool policy
- Admin API — Real-time stats, health checks, session CRUD, dynamic config hot-reload
- Client SDKs — TypeScript, Python, Java, and Go SDKs with working examples
- Web Chat UI — Next.js chat interface powered by Vercel AI SDK transport adapter
- Cloud Native — Prometheus metrics, OpenTelemetry tracing, PGO-optimized builds
graph TD
Client[Client: Web / IDE / CLI] -- "WebSocket (AEP v1)" --> Gateway
subgraph HotPlex Gateway
Gateway[WS Gateway Layer]
Session[Session Manager]
Pool[Worker Pool]
end
Pool -- "stdio" --> Claude[Claude Code]
Pool -- "stdio" --> OpenCode[OpenCode CLI]
Pool -- "HTTP" --> OCS[OpenCode Server]
Pool -- "stdio" --> ACPX[ACPX]
Pool -- "stdio" --> Pi[Pi-mono]
See Architecture Design for details.
- Go 1.26+
- SQLite3
git clone https://github.com/hrygo/hotplex-worker.git
cd hotplex-worker
make build
# Start with default config
./bin/gateway --config configs/config.yaml
# Development mode (relaxed security)
./bin/gateway --devSee configs/README.md for full configuration reference, including hot-reload, environment variables, and multi-environment setups.
| Language | Directory | Protocol |
|---|---|---|
| TypeScript | examples/typescript-client | WebSocket (AEP v1) |
| Python | examples/python-client | WebSocket (AEP v1) |
| Java | examples/java-client | WebSocket (AEP v1) |
| Go | client | WebSocket (AEP v1) |
A Next.js web chat interface is available at webchat/, using the @hotplex/ai-sdk-transport adapter for Vercel AI SDK integration.
| Document | Description |
|---|---|
| Architecture Design | System design and constraints |
| AEP v1 Protocol | Wire format, events, versioning |
| AEP v1 Appendix | Sequence diagrams, state machines |
| WebSocket Full-Duplex Flow | Connection lifecycle and race prevention |
| User Manual | API usage, lifecycle, examples |
| Security | JWT, input validation, SSRF, tool policy |
| Testing Strategy | Unit / integration / e2e testing |
See CONTRIBUTING.md for development workflow, PR guidelines, and testing standards.