https://github.com/lost-coder/panvex
Panel & agent system for Telemt fleet management
https://github.com/lost-coder/panvex
fleet-management go panel react telemt
Last synced: 2 months ago
JSON representation
Panel & agent system for Telemt fleet management
- Host: GitHub
- URL: https://github.com/lost-coder/panvex
- Owner: lost-coder
- License: mit
- Created: 2026-03-31T11:36:28.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-18T16:59:56.000Z (3 months ago)
- Last Synced: 2026-04-18T18:13:01.317Z (3 months ago)
- Topics: fleet-management, go, panel, react, telemt
- Language: Go
- Size: 29.9 MB
- Stars: 32
- Watchers: 1
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Agents: AGENTS.md
Awesome Lists containing this project
README
Fleet management control plane for Telemt MTProto proxy nodes
Quick Install •
Features •
Architecture •
Development •
Docker
---
## ✨ Features
| | Feature | Description |
|---|---------|-------------|
| 📊 | **Fleet Dashboard** | Real-time monitoring with metrics, health indicators, and alerts |
| 👥 | **Managed Clients** | Centralized client management with secret rotation and quotas |
| 🤖 | **Agent System** | Lightweight per-node agents with mTLS enrollment and gRPC streaming |
| 🗄️ | **Dual Storage** | SQLite for dev/lightweight, PostgreSQL for production |
| 🔄 | **Self-Update** | Panel and agents update themselves from GitHub Releases |
| 📦 | **Embedded UI** | Single binary ships the React dashboard — no separate web server |
| 🔐 | **TOTP 2FA** | Optional two-factor authentication for operator accounts |
| 🛡️ | **RBAC** | Viewer, Operator, and Admin roles with middleware enforcement |
---
## 🚀 Quick Install
### Control Plane
```sh
sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/lost-coder/panvex/main/deploy/install.sh)"
```
> Interactive wizard: ports, storage, TLS, firewall, admin account — all configured step by step.
### Agent
```sh
sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/lost-coder/panvex/main/deploy/install-agent.sh)"
```
> Requires a panel URL and enrollment token (create one in **Settings → Enrollment Tokens**).
📋 Non-interactive mode (CI / automation)
```sh
# Control Plane
PANVEX_ADMIN_PASS='' \
PANVEX_HTTP_PORT=8080 \
PANVEX_GRPC_PORT=8443 \
sudo -E bash install.sh
# Agent
PANVEX_PANEL_URL='https://panel.example.com' \
PANVEX_ENROLLMENT_TOKEN='' \
sudo -E bash install-agent.sh
```
Run `bash install.sh --help` for all environment variables.
---
## 🏗️ Architecture
```
┌─────────────────────────────────────────────────────┐
│ 🌐 Browser │
│ React · TanStack Router/Query │
├─────────────────────────────────────────────────────┤
│ 📡 Control Plane (:8080) │
│ HTTP API · WebSocket · Embedded UI │
├─────────────────────────────────────────────────────┤
│ 🔒 gRPC Gateway (:8443) │
│ mTLS · Bidirectional Stream · Jobs │
├─────────────────────────────────────────────────────┤
│ 🤖 Agent (per Telemt node) │
│ Heartbeats · Snapshots · Job Execution │
└─────────────────────────────────────────────────────┘
```
📁 Repository Layout
| Directory | Description |
|-----------|-------------|
| `cmd/control-plane` | Control plane server (HTTP + gRPC + embedded UI) |
| `cmd/agent` | Agent binary with bootstrap and enrollment |
| `internal/controlplane` | Auth, jobs, presence, storage, server logic |
| `internal/agent` | Telemt client, runtime, self-updater |
| `internal/gatewayrpc` | Generated gRPC stubs (protobuf) |
| `internal/security` | Enrollment, crypto, mTLS CA |
| `web` | React dashboard (Vite + TailwindCSS 4 + TanStack) |
| `db/migrations` | PostgreSQL and SQLite schema migrations |
| `proto` | Protobuf gateway contract |
| `deploy` | Install scripts, Docker Compose, nginx config |
🔧 Tech Stack
| Layer | Technology |
|-------|------------|
| Backend | Go 1.26, chi/v5, pgx/v5, modernc.org/sqlite, gRPC |
| Frontend | React 19, Vite 7, TailwindCSS 4, TanStack Router + Query |
| UI Kit | [@lost-coder/panvex-ui](https://github.com/lost-coder/panvex-ui) — Radix UI + CVA |
| Database | PostgreSQL (primary) · SQLite (lightweight) |
| Deploy | Multi-stage Docker · systemd · nginx |
---
## 💻 Development
### Prerequisites
- **Go** 1.26+ · **Node.js** 22+ · [sqlc](https://sqlc.dev) · [protoc](https://grpc.io/docs/protoc-installation/) + Go plugins
### Backend
```sh
go build ./... # Build all
go test ./... # Run tests
go test -race ./... # Race detector
golangci-lint run ./... # Lint
sqlc generate # Regenerate DB code
```
### Frontend
```sh
cd web
npm install # Install deps
npm run dev # Dev server (proxies API to :8080)
npm run build # Production build
npm run lint # ESLint
```
### 🏃 Local Development Flow
**1.** Bootstrap admin:
```sh
go run ./cmd/control-plane bootstrap-admin \
-username admin \
-password ''
```
**2.** Start control plane:
```sh
go run ./cmd/control-plane -http-addr :8080 -grpc-addr :8443
```
**3.** Start frontend dev server:
```sh
cd web && npm run dev
```
> Dashboard at `http://localhost:5173`, API proxied to `:8080`
📦 Single binary build
```sh
cd web && npm run build:embed
cd .. && go build -tags embeddedui -o panvex-control-plane ./cmd/control-plane
```
---
## 🐳 Docker
SQLite (lightweight)
```sh
docker compose -f deploy/docker-compose.sqlite.yml up --build -d
docker compose -f deploy/docker-compose.sqlite.yml exec backend \
./panvex-control-plane bootstrap-admin \
-storage-driver sqlite \
-storage-dsn /var/lib/panvex/panvex.db \
-username admin \
-password ''
```
PostgreSQL (production)
```sh
docker compose -f deploy/docker-compose.postgres.yml up --build -d
docker compose -f deploy/docker-compose.postgres.yml exec backend \
./panvex-control-plane bootstrap-admin \
-storage-driver postgres \
-storage-dsn 'postgres://panvex:panvex@postgres:5432/panvex?sslmode=disable' \
-username admin \
-password ''
```
> Dashboard: `http://localhost:8080` · gRPC: `localhost:8443`
---
## 🤖 Agent Deployment
1. Create an enrollment token: **Settings → Enrollment Tokens**
2. On each Telemt server:
```sh
sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/lost-coder/panvex/main/deploy/install-agent.sh)"
```
Manual bootstrap (without installer)
```sh
./panvex-agent bootstrap \
-panel-url https://panel.example.com \
-enrollment-token '' \
-state-file /var/lib/panvex-agent/agent-state.json
```
---
## 👥 Managed Clients
Create and manage Telemt clients centrally from the dashboard:
- 🔑 Generate secrets and `user_ad_tag`
- 📏 Set limits: connections, unique IPs, quota, expiration
- 🌐 Assign by fleet group or individual nodes
- 🔄 Rotate secrets without recreating the client
- 📈 Live deployment status, connection links, and usage per node
---
## 🔐 Security
**Two-Factor Authentication** — TOTP 2FA is optional. Enable in Profile page.
Emergency TOTP reset via CLI:
```sh
./panvex-control-plane reset-user-totp \
-storage-driver sqlite \
-storage-dsn /var/lib/panvex/panvex.db \
-username admin
```
---
## 🔄 Updates
The control plane checks GitHub Releases for new versions automatically.
| Method | Command |
|--------|---------|
| **Dashboard** | Settings → Updates → *Update Panel* / *Update Agent* |
| **CLI** | `./panvex-control-plane self-update` |
| **Auto-update** | Enable in Settings → Updates (disabled by default) |
Agents can be updated individually or in bulk. The panel sends an update job via gRPC — the agent downloads and installs the new binary automatically.
---
## 📚 Documentation
| Topic | Link |
|-------|------|
| Docs index | [`docs/README.md`](docs/README.md) |
| HTTP API (OpenAPI 3.0) | [`docs/api/openapi.yaml`](docs/api/openapi.yaml) |
| gRPC gateway reference | [`docs/api/gateway.proto.md`](docs/api/gateway.proto.md) |
| Architecture Decision Records | [`docs/architecture/adr/`](docs/architecture/adr/) |
| Operational runbook | [`docs/ops/runbook.md`](docs/ops/runbook.md) |
---
Built with ❤️ for Telemt fleet operators