____   _   _ _   _  ____ _____ _____
| __ ) | | | | \ | |/ ___| ____| ____|
|  _ \ | | | |  \| | |  _|  _| |  _|
| |_) || |_| | |\  | |_| | |___| |___
|____/  \___/|_| \_|\____|_____|_____|
  

Bungee

A high-performance, configurable reverse proxy server built for the Bun runtime.

Languages: English | 中文

---

🌟 Overview

Bungee is a Bun + TypeScript reverse proxy designed for teams that want high throughput and programmable traffic control in the JS/TS ecosystem. It combines hot configuration reloads, multi-process execution, plugin-based request/response transformations, and a built-in web dashboard.

Why Bungee?

• Developer-native: Configure and extend gateway behavior in TypeScript-friendly workflows.
• Production-ready: Multi-worker architecture, structured logging, health checks, and failover support.
• Extensible by design: Plugin system for hooks, APIs, dashboard widgets, and AI provider format conversion.

---

✨ Feature Highlights

Area	Highlights
Runtime & Performance	Bun runtime, multi-worker architecture, zero-downtime reload
Traffic Control	Route/upstream layering, load balancing, failover, health checks
Transformation	Expression engine, request/response mutation, streaming transform support
Operations	Web dashboard, CLI daemon management, structured logging, Docker support
Extensibility	Plugin hooks, plugin APIs, native dashboard widget integration

For technical deep dives, use the docs index in the next section.

---

🖥️ Project Showcase

Bungee ships with a built-in industrial dark dashboard for operating routes, services, request logs, plugins, and runtime configuration from one control surface.

Operations Dashboard

• Track request volume, success rate, latency, and upstream health in one view.
• Monitor reusable services and endpoint pools with status-aware cards.
• Inspect request, response-time, success-rate, and error trends from the dashboard.

Route Inventory

• Manage route-to-service bindings, direct responses, rewrites, and feature flags.
• Filter routes by target type, feature set, and health status.
• Keep reusable service pools visible while editing route behavior.

Configuration Center

• Edit system settings, global authentication, and body logging policies.
• Switch between form-based controls and JSON configuration editing.
• Reload configuration or restart the runtime directly from the dashboard.

---

📚 Documentation

Documentation index: docs/README.md

Start Here

• Configuration Guide
• Core Capabilities
• Architecture
• Web Dashboard
• CLI Reference
• Deployment (Docker)
• Development Guide

Advanced Topics

• Plugin System
• Plugin Development
• AI Provider Conversion

---

🚀 Quick Start

Option 1: CLI (Recommended for Production)

# Initialize configuration (creates ~/.bungee/config.json)
npx bungee init

# Start daemon
npx bungee start

# Check status
npx bungee status

Configuration model

Bungee now uses Config Model V3:

• Reusable backend pools live under services[].endpoints
• Routes usually reference a service with service
• Config fields use snake_case, such as config_version, body_parser_limit, path_rewrite, and retry_on
• Older config files are migrated in memory to V3 on load

See Configuration Guide for the current schema.

Option 2: Docker

docker-compose up -d

Option 3: Development Mode

bun install
bun dev

Dashboard URL (default): http://localhost:8088/__ui/

---

🗺️ Roadmap

• Web Dashboard
• CLI Tool
• Streaming Support
• API Transformers
• Plugin System
• WebSocket Proxying
• gRPC Proxying
• Automatic TLS/SSL
• Prometheus Metrics
• Rate Limiting

Have an idea? Open an issue.

---

🤝 Contributing

Contributions are welcome.

• Follow Conventional Commits
• Open an issue before larger feature work
• Include tests for behavior changes

---

📄 License

MIT License. See LICENSE.

---

Made with ⚡ by the Bungee team

GitHub • Issues • Discussions