TrinityProxy

Distributed SOCKS5 proxy network with a central controller, web dashboard, and agent nodes.

Status: ROADMAP.md · MISSING_COMPONENTS.md

---

Quick start

# Local dev (laptop)
make start-dev

# Production VPS
sudo make start

# Uninstall production (removes systemd, /opt, config — fresh install: sudo make start)
sudo make uninstall-production

# Agent dev (macOS, foreground SOCKS :1080)
make run-agent-dev

---

Two modes

Command	Where	What it does
sudo make start	Linux VPS	Installs deps, builds, secrets, systemd, optional domain/HTTPS step, prints admin credentials
make start-dev	Your laptop	Vite UI :8080, dashboard API :8081, controller :3100

Stop: make stop-production (VPS) · make stop (dev)

---

Production VPS

Prerequisites: Fresh Linux VPS with git, curl, sudo

git clone https://github.com/Skillz147/TrinityProxy.git
cd TrinityProxy
sudo make start

make start prints admin credentials at the end — save them before closing the terminal.

Locked out of the dashboard? Regenerate admin login (keeps agent keys): sudo make reset-dashboard-admin

During bootstrap, step [10/11] optionally walks through domain + Cloudflare HTTPS (DNS checklist, confirm, Caddy). You can skip and keep using the dashboard on :8081.

GCP/cloud firewall: allow inbound TCP 8081, 3100, 80, 443 (80/443 when using HTTPS).

Domain + SSL later: sudo make setup-domain or sudo ./scripts/setup-domain.sh

After install: log in → change password → Settings → Deploy Agent.

---

Local development

Prerequisites: Go 1.24+, Node.js 18+

git clone https://github.com/Skillz147/TrinityProxy.git
cd TrinityProxy
make start-dev

Open http://localhost:8080 (first run prints admin credentials). macOS agent: make run-agent-dev · docs/DEV_SETUP.md

---

Agents

• Linux VPS — curl one-liner from Deploy Agent, or sudo CONTROLLER_URL=... TRINITY_AGENT_KEY=... ./scripts/install-agent-service.sh
• Windows — make build-windows-agent + scripts/install-agent-windows.ps1 (docs/WINDOWS_AGENT.md)
• macOS — make run-agent-dev or make install-agent-macos

---

Online vs Healthy

State	Meaning
Online	Heartbeat in last 5 minutes
Healthy	SOCKS5 auth probe succeeded

---

Configuration

Production secrets: /etc/trinityproxy/ (auto-generated by make start). Dev: .env.controller (synced by make start-dev).

Full env reference: docs/ENV.md

---

License

MIT — see LICENSE