Fleet management control plane for Telemt MTProto proxy nodes

Quick Install  •  Features  •  Architecture  •  Configuration  •  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

The control-plane embeds the installer and serves it at <panel>/install-agent.sh, so once you have a running panel:

sudo bash -c "$(curl -fsSL https://panel.example.com/install-agent.sh)"

For the GitHub-hosted bootstrap script (when no panel is reachable yet — typically the very first agent on a fresh control-plane), the upstream copy is also published:

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

⚙️ Configuration

Panvex reads its configuration from environment variables and a config.toml file at startup. Operational tunables (password policy, job worker cadences, presence thresholds, GeoIP, retention) are edited at runtime via the dashboard and stored in the database.

Quick reference

Essential env vars (bootstrap)

The full list of bootstrap variables (~26) lives in docs/settings/reference.md. A ready-to-edit example config is at docs/settings/example.config.toml.

Operational settings

Operational tunables (password lockout, session timeouts, presence thresholds, retention, GeoIP, update channel, plus 20 others) are managed through the dashboard at Settings. Changes take effect immediately; a few items (session timeouts) require a panel restart and the UI surfaces a banner when that's the case.

The same list is also visible at the /api/settings/schema endpoint and documented in docs/settings/reference.md.

Logging

Both binaries log via log/slog to stderr by default. Three controls are available on the command line; each backend also accepts an env fallback so deployments can configure without flag plumbing.

Both formats carry the same fields. The structured attributes per layer (request_id, agent_id, attempt_id, job_id, …) follow the conventions in docs/superpowers/logging.md; new code should use the slog.*Context variants so the request-id correlation works through HTTP and gRPC.

Typical recipes:

# Dev: verbose text on stderr
panvex-control-plane -log-level=debug

# Prod: JSON to stdout for Loki, plus a local rotation file
PANVEX_LOG_FORMAT=json PANVEX_LOG_FILE=/var/log/panvex/panel.log \
  panvex-control-plane

# Agent under systemd: structured logs picked up by journald
panvex-agent -log-format=json

The control-plane also exposes a per-attempt enrollment timeline in the dashboard (Server Detail → Enrollment history, plus the fleet-wide /enrollment-attempts page) and a live "Recent events" section on the Server Detail page that streams the agent's slog Info+ records in real time over the existing gRPC connection.

💻 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

Glossary

Three terms appear in different layers and mean related but distinct things:

When writing code, always use agent / agent_id. When writing user copy, prefer "Server".

🏃 Local Development Flow

The dev fleet (scripts/dev-panel.sh, scripts/dev-agents.sh, scripts/dev-stop.sh) lives one level above this repo, in the workspace. It writes its DB, logs, and PIDs to .tmp/dev/. See the workspace scripts/README.md for the full orchestration loop. The flow below is the manual equivalent.

1. Bootstrap admin:

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

2. Start control plane:

PANVEX_STORAGE_DSN=data/panvex.db PANVEX_ENCRYPTION_KEY=<your-key> go run ./cmd/control-plane

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

PANVEX_GEOIP_DIR is an optional override for where auto/URL-mode GeoIP .mmdb files are written. Defaults to <dir(panvex.db)>/geoip for SQLite deployments or /var/lib/panvex/geoip otherwise. Local-mode files are read from operator-supplied absolute paths and ignore this setting.

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

🤖 Agent Deployment

Panvex supports two transport modes per agent:

• Inbound (default). The agent dials the panel. Use this when the panel is internet-reachable from the agent host.
• Outbound (reverse). The panel dials an agent that listens on a public host:port. Use this when the panel is firewalled (private network, VPN-only, behind NAT) but the agent has a public address.

The Add Server wizard (Dashboard → Servers → Add) generates the install command for either mode in one click.

Config editing requires Telemt 3.4.25+ (in-process Maestro reload). On older nodes, changes needing a runtime reload are refused with an upgrade prompt; hot fields still apply.

Inbound (the agent dials the panel)

1. Create an enrollment token: Settings → Enrollment Tokens, or the wizard mints one for you.
2. Paste the rendered command on the Telemt host:

sudo bash -c "$(curl -fsSL https://panel.example.com/install-agent.sh)"

The script is embedded into the control-plane binary and served from the panel itself — no external CDN required.

Outbound (the panel dials the agent)

Use POST /api/agents/provision-outbound (admin) or the wizard's "Panel connects to agent" branch. The endpoint creates the agent row, mints a 5-minute bootstrap token, and returns a pre-baked install command pre-configured with --mode=reverse, --listen-addr=:<port>, and the panel's CA pin. The agent listens; the panel's outbound supervisor dials it via mTLS.

Install-script source

Each wizard run lets the operator pick one of two install-script sources:

Operators on a fork or behind a private mirror override the URLs via:

PANVEX_INSTALL_SCRIPT_URL=https://panel.example.com/install-agent.sh   # panel source
PANVEX_INSTALL_SCRIPT_GITHUB_URL=https://github.example.com/raw/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

🛟 Operator tooling

./panvex-control-plane diagnose \
  -storage-driver sqlite \
  -storage-dsn /var/lib/panvex/panvex.db

./panvex-control-plane backup \
  -storage-driver sqlite \
  -storage-dsn /var/lib/panvex/panvex.db \
  -out /var/backups/panvex-$(date -u +%Y%m%dT%H%M%SZ).tar.gz

The encryption-key fingerprint embedded in both diagnose output and metadata.json is a one-way SHA-256 prefix — operators can confirm two panels share the same PANVEX_ENCRYPTION_KEY without ever exchanging the key itself.

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

Telemt updates

Separately from the panel/agent self-update above, the panel can also update the Telemt proxy binary itself on a node (admin-only, Server Detail → "Telemt update"). The panel polls the upstream telemt/telemt GitHub repo for the latest release and shows a badge when a node is behind.

• Modes. Each node has a persisted update strategy:

  • binary — the agent downloads the release asset, verifies it, and swaps the local Telemt binary in place.
  • docker — Telemt runs in a container; the panel shows a docker compose pull && up -d hint instead of dispatching a job, and the "update available" badge clears itself automatically once the node's next telemetry snapshot reports the new version.
  • none — no supervisor was detected; updates are disabled for the node.

  The agent probes its own host (systemd unit, OpenRC/procd init.d script, runit service, or a running telemt container) and suggests a strategy; the operator can accept it as-is or edit it.

• Restart command presets (binary mode only) — one of systemd:<unit>, procd:<service> (OpenWrt), openrc:<service>, runit:<service>, or a raw command:<argv> escape hatch for other supervisors. The configured command is what restarts Telemt after the binary swap; it does not depend on the supervisor's own restart policy.

• Permissions. The agent process must be able to run the configured restart command itself — either as root, or via sudoers/polkit rules scoped to that one command. Without that, the binary swap succeeds but the restart step fails.

• OpenWrt / musl. The agent detects musl libc (/lib/ld-musl-*) and downloads the matching *-musl release asset instead of the *-gnu one. Before downloading, it fail-closed preflight-checks that the target filesystem has at least 3× the downloaded archive's size free (room for the archive, the extracted binary, and the .bak of the binary being replaced) — the update is refused up front rather than left half-installed on a full disk, which matters most on small OpenWrt flash/overlay partitions.

• Safety. Downloads are HTTPS-only against an allowlisted host, verified against a .sha256 sidecar, capped at 128 MiB, and gated against downgrading below the currently-running version (overridable per-dispatch). After the swap, the agent watches the Telemt API for up to 60s to confirm the process is alive and reports the target version before declaring success; a failed health check rolls the binary back automatically.

• Version selection. Instead of only "latest", the Server Detail update control offers a dropdown of the most recent stable Telemt releases (source: the same GitHub poll, surfaced per-node via telemetry); how many versions to list is configured in Settings → Updates (telemt_versions_to_show, default 5, clamped to 1–20). Picking an older version than the one currently running shows a warning confirm dialog and dispatches the job with the downgrade override enabled; the same override is forced automatically when the node's current version can't be parsed, since the panel has no baseline to compare against.

This is independent of the Telemt 3.4.25+ requirement noted above for in-process config-reload — the binary-update feature itself has no minimum Telemt version.

_{Built with ❤️ for Telemt fleet operators}