Fleet management control plane for Telemt MTProto proxy nodes

Quick Install  •  Features  •  Architecture  •  Development  •  Docker

✨ Features

🚀 Quick Install

Control Plane

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

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).

# Control Plane
PANVEX_ADMIN_PASS='<password>' \
PANVEX_HTTP_PORT=8080 \
PANVEX_GRPC_PORT=8443 \
  sudo -E bash install.sh

# Agent
PANVEX_PANEL_URL='https://panel.example.com' \
PANVEX_ENROLLMENT_TOKEN='<token>' \
  sudo -E bash install-agent.sh

🏗️ 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         │
└─────────────────────────────────────────────────────┘

💻 Development

Prerequisites

• Go 1.26+  ·  Node.js 22+  ·  sqlc  ·  protoc + Go plugins

Backend

go build ./...                    # Build all
go test ./...                     # Run tests
go test -race ./...               # Race detector
golangci-lint run ./...           # Lint
sqlc generate                     # Regenerate DB code

Frontend

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:

go run ./cmd/control-plane bootstrap-admin \
  -username admin \
  -password '<strong-password>'

2. Start control plane:

go run ./cmd/control-plane -http-addr :8080 -grpc-addr :8443

3. Start frontend dev server:

cd web && npm run dev

Dashboard at http://localhost:5173, API proxied to :8080

cd web && npm run build:embed
cd .. && go build -tags embeddedui -o panvex-control-plane ./cmd/control-plane

🐳 Docker

Each compose file ships a bootstrap service under --profile bootstrap that creates the first admin one-shot. It refuses to plant an account on a non-empty store, so it's safe to re-run.

# 1. First-run admin (run before bringing up the backend so the SQLite
#    file isn't contended).
PANVEX_BOOTSTRAP_PASSWORD='<strong-password>' \
  docker compose -f deploy/docker-compose.sqlite.yml \
    --profile bootstrap run --rm bootstrap

# 2. Start the stack.
docker compose -f deploy/docker-compose.sqlite.yml up --build -d

# 1. Start Postgres + backend (creates schema on first boot).
docker compose -f deploy/docker-compose.postgres.yml up --build -d

# 2. First-run admin.
PANVEX_BOOTSTRAP_PASSWORD='<strong-password>' \
POSTGRES_PASSWORD='<db-password>' \
  docker compose -f deploy/docker-compose.postgres.yml \
    --profile bootstrap run --rm bootstrap

# 1. Bring up the stack. Required env vars are enforced via ${VAR:?...}.
POSTGRES_PASSWORD='<strong-db-password>' \
PANVEX_ENCRYPTION_KEY='<strong-encryption-key>' \
  docker compose -f deploy/docker-compose.prod.yml up --build -d

# 2. First-run admin. Reuse the same PANVEX_ENCRYPTION_KEY so freshly
#    minted secrets are readable to the running backend.
POSTGRES_PASSWORD='<strong-db-password>' \
PANVEX_ENCRYPTION_KEY='<strong-encryption-key>' \
PANVEX_BOOTSTRAP_PASSWORD='<strong-admin-password>' \
  docker compose -f deploy/docker-compose.prod.yml \
    --profile bootstrap run --rm bootstrap

Override the admin username via PANVEX_BOOTSTRAP_USERNAME (default: admin).

Dashboard: http://localhost:8080  ·  gRPC: localhost:8443

🤖 Agent Deployment

1. Create an enrollment token: Settings → Enrollment Tokens
2. On each Telemt server:

sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/lost-coder/panvex/main/deploy/install-agent.sh)"

./panvex-agent bootstrap \
  -panel-url https://panel.example.com \
  -enrollment-token '<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:

./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.

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.

_{Built with ❤️ for Telemt fleet operators}