HotPlex Gateway

The Unified Bridge for AI Coding Agents

A high-performance Go gateway providing a single WebSocket interface
to access any AI Coding Agent across Web, Slack, and Feishu.

简体中文 | English

---

✨ Core Capabilities

• 🌐 Universal Agent Gateway — Abstract any AI Coding Agent protocol into a unified AEP v1 (Agent Exchange Protocol) WebSocket interface for consistent streaming and interaction.
• 📱 Cross-Platform Delivery — "Write Once, Deploy Anywhere". Bridge agents to Web, Slack (Socket Mode), and Feishu (WebSocket) with zero code changes.
• 🛠️ Multi-Modal Interaction — Native Speech-to-Text (SenseVoice-Small) support for a seamless voice-to-code development workflow.
• 🤖 Deep Personality Injection — Dynamic B/C dual-channel injection: B-channel (SOUL/AGENTS/SKILLS) for directives and C-channel (USER/MEMORY) for context.
• 🧠 Autonomous Meta-Cognition — Built-in 5-state machine with META-COGNITION core, intelligent LLM retry, and 3-layer self-healing for unmatched session stability.
• 🌐 Embedded Web Chat — A single binary serves both the API/WebSocket gateway and a premium Next.js-based web chat interface out of the box.
• 🛡️ Enterprise-Grade Security — JWT ES256 authentication, SSRF protection, and PGID-isolated process management with orphan cleanup.
• 📊 End-to-End Observability — Native Prometheus metrics, OpenTelemetry tracing, and structured JSON logging for full auditability.
• 🛠️ Self-contained CLI — gateway, service, dev, onboard, doctor, security, status in a single binary
• 🌍 Multi-language SDKs — Go, TypeScript, Python, Java clients ready to use

⚡ Quick Start

AI Agents: Read https://github.com/hrygo/hotplex/blob/main/INSTALL.md and complete the HotPlex installation and configuration

Install

macOS / Linux (one-click binary):

curl -fsSL https://raw.githubusercontent.com/hrygo/hotplex/main/scripts/install.sh | bash -s -- --latest

Windows (PowerShell 5.1+):

Invoke-WebRequest -Uri https://raw.githubusercontent.com/hrygo/hotplex/main/scripts/install.ps1 -OutFile install.ps1
.\install.ps1 -Latest

From source (requires Go 1.26+, pnpm, Node.js 22+):

git clone https://github.com/hrygo/hotplex.git
cd hotplex
make quickstart

Tip (Claude Code): After cloning, use /setup-env for interactive .env configuration (Slack/Feishu tokens, access policies, STT, worker settings, etc.).

Docker (Experimental):

cp configs/env.example .env  # edit with your API keys
docker compose up -d

Configure

# Interactive setup wizard
hotplex onboard

# Or auto-generate all configs:
hotplex onboard --non-interactive --enable-slack --enable-feishu

Run

# Development mode (foreground)
make dev

# Production mode (background daemon)
hotplex gateway start -d

# Stop / restart
hotplex gateway stop
hotplex gateway restart -d

Install as System Service

hotplex service install              # user-level (no root)
sudo hotplex service install --level system  # system-wide
hotplex service start
hotplex service status
hotplex service logs -f

# Uninstall
hotplex service uninstall

Supports systemd (Linux), launchd (macOS), and Windows SCM.

Services

Service	Address	Note
Gateway (WebSocket)	ws://localhost:8888/ws	Main protocol endpoint
Admin API	http://localhost:9999	Management & Statistics
Web Chat UI	http://localhost:8888	Embedded SPA (served from Gateway)
Dev Web Chat	http://localhost:3000	Next.js Dev Server (make dev)

🏗️ Architecture

HotPlex sits between frontend clients and backend AI coding agents, featuring a built-in Meta-Cognition Core that abstracts protocol differences into a unified AEP v1 WebSocket layer.

┌──────────┐   ┌──────────┐   ┌──────────┐
│  Web UI  │   │  Slack   │   │  Feishu  │
└────┬─────┘   └────┬─────┘   └────┬─────┘
     │              │              │
     └──────────────┼──────────────┘
                    │  WebSocket / AEP v1
              ┌─────┴─────┐
              │  HotPlex  │  Session · Auth · Retry · B/C Config
              │  Gateway  │  Metrics · Tracing · Admin · Meta-Core
              └─────┬─────┘
     ┌──────────────┼──────────────┐
     │              │              │
┌────┴─────┐  ┌────┴──────┐  ┌───┴───────┐
│  Claude  │  │  OpenCode │  │  Pi-mono  │
│  Code    │  │  Server   │  │           │
└──────────┘  └───────────┘  └───────────┘

🔗 SDKs & Libraries

Language	Path	Features
Go	client/	Full-featured, channel-based events, production-grade
TypeScript	examples/typescript-client/	Streaming, multi-turn chat, React compatible
Python	examples/python-client/	Asyncio, session resume, CLI ready
Java	examples/java-client/	Enterprise AEP v1 implementation

Connect with Go SDK

package main

import (
    "context"
    "fmt"
    client "github.com/hrygo/hotplex/client"
)

func main() {
    c, err := client.New(context.Background(),
        client.URL("ws://localhost:8888/ws"),
        client.WorkerType("claude_code"),
        client.APIKey("<your-api-key>"),
    )
    if err != nil {
        panic(err)
    }
    defer c.Close()

    c.SendInput(context.Background(), "Explain HotPlex architecture")

    for env := range c.Events() {
        if data, ok := env.AsMessageDeltaData(); ok {
            fmt.Print(data.Content)
        }
    }
}

🛠️ Configuration

Key	Default	Description
agent_config.enabled	true	Enable agent personality/context injection
webchat.enabled	true	Serve embedded webchat SPA from gateway
worker.auto_retry.enabled	true	Intelligent LLM retry with exponential backoff
gateway.addr	localhost:8888	WebSocket gateway address
admin.addr	localhost:9999	Admin API address
db.path	~/.hotplex/data/hotplex.db	SQLite database path
log.level	info	Log level: debug, info, warn, error

Tip

See Config Reference for the full list of environment variables and YAML settings.

📖 Documentation

Area	Guide
Getting Started	Quick Start · Reference Manual · Whitepaper
Protocol	AEP v1 Specification
Architecture	Gateway Design · Agent Config Design · Meta-Cognition Design
Security	Authentication · SSRF Protection
Operations	Admin API · Observability · Testing

👥 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feat/AmazingFeature)
3. Commit with conventional messages (git commit -m 'feat: add AmazingFeature')
4. Push to the branch (git push origin feat/AmazingFeature)
5. Open a Pull Request

Note

All build/test/lint operations must use make targets. See make help for the full list.

🛡️ Security

If you discover a security vulnerability, please do NOT open a public issue. Report it via SECURITY.md or contact maintainers directly.

📜 License

Distributed under the Apache License 2.0.