SpecterGate

A self-hosted control panel for proxy users, subscriptions, nodes and DNS tunnels.

SpecterGate combines a React interface with a FastAPI backend and Xray-core. It supports individual and shared subscriptions, administrator scopes, per-user resource permissions and traffic quotas.

Features

• VLESS, VMess, Trojan and Shadowsocks inbounds with Xray or Sing-box.
• Native Hysteria2, TUIC, ShadowTLS v3, restricted SSH forwarding and dedicated per-user MTProto listeners on the local node.
• HWID subscription registration limits, periodic user traffic resets and bounded automatic renewal.
• Xray TLS fallbacks, TCP/UDP FinalMask, VLESS encryption, ECH and Reality ML-DSA-65 key generation.
• Owner-scoped Cloudflare DNS management and scheduled CDN edge selection with verified HTTPS probes.
• Durable SMTP/Discord event notifications, signed stable-release updates, Persian/English UI and an installable network-only PWA.
• Optional native WireGuard IPv4 server with encrypted user keys, config files, QR and quota/expiry reconciliation.
• Optional native AmneziaWG with separate peers and keys, per-user grants, IPv4 configuration/QR and a root companion for traffic and expiry enforcement.
• Encrypted TOTP secrets, protected recovery-code hashes and single-use login codes.
• Hosts/DNS editing, routing diagnostics against the running Xray core, and local online-IP monitoring.
• Managed Xray extension for independent user/IP disconnection and atomic concurrent-IP limits, without restarting other users' connections.
• Certificate upload plus a separate Linux Certbot worker and renewal hooks.
• RAW/TCP, WebSocket, gRPC, HTTPUpgrade, XHTTP and mKCP transports; TLS and VLESS Reality.
• Validated advanced TLS/Reality, Sniffing, Sockopt and stream options, subscription ordering and host overrides.
• Subscription links, QR codes, Base64, raw links, Xray JSON, Clash Meta and Sing-box exports. Export compatibility depends on the selected protocol and transport.
• Individual and group access policies for inbounds and DNS tunnels.
• Administrator hierarchy, scoped permissions, plans and quotas.
• Local Xray management and a pull-based remote node agent.
• DNSTT and NoizDNS profile generation, DNS multiplexing and an optional authenticated local SOCKS gateway with per-user accounting.
• Node-specific Direct/IPv4/Block/WARP routing and SOCKS5/HTTP proxy outbounds with encrypted credentials.
• Fail2ban SSH status, ban/unban and protection settings through a restricted local bridge, with independent administrator permissions.
• Installation-specific Telegram bot: administrator user creation, subscription QR delivery and owner-only encrypted backups.
• SQLite, PostgreSQL, MySQL, MariaDB or TimescaleDB; a quick server installer, Docker Compose, Nginx and systemd deployment.

This project is under active development. OpenVPN is not implemented. Native AmneziaWG and certificate management require their Linux services; client and public-network compatibility must be verified for your deployment. Automated sales and payment processing are outside the project scope.

See the version 0.2 Persian guide for setup, engine compatibility, device policies and update limitations. Auxiliary engines currently run on the local node only. HWID is a client-supplied identifier, not hardware attestation.

Quick server setup

On a dedicated Debian/Ubuntu server (Python 3.11+), replace the domain and run:

curl -fsSLo /tmp/spectergate-install.sh https://raw.githubusercontent.com/SpecterLogic/SpecterGate/main/install.sh && sudo bash /tmp/spectergate-install.sh --domain panel.example.com --private-panel

Add --database postgresql, mysql, mariadb or timescaledb for a local database, or --version TAG_OR_COMMIT to select an existing version. SQLite is the default. The installer generates owner credentials, configures HTTPS and installs the spectergate management command. Your domain must point to the server, with TCP ports 80/443 reachable.

The installer and Docker build compile a pinned Xray revision with the session-control extension in backend/core; the first build requires extra time and Internet access to Go dependencies. Existing installations using a standard Xray binary need the managed core upgrade before targeted disconnection or IP-limit enforcement is available.

--private-panel puts management on a dedicated port and random URL path; allow that port in your provider firewall. Use --panel-port PORT to select the port. Add --wireguard for native WireGuard (UDP 51820), or --amneziawg for native AmneziaWG (UDP 51821). The full private URL is printed during installation. Public subscription paths remain available separately. HTTPS and administrator authentication are still required. See the native services guide for permissions, setup and deployment limits.

spectergate status
spectergate logs
sudo spectergate restart

See installation, bot, backups and routing for paths, recovery and configuration. Each installation uses its owner's own Telegram bot token. Network filtering resistance depends on the configured transport, endpoint and client; connectivity must be tested on the intended networks.

Local development

Requirements: Python 3.11+, Node.js 20+ and npm. Xray-core is required to validate and run generated Xray configurations.

cd backend
python -m venv .venv
source .venv/bin/activate
# Windows: .venv/Scripts/Activate.ps1
pip install -r requirements-dev.txt
cp .env.example .env

Set these values in backend/.env before starting:

SPECTERGATE_SECRET_KEY=<random-secret-at-least-32-characters>
SPECTERGATE_ADMIN_PASSWORD=<unique-password-at-least-12-characters>
SPECTERGATE_SESSION_COOKIE_SECURE=false
SPECTERGATE_PUBLIC_HOST=127.0.0.1
SPECTERGATE_SUBSCRIPTION_BASE_URL=http://127.0.0.1:8000

Use SPECTERGATE_SESSION_COOKIE_SECURE=true when serving through HTTPS. Sample passwords and placeholder secrets are rejected at startup. Set SPECTERGATE_XRAY_BINARY to the installed binary path.

uvicorn app.main:app --host 127.0.0.1 --port 8000

In a separate terminal:

cd frontend
npm ci
npm run dev

Open http://127.0.0.1:5173. The initial administrator username is admin; its password comes from the environment file. API documentation is disabled by default; set SPECTERGATE_EXPOSE_API_DOCS=true to expose /api/docs.

Docker

cp .env.docker.example .env
# Replace all placeholder values and configure the public URL.
docker compose up -d --build

The web container binds to 127.0.0.1:8080; put it behind a host HTTPS reverse proxy. For local HTTP-only testing, set SPECTERGATE_SESSION_COOKIE_SECURE=false. Publish every inbound TCP/UDP port that clients need. Database overrides are docker-compose.postgres.yml, docker-compose.mysql.yml, docker-compose.mariadb.yml and docker-compose.timescale.yml. MySQL/MariaDB require separate administrator and application passwords.

The backend manages local processes and listeners; run one API worker per instance. DNSTT server installation and DNS records are separate deployment steps described in the tunnel setup screen.

Documentation

• Server installation, bot and encrypted backups
• Feature coverage and remaining compatibility work
• Access policies, subscriptions and tunnels
• Architecture
• Remote node agent
• Deployment files

The subscription page is /s/<token>; the client subscription endpoint is /sub/<token>. Individual and group tokens can be revoked independently. Resource restrictions also apply to generated server configurations.

Verification

cd backend
pytest

cd ../frontend
npm run build

Native configuration checks can be enabled with XRAY_TEST_BINARY pointing to an installed Xray executable. They validate server and exported client configurations, including VLESS Reality and XHTTP.

Operational notes

• Back up the database and server key material before upgrades.
• Keep runtime databases, private keys and environment files outside version control.
• Local Xray reconciliation runs every 30 seconds while the managed core is running. Remote nodes use their configured polling interval.
• The local DNS SOCKS gateway checks active connections and commits traffic every second. External tunnel targets require their own authorization and accounting.
• Device-limit values are stored in plans; strict device/HWID enforcement is not implemented.
• Additional tables are created at startup. General versioned database migrations are not yet implemented.

License

MIT.

• راهنمای فارسی از نصب تا ساخت کانفیگ