ProxyFleet

A self-hosted control plane for deploying and managing distributed HTTP and SOCKS5 proxy nodes.

Quick start · Features · Architecture · Updating · Contributing

ProxyFleet keeps a private proxy fleet understandable and manageable from one web interface. A single control plane stores the desired configuration, lightweight agents connect outbound from your VPS instances, and each node can serve multiple independent authenticated proxies.

There is no required .env file. The owner account, password, public URL, session secret, encryption key, and Web Push keys are created or configured during first-run setup and stored in a persistent Docker volume.

Important

Docker Hub is the recommended installation source. Building from the GitHub repository is fully supported for development, auditing, and custom images.

✨ Features

• one control plane for multiple proxy nodes;
• multiple independent proxies on a single node;
• authenticated HTTP proxy with CONNECT support;
• authenticated SOCKS5 proxy;
• one protocol per managed proxy, with generated connection URLs;
• create, disable, move, and edit proxies without restarting containers;
• encrypted storage and availability checks for third-party HTTP/SOCKS5 proxies;
• one-time enrollment tokens for secure agent registration;
• node heartbeat, uptime, traffic, active connections, RAM, goroutines, and load average;
• activity and traffic analytics across the fleet;
• infrastructure event log;
• Telegram notifications with optional HTTP(S) proxy support;
• installable PWA with per-device Web Push preferences;
• configurable system name, logo, and owner password;
• in-app update notices based on the latest published GitHub Release;
• English and Russian interface;
• responsive desktop and mobile navigation;
• loopback, private, and link-local destination blocking by default;
• multi-architecture images for linux/amd64 and linux/arm64.

🏗️ Architecture

Browser
   │ HTTPS
   ▼
Reverse proxy (nginx / Caddy)
   │ 127.0.0.1:8088
   ▼
ProxyFleet control plane
   │ outbound HTTPS connections from agents
   ├───────────────┬───────────────┐
   ▼               ▼               ▼
Agent / VPS 1      Agent / VPS 2      Agent / VPS N
HTTP / SOCKS5      HTTP / SOCKS5      HTTP / SOCKS5

The control plane stores desired state. Agents initiate the connection to the panel, receive their configuration, and send heartbeat data back. Proxy nodes do not need a publicly exposed management port.

📦 Requirements

For a standard deployment:

• a Linux server;
• Docker Engine 24 or newer;
• Docker Compose v2;
• a domain and HTTPS reverse proxy for a public installation.

For local development without Docker:

• Go 1.26 or newer;
• Node.js only for JavaScript syntax checks.

🚀 Quick start (recommended)

Install the published image from Docker Hub:

sudo mkdir -p /opt/proxyfleet
sudo chown -R "$USER":"$(id -gn)" /opt/proxyfleet
cd /opt/proxyfleet

curl -fsSL https://raw.githubusercontent.com/neluckoff/proxyfleet/master/docker-compose.yml \
  -o docker-compose.yml

docker compose pull
docker compose up -d --no-build
docker compose ps

The control plane is now available at http://127.0.0.1:8088.

On first open:

1. choose the owner username;
2. create a password with at least 12 characters;
3. enter the public HTTPS URL of the panel;
4. finish the setup wizard.

The password is stored only as a bcrypt hash. Session signing and data-encryption secrets are generated automatically. Persistent data lives in the proxyfleet-control-data Docker volume.

Build from GitHub instead

Use this option when you want to inspect or modify the source before building:

git clone https://github.com/neluckoff/proxyfleet.git
cd proxyfleet
docker compose up -d --build

To use a custom registry or immutable image tag:

PROXYFLEET_IMAGE=registry.example.com/team/proxyfleet:1.0.0 \
  docker compose up -d --no-build

🌐 Production reverse proxy

The Compose service binds the panel to 127.0.0.1:8088 only. Publish it through HTTPS with nginx, Caddy, Traefik, or another reverse proxy.

Example nginx server:

server {
    listen 443 ssl http2;
    server_name proxy.example.com;

    location / {
        proxy_pass http://127.0.0.1:8088;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Secure cookies are enabled automatically for direct TLS connections or when X-Forwarded-Proto: https is present.

🛰️ Connect a node

1. Open Nodes in the panel.
2. Select Add node.
3. Enter its name, region, public host, and proxy ports.
4. Run the generated Docker command on the new VPS.

The enrollment token is valid once. After enrollment, the agent receives a permanent credential and stores it in the proxyfleet-node-data volume.

The generated command uses the same neluckoff/proxyfleet:latest image in agent mode. No additional image is required.

🔐 Create and manage proxies

For a managed proxy, choose:

• a display name;
• HTTP or SOCKS5;
• the node that should serve it;
• a username and password, or let ProxyFleet generate the password.

The complete connection URL is shown only after creation or credential rotation. Save it immediately: managed proxy passwords are stored only as hashes.

Third-party proxies

In the same creation dialog, select External proxy and paste a connection URL:

http://login:[email protected]:3128
socks5://login:[email protected]:1080

The URL is encrypted before it reaches state.json; passwords stay masked in the API and interface. ProxyFleet can check reachability, record latency, edit metadata, and exclude the connection from local use. It cannot disable the subscription at the external provider.

🔥 Firewall

Expose HTTP/SOCKS5 ports only to trusted clients:

sudo ufw allow from <CLIENT_IP> to any port 3128 proto tcp
sudo ufw allow from <CLIENT_IP> to any port 1080 proto tcp

Do not expose HTTP/SOCKS5 ports to the whole internet, even when authentication is enabled.

🔔 Notifications and PWA

Telegram

The Settings page accepts a bot token, chat ID, and optional HTTP(S) proxy URL. The connection test calls getMe and sends a test message. The saved token is never returned to the browser.

Notifications cover node enrollment, offline/online transitions, configuration changes, and proxy operations.

Web Push

ProxyFleet can be installed as a PWA. Under Settings → Application & Push, each browser or device can subscribe independently and choose notifications for nodes, proxies, and system events.

Production Web Push requires HTTPS. localhost and 127.0.0.1 remain valid for local development. VAPID keys are generated automatically and stored in the private control-plane volume.

♻️ Updating

Docker Hub installation

From the directory containing docker-compose.yml:

cd /opt/proxyfleet
docker compose pull
docker compose up -d --no-build --remove-orphans
docker image prune -f

This recreates the container with the newest neluckoff/proxyfleet:latest image while preserving proxyfleet-control-data.

For reproducible production deployments, pin PROXYFLEET_IMAGE to an exact release such as neluckoff/proxyfleet:0.5.3 or to an immutable image digest from Docker Hub Tags.

Update a standalone node installed with the generated docker run command:

docker pull neluckoff/proxyfleet:0.5.3
docker rm -f proxyfleet-node
docker run -d --name proxyfleet-node --restart unless-stopped --network host \
  -v proxyfleet_node_data:/data \
  -e CONTROL_URL=https://proxy.example.com \
  neluckoff/proxyfleet:0.5.3 agent

Replace CONTROL_URL with your panel URL. The existing proxyfleet_node_data volume contains the enrolled agent credential, so no new enrollment token is needed.

GitHub source installation

cd /opt/proxyfleet
git pull --ff-only
docker compose up -d --build
docker image prune -f

💾 Backup and restore

All control-plane data is stored in proxyfleet-control-data.

Create a backup:

docker run --rm \
  -v proxyfleet-control-data:/data:ro \
  -v "$PWD":/backup \
  alpine tar -czf /backup/proxyfleet-backup.tar.gz -C /data .

Restore only while the control plane is stopped:

docker compose down
docker run --rm \
  -v proxyfleet-control-data:/data \
  -v "$PWD":/backup:ro \
  alpine sh -c 'rm -rf /data/* && tar -xzf /backup/proxyfleet-backup.tar.gz -C /data'
docker compose up -d --no-build

⚙️ Configuration

Variable	Component	Default	Purpose
LISTEN_ADDR	control plane	:8080	HTTP listener inside the container
DATA_PATH	control plane	/data/state.json	Persistent state file
NODE_IMAGE	control plane	neluckoff/proxyfleet:latest	Image used in generated node commands
PROXYFLEET_IMAGE	Compose	neluckoff/proxyfleet:latest	Control-plane and agent image override
CONTROL_URL	agent	required	Public control-plane URL
ENROLL_TOKEN	agent	first start	One-time enrollment token
AGENT_STATE_PATH	agent	/data/agent.json	Persistent agent state
AGENT_HEALTH_SOCKET	agent	/tmp/proxyfleet-agent-health.sock	Internal Unix socket used by Docker health checks
HEALTHCHECK_URL	control plane	http://127.0.0.1:8080/health	Override for the built-in control-plane health check

Container health

The published image includes a mode-aware Docker health check. For the control plane it calls the local /health endpoint. For an agent it verifies the HTTP/SOCKS5 listeners and a recent control-plane synchronization.

docker inspect --format '{{.State.Health.Status}}' proxyfleet-control
docker inspect --format '{{.State.Health.Status}}' proxyfleet-node

🧑‍💻 Local development

git clone https://github.com/neluckoff/proxyfleet.git
cd proxyfleet
go mod download
DATA_PATH=./state.json LISTEN_ADDR=127.0.0.1:8080 \
  go run ./cmd/proxyfleet server

Run the checks:

go test ./...
go vet ./...
node --check internal/control/web/app.js
node --check internal/control/web/i18n.js

Project layout

cmd/proxyfleet/             server and agent entry point
internal/agent/             proxy engine, node sync, and metrics
internal/control/           HTTP API, authentication, and file storage
internal/control/web/       embedded web interface and PWA assets
internal/model/             shared control-plane and agent models
.github/workflows/          CI and Docker publishing
docker-compose.yml          control plane
docker-compose.node.yml     standalone proxy node

🔌 HTTP API

Main route groups:

• /api/setup/* — first-run setup;
• /api/login, /api/logout, /api/me — owner session;
• /api/nodes — node management;
• /api/proxies — managed and external proxy management;
• /api/pwa/* — Web Push subscriptions and preferences;
• /api/analytics, /api/activity, /api/events — observability;
• /api/settings/* — branding, Telegram, and password changes;
• /api/agent/* — enrollment, configuration, and heartbeat.

All administrative routes except setup, login, and public branding require an authenticated owner session.

🐳 Image publishing

.github/workflows/docker-publish.yml automatically publishes a release when a new application version reaches master. The workflow verifies that the control plane and node agent use the same semantic version, runs the test suite, publishes linux/amd64 and linux/arm64 images to Docker Hub, verifies the resulting manifest, and only then creates the matching Git tag and GitHub Release with generated release notes.

Required GitHub Actions secrets:

• DOCKERHUB_USERNAME — Docker Hub username;
• DOCKERHUB_TOKEN — access token with Read & Write permission.

To prepare a release, update both version constants before merging:

// internal/control/server.go
const version = "0.5.3"

// internal/agent/agent.go
const agentVersion = "0.5.3"

If v0.5.3 does not exist yet, the workflow produces Docker tags :0.5.3, :0.5, and :latest, then creates GitHub Release v0.5.3. If the Git tag already exists, the workflow exits without republishing anything. Manual workflow runs follow the same version and duplicate checks.

🤝 Contributing

Please read CONTRIBUTING.md before opening a pull request. Use GitHub Issues for bugs and feature requests. Report security issues privately as described in SECURITY.md.

🗺️ Roadmap

• mTLS or WireGuard between control plane and nodes;
• node restart and update operations from the panel;
• automatic failover and a unified gateway endpoint;
• traffic and connection limits;
• additional roles and 2FA;
• PostgreSQL support for redundant control-plane deployments.

📄 License

ProxyFleet is open-source software licensed under the MIT License.