Hotplex Gateway

The Unified Bridge for AI Coding Agents

简体中文 | English

---

Hotplex is a high-performance Go gateway that provides a single WebSocket interface to access any AI Coding Agent. It abstracts protocol differences, manages complex session lifecycles, and connects users across Web, Slack, and Feishu — all through one optimized binary.

One Gateway. Any Agent. Every Channel.

🧭 Table of Contents

• Core Features
• Quick Start
• Architecture
• SDKs & Libraries
• Configuration
• Documentation
• Contributing
• License

🚀 Core Features

🔌 Connectivity

• 🔹 Unified AEP v1 Protocol: 23+ event types over WebSocket (streaming, permissions, MCP Elicitation).
• 🔹 Multi-Channel Bridge: Bidirectional support for Slack (Socket Mode) and Feishu (WebSocket).
• 🔹 Worker Adapters: Out-of-the-box support for Claude Code, OpenCode Server, and Pi-mono.

🤖 Agent Intelligence

• 🔹 Agent Config System: Define agent personality (SOUL.md), workspace rules (AGENTS.md), tool guides (SKILLS.md), user profile (USER.md), and persistent memory (MEMORY.md) — automatically injected into every worker session via B/C dual channels.
• 🔹 Platform Variants: Per-platform config overrides (e.g. SOUL.slack.md, SOUL.feishu.md) appended automatically for channel-specific behavior.

🛡️ Reliability & Security

• 🔹 Robust Session Management: 5-state lifecycle machine with crash recovery and auto-reconnection.
• 🔹 Security First: JWT ES256 authentication, SSRF protection, and command whitelisting.
• 🔹 Observability: Prometheus metrics, OpenTelemetry tracing, and structured JSON logging.
• 🔹 Admin API: Dedicated management interface for session control and health monitoring.

💎 Developer Experience

• 🔹 CLI Self-Service: Interactive onboard wizard, doctor diagnostics, security audit, status check, and config validate — all built into a single binary.
• 🔹 Ready-to-use Web UI: Next.js 16 + Vercel AI SDK integration with Premium UX, Generative UI (GenUI), and Glassmorphism design system.
• 🔹 Hot-Reload Config: Update gateway settings without downtime.
• 🔹 Multi-Language SDKs: Native support for Go, TypeScript, Python, and Java.

⚡ Quick Start

1. Installation

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

2. Configure

# Interactive setup wizard (detects existing config, supports keep-or-reconfigure)
./hotplex onboard

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

3. Run Development Servers

make dev

• Gateway WebSocket: ws://localhost:8888/ws
• Admin API: http://localhost:9999
• Web Chat: http://localhost:3000

3. Connect via 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)
        }
    }
}

🧱 Architecture

Hotplex acts as an orchestration layer between frontend clients and backend coding agents.

📦 SDKs & Libraries

Language	Path	Features
Go	client/	Full feature, 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

🛠️ Configuration

Hotplex uses Viper for configuration with support for environment variable overrides.

Key	Default	Description
agent_config.enabled	true	Enable agent personality/context injection
agent_config.config_dir	~/.hotplex/agent-configs/	Directory for SOUL.md, AGENTS.md, etc.
gateway.addr	:8888	WebSocket gateway endpoint
admin.addr	:9999	Admin API endpoint
db.path	~/.hotplex/data/hotplex.db	SQLite database location
log.level	info	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
Internals	Gateway Design · Agent Config Design · Security
Management	Admin API · Testing

👥 Contributing

We welcome contributions of all kinds! Please see our Contributing Guide for more details.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feat/AmazingFeature)
3. Commit your Changes (git commit -m 'feat: Add some AmazingFeature')
4. Push to the Branch (git push origin feat/AmazingFeature)
5. Open a Pull Request

🛡️ Security

If you find a security vulnerability, please do NOT open a public issue. Report it via the instructions in our Security Policy (or contact maintainers directly).

📜 License

Distributed under the Apache License 2.0. See LICENSE for more information.

---

Built with ❤️ by the Hotplex Team