Documentation

Configuration

The main configuration file is proxystack.json in the ProxyStack root folder.

Structure

{
  "settings": {
    "httpPort": 80,
    "httpsPort": 443,
    "serverAdmin": "admin@localhost",
    "environment": "development"
  },
  "sites": [...],
  "apps": [...],
  "security": {...},
  "sentinel": {...}
}

Settings File

GUI-specific settings are stored separately in proxystack.settings.json:

{
  "autoStartApache": true,
  "alertsEnabled": true,
  "slackWebhook": "https://hooks.slack.com/services/...",
  "alertEmail": "alerts@example.com"
}

Environment Profiles

Store profiles in profiles/ folder:

• profiles/proxystack.development.json
• profiles/proxystack.staging.json
• profiles/proxystack.production.json

Switch profiles from the Security tab using the Environment dropdown.

Site Configuration

Reverse Proxy Site

{
  "domain": "app.example.com",
  "proxy": {
    "target": "http://localhost:3000",
    "timeout": 60,
    "websocket": true
  },
  "ssl": {
    "enabled": true,
    "cert": "certs/app.example.com-crt.pem",
    "key": "certs/app.example.com-key.pem"
  },
  "redirectHttpToHttps": true
}

Static Site with SPA Fallback

{
  "domain": "static.example.com",
  "documentRoot": "sites/my-react-app/build",
  "spaFallback": true,
  "ssl": { "enabled": true, "cert": "...", "key": "..." }
}

Hybrid Site (Static + Proxy Routes)

{
  "domain": "hybrid.example.com",
  "documentRoot": "sites/frontend",
  "spaFallback": true,
  "proxyRoutes": [
    { "path": "/api", "target": "http://localhost:8000" },
    { "path": "/ws", "target": "ws://localhost:8001", "websocket": true }
  ],
  "ssl": { "enabled": true, "cert": "...", "key": "..." }
}

Site Fields

App Configuration

{
  "apps": [
    {
      "name": "My API",
      "command": "npm run dev",
      "workingDirectory": "apps/my-api",
      "port": 3000,
      "autoStart": true,
      "autoRestart": true,
      "subProcesses": [
        {
          "name": "Supabase",
          "command": "npx supabase start",
          "workingDirectory": null,
          "port": 54321,
          "autoStart": true
        }
      ]
    }
  ]
}

Sub-Processes

All commands are launched with echo y | piped to stdin and npm_config_yes=true set in the environment to auto-accept prompts. Sub-processes start before the main command and are killed together when the app is stopped.

SSL & Certificates

Let's Encrypt (Free Certificates)

1. Go to Certs tab
2. Click "Let's Encrypt"
3. Enter your domain and email
4. ProxyStack stops Apache, runs win-acme for HTTP-01 validation, then restarts Apache
5. Certificate files are saved to certs/

Self-Signed Certificates

Use the "Generate Self-Signed" option in the Certs tab. ProxyStack uses the bundled OpenSSL to create a certificate and key pair. Useful for local development.

Auto-Detection

When a site has SSL enabled but empty cert/key paths, ProxyStack automatically scans certs/ for matching files based on the domain name. Supported naming patterns:

• Cert: {domain}-crt.pem, {domain}-cert.pem, {domain}.crt, {domain}-fullchain.pem
• Key: {domain}-key.pem, {domain}.key, {domain}-privkey.pem
• Chain: {domain}-chain.pem, {domain}-chain-only.pem

Docker Integration

The Docker tab provides comprehensive container management (requires Docker Desktop).

Container Management

• View all containers (running and stopped) with status, ports, and image info
• Start, stop, restart, and remove containers
• View container logs with real-time streaming
• Inspect container details (full JSON configuration)
• Execute commands in running containers

Image Management

• Pull Docker images with progress indicators
• List local images with size and tag info
• Remove unused images

Docker Compose

• Compose Up/Down for multi-service deployments
• Select any docker-compose.yml file
• Managed Compose project records for imported ZIPs
• Service status, selected profile/service tracking, logs, version history, and rollback

Secure Project Import

• Drag-and-drop .zip/.7z archives onto the Dashboard or Apps view
• Detects Static, Node.js, Bun, Python, Go, .NET, Java, Ruby, PHP, Rust, Deno, Docker Compose, and Dockerfile projects
• Nested project picker ranks candidates and explains recommended folders for GitHub sample repos and monorepos
• Auto Build can use Railpack first or Nixpacks as a fallback when installed locally
• Build-plan preview shows runtime confidence, env keys, build/run commands, port mapping, and listen-probe behavior
• Import Evidence keeps archive hash, sandbox score, builder metadata, rollback target, and verdict details

Container Templates

One-click deploy for common services: NGINX, Apache, Caddy, PostgreSQL, MySQL, MongoDB, Redis, Node.js, Python, Go, Adminer, pgAdmin.

Resource Monitoring

Real-time CPU usage, memory consumption, network I/O, and disk usage per container.

Portable PostgreSQL

ProxyStack can manage a portable PostgreSQL instance without Docker.

First Time Setup

1. Click "Start PostgreSQL" in the Docker tab
2. If not installed, you'll be prompted to download (~300 MB)
3. PostgreSQL extracts to postgres/ automatically
4. Database initializes on first run

Paths

Database Console

Go to Advanced tab → Database Console. Enter connection details and execute SQL queries directly from the GUI.

Security Features

{
  "security": {
    "enableHSTS": true,
    "enableXFrameOptions": true,
    "enableXContentTypeOptions": true,
    "enableXXSSProtection": true,
    "ipWhitelist": ["192.168.1.0/24"],
    "ipBlacklist": ["10.0.0.5"]
  }
}

Security Headers

ProxyStack automatically adds security headers to all HTTPS responses: X-Content-Type-Options, X-Frame-Options, and Referrer-Policy. Additional headers (HSTS, XSS Protection) can be enabled in the Security tab.

IP Access Control

Configure IP whitelists and blacklists to restrict access to your sites.

Encrypted Secrets Vault

The Secrets & Tools tab provides an encrypted vault for storing sensitive values like API keys, database passwords, and tokens.

Auto-Start on Boot

Enable "Start ProxyStack with Windows" and "Auto-start Apache" in the Security tab to run ProxyStack as a background service.

OWASP Compliance Dashboard

The Compliance sidebar view provides automated checks against the OWASP Top 10 2025 standard.

How It Works

1. Navigate to the Compliance view in the sidebar
2. Click "Run Compliance Scan"
3. ProxyStack evaluates 10 categories (A01 through A10) against your live configuration
4. Each category shows Pass/Fail with a color-coded card
5. An overall Security Score (0–100) is calculated

OWASP Top 10 2025 Categories

Exporting Reports

Click "Export Report" to save results as CSV or TXT. Reports include the score, each category's pass/fail status, and remediation suggestions.

Web Application Firewall (WAF)

The WAF sidebar view provides request filtering with 14 built-in rules and a custom rule editor. Rules set to Block are compiled into real inline firewall conditions and reject matching requests with a 403 before your site ever sees them — on both Nginx and Apache. A rule only falls back to detection-only if its specific pattern can't be safely compiled into that engine's config (see below); the WAF view's "Enforcement" column always shows the real, current status per rule.

Built-in Rules

WAF Modes

• Detect Only — Never blocks. Matches are logged only, on every engine.
• Block & Log — Matching Block-action rules are rejected inline with a 403, on both Nginx and Apache.
• Block Silent — Same inline blocking as Block & Log; intended for cases where you don't want a block to change dashboard-facing presentation.

Whichever mode is selected, each rule's own Enforcement status — shown live in the WAF view — tells you exactly whether that specific rule is inline enforced, detection-only, export-only (Rate Limit), or disabled/invalid. A rule can only be inline-enforced when its pattern compiles as a regex and doesn't hit an engine-specific limit: on Nginx, containing a "$" that Nginx would try to read as a variable; on Apache, mixing literal whitespace with a literal double-quote, which Apache's RewriteCond has no way to escape.

Custom Rules

Click "+ Add Rule" to create rules with a name, category, regex pattern, match target (URI, query string, user agent, HTTP method, header, or remote IP), action, and severity. Custom rules are evaluated by the same engine as built-in rules, and get the same live Enforcement status.

Test WAF Rule

Click "Test WAF Rule" to type in a sample method, path, query string, and user agent and see exactly what the real rule engine decides — allowed, detected, or blocked, and which rule(s) matched. This runs the same code path as live enforcement, so a passing test means the rule will actually behave that way in production.

ModSecurity Export

Click "Export Rules" and choose the .conf format to generate a ModSecurity-compatible configuration file. This is an export only — ProxyStack does not load or run ModSecurity itself. The WAF view reports whether a ModSecurity module is actually detected on your Nginx/Apache installation, so you know upfront whether the exported file has anything to attach to.

Threat Dashboard

The bottom panel reads real events from logs/waf-threats.jsonl — timestamp, source IP, site, matched rule(s), severity, and whether the request was blocked or only detected. Requests Nginx blocks inline appear here immediately (the block already happened; this is the record of it). Everything else is picked up by a background scan that tails your access logs every 60 seconds and re-checks them against the same rules. Rate-limit-category rules are not pattern-evaluated by this engine at all — use per-site Rate Limiting settings for real request-rate enforcement.

Security Scanner

The Scanner sidebar view performs automated security assessments of your ProxyStack configuration.

Scan Types

Check Categories

• TLS Configuration — Protocol versions, cipher suites, certificate validity
• Security Headers — HSTS, CSP, X-Frame-Options, Referrer-Policy
• Directory Permissions — Write access on config files, world-readable secrets
• Secrets Exposure — API keys in config, hardcoded passwords
• Network Ports — Unnecessary open ports, default credentials
• Container Security — Privileged containers, exposed Docker socket
• Database Security — Default passwords, remote access settings

Severity Levels

Each finding is classified as Critical (red), High (orange), Medium (yellow), or Low/Info (blue). The overall security score (0–100) is weighted by severity.

Results

Scan results are persisted to logs/security-scan.json and displayed in a scrollable list with severity icons and remediation guidance.

Secrets Vault Pro

The Secrets Vault sidebar view provides DPAPI-encrypted storage for sensitive values.

Encryption

All secrets are encrypted using Windows DPAPI (Data Protection API) with the CurrentUser scope. This means secrets can only be decrypted by the same Windows user account on the same machine. No master password is needed.

Categories

Security Features

• Reveal — Shows the secret value for 5 seconds, then auto-hides
• Copy — Copies to clipboard with automatic 30-second clear
• Rotate — Generates a new 32-character cryptographically random value
• Export .env — Exports all secrets as a .env file for use in applications

Storage

Secrets are stored in config/secrets.json as DPAPI-encrypted base64 strings. The file is safe to back up but cannot be decrypted on a different machine or user account.

Compliance Reporting

The Reports sidebar view generates evidence-based compliance reports against 4 major frameworks.

Supported Frameworks

How It Works

1. Select a framework from the dropdown (or "All Frameworks")
2. Click "Generate Report"
3. Each control is evaluated against your real configuration and files
4. Results show Pass/Fail/N/A with evidence text
5. A compliance score percentage is calculated

Export Options

• Export CSV — Spreadsheet-friendly format with all check details
• Export TXT — Formatted text report suitable for auditors

Zero Trust Security

The Zero Trust sidebar view configures mutual TLS (mTLS), certificate-based authentication policies, and network segmentation.

As of v14.6.1, mTLS is actually enforced on both Nginx and Apache installs — checking "Enable mTLS" + "Require client certificate" with a valid CA cert path emits real client-cert-verification directives (ssl_client_certificate/ssl_verify_client on Nginx, SSLCACertificateFile/SSLVerifyClient require on Apache) into every HTTPS site's generated config. It applies globally to all HTTPS sites (the config has no per-site scoping). Certificate Auth Policies and Network Segmentation, described below, are also enforced as of v14.6.1 — both apply site-wide rather than honoring the policy's Target path or a zone's allowed-ports field, since neither maps cleanly onto the generated config structure. The "Export Apache Config" button still exists for producing a standalone reference file, but Apache installs no longer need it to get real enforcement.

mTLS Configuration

1. Toggle "Enable mTLS" to activate mutual TLS
2. Set the CA certificate path, server certificate path, and server key path
3. Configure Client Cert Verification (require, optional, none)
4. Set Verify Depth (certificate chain depth, default: 2)
5. Click "Save mTLS Config", then Reload/Restart the web server for it to take effect

Certificate Generation

• Generate CA — Creates a self-signed CA certificate (RSA 4096-bit, 10-year validity) for signing client and server certificates
• Generate Server Cert — Creates a server certificate (RSA 2048-bit, 2-year validity) signed by the CA. Automatically adds Subject Alternative Names (SANs) for all configured site domains, plus localhost and 127.0.0.1

Authentication Policies

Define certificate-based authentication rules. Each policy specifies a match type and value:

Enforced on both engines once mTLS is enabled, except SAN Match, which is Apache-only — stock Nginx has no variable exposing a client cert's SAN entries. OU Match has no dedicated Nginx variable either, so it falls back to a substring check against the full subject DN there. Policies apply site-wide; the Target field isn't used to scope enforcement to a specific path.

Network Segmentation

Define network zones with CIDR ranges, allowed ports, and traffic direction (inbound/outbound/both). Inbound and Both zones are enforced as an IP allow-list on both engines, merged with the Security tab's IP whitelist. Outbound zones are not enforced — they describe traffic the server itself initiates, which no request-time access-control directive can restrict. The allowed-ports field is stored but not yet used to scope enforcement to specific ports.

Trust Score

A dynamic trust score (0–100) is calculated based on: mTLS enabled (+30), CA cert configured (+15), server cert configured (+15), client verification set to "require" (+15), auth policies defined (+15), segmentation zones defined (+10). As of v14.6.1 every factor corresponds to something actually enforced.

Apache Export

Click "Export Apache Config" to generate a .conf file with SSLVerifyClient, SSLRequire directives, and IP-based <Location> blocks for network segmentation.

Configuration File

All Zero Trust settings are persisted to config/zero-trust.json:

{
  "mTLS": {
    "enabled": true,
    "caCertPath": "certs/zero-trust-ca.pem",
    "serverCertPath": "certs/zero-trust-server.pem",
    "serverKeyPath": "certs/zero-trust-server-key.pem",
    "clientVerification": "require",
    "verifyDepth": 2
  },
  "authPolicies": [...],
  "segmentationZones": [...]
}

Security Center & Process Reputation

Security Center (Enterprise tier) is a single view aggregating every security signal ProxyStack has: WAF, SentinelAI, Cluster node health, Microsoft Defender, ClamAV, Headscale VPN, Process Reputation, Local Network Exposure, and the AI Runtime Manager, into one set of status cards and one unified threat timeline. It doesn't replace the individual views (WAF, SentinelAI, Cluster, AI Runtime) - it reads the same real data they already produce and shows it in one place. Every card maps to a real provider call; an unreachable or not-installed provider is shown honestly as such, never hidden.

Process Reputation - real process monitoring for your managed apps

Monitors every ProxyStack-managed app (Apps view) and its actual child/grandchild processes via a live Windows process-tree walk - not a simulation, and not a general "scan any file" tool. Built in 5 phases, all real as of v14.11.0-14.12.0:

• Monitoring: hashes and deterministically scores every newly-seen process. A risky interpreter (PowerShell, cmd, Python, Node, etc.) isn't flagged just for being your app's own configured command - it's flagged when it shows up as an unexpected descendant spawned by your app (the "command chain" pattern real attacks use), plus known malicious command-line patterns regardless of depth.
• Reputation lookup: a local allowlist/blocklist plus a real VirusTotal hash-only lookup (never uploads a file) - cached, rate-limited to VirusTotal's public tier.
• Controlled sample submission: uploading a file's actual content to VirusTotal for a full scan requires an explicit privacy warning and confirmation - hash-only lookup is the default for every process; nothing is ever uploaded automatically.
• Sandbox detonation: runs a copy of a flagged executable in an isolated, network-restricted temp directory for ~15 seconds, watching for child processes, file writes, registry persistence, and network connections. This is real containment, but not full VM isolation - see the callout below. Can run on-demand ("Detonate in Sandbox...") or automatically once explicitly enabled.
• Policy enforcement: Kill, Quarantine, Block future re-launches, Isolate network access, or Require admin approval (pauses the process) - available manually per-process, or fully automatically once an admin explicitly raises the policy past its default of Warn-only.

Process Reputation is not a cloud-based instant-verdict service like some antivirus "unknown file" features - everything runs locally and in real time (a scan/detonation completes in seconds, not hours), and it doesn't require IAMVC to operate cloud sandbox infrastructure.

AI Runtime Manager

Local LLM hosting as a first-class managed deployment - not a separate tool bolted on, and not a fake UI. ProxyStack scans your hardware, recommends models that will actually run well on it, detects or installs a runtime, downloads a hash-verified model, and starts a real local OpenAI-compatible endpoint you manage the same way as a Site or App: Start/Stop/Restart, live health checks, logs, and a per-deployment API key. Available in the GUI's "AI Runtime" sidebar view and via proxystack ai ... in the CLI, on Windows and Linux.

How it works

1. System Scan - real CPU core count, AVX2/FMA/AVX512 support, total/available RAM, free disk, and GPU (NVIDIA via nvidia-smi, AMD/Intel via Windows device enumeration), plus Docker/WSL2/Vulkan availability.
2. Recommended Models - the built-in catalog (11 curated, hash-verified GGUF models spanning tiny through 14B-class, including a dedicated code-generation model) is filtered against your real scanned hardware, with a Recommended/Marginal/Not Recommended verdict and reason for each, plus a use-case note and a rough speed expectation.
3. Runtime Options - detects an existing llama.cpp/Ollama install, or downloads the official llama.cpp release for your platform (CPU or GPU build, matching your detected hardware) with one click/command. Never installs anything without explicit confirmation.
4. Download - the selected model's file is downloaded and its SHA256 independently verified against the catalog before it's ever marked available; a failed or cancelled download never leaves a partial file that looks installed.
5. Run Server - starts a real local server on an automatically-chosen free port (loopback-only by default), with a generated API key stored in the Secrets Vault. An explicit, off-by-default "Allow remote access" option binds to all network interfaces instead, for when you deliberately want another device to reach it.
6. Logs/Evidence - the deployment's real launch command, last health-check result, and the server's own log output.

Model catalog

A small, hand-curated list rather than open Hugging Face browsing - every entry's SHA256, file size, license, and context length is verified against the real source before it's added. Covers every practical tier: a tiny/fastest option for constrained hardware, small 1.5-3B general models, 7B-class general models (two different ones, for comparison), a dedicated code-generation model at two sizes, and 9B/14B-class larger models for when you have the RAM/VRAM to spare.

Security

Security Center's AI Runtime provider watches every deployment for real misconfiguration: a server bound to all network interfaces instead of just localhost (and separately, whether it's actually reachable on the network right now, not just configured that way); an API key that's configured but not actually being enforced by the running server (checked with a genuine test request, not just "is a key present in the vault"); a deployment marked "running" whose process has actually died; an unusually large log file; orphaned duplicate server processes; and a few other real, checked conditions - each finding comes with a plain-language explanation and a concrete fix, the same as every other Security Center finding.

Ollama support

If you already run Ollama, ProxyStack detects it (installed-but-not-running vs. actually running, not just "found or not") and can list, pull, and unload its models directly from the same view - no separate tool needed.

REST API v2.0 Reference

Enable the API from Security tab → "Enable REST API (port 9090)". 20 endpoints with CORS support, rate limiting (60 req/min), and API key authentication.

Endpoints

Authentication

For production use, enable API key authentication in the Production tab. Include the header X-API-Key: your-key with all requests.

Usage Examples

# PowerShell
Invoke-RestMethod -Uri "http://localhost:9090/api/status"
Invoke-RestMethod -Uri "http://localhost:9090/api/apache/restart" -Method POST

# curl
curl http://localhost:9090/api/health
curl -X POST http://localhost:9090/api/apache/restart

# Node.js
const res = await fetch('http://localhost:9090/api/status');
const status = await res.json();

Error Handling

All endpoints return JSON. Errors include an error field. HTTP status codes: 200 (success), 401 (unauthorized), 404 (not found), 500 (internal error).

Alerts & Notifications

Built-in alerts monitor the ProxyStack web server (Nginx/Apache) itself — no plugin required. For broader monitoring (individual sites, certificate expiry, daily summaries), see the Plugin Marketplace starter plugins below.

Supported Channels

What Triggers an Alert

• Server Started — sent when Nginx/Apache starts (or restarts) successfully
• Start/Restart Failed — sent if a Start or Restart attempt fails
• Unexpected Down — a 30-second health check detects the server process disappearing on its own (a crash). A deliberate Stop click is never reported as "down" — you already know you stopped it.

Cooldown

Default 5-minute cooldown prevents alert spam for flapping services. Settings changes take effect on the next check without restarting the app.

Test It

Click "Test Alert" in Settings to send a sample message to whichever channels you've configured, without waiting for a real event.

Plugin Marketplace

ProxyStack plugins are real scripts that run on lifecycle hooks — not just manifest entries. Browse and one-click install from the hosted marketplace, or install your own .zip package, in the Advanced tab. Requires Pro license to install.

How It Works

A plugin is a folder containing a plugin.json manifest and an entry script (.ps1, .py, .cmd/.bat, or .exe). The manifest declares which lifecycle events it runs on:

Each run gets a 20-second timeout and its output is appended to plugins/<slug>/plugin.log. One plugin failing or hanging never blocks another plugin or the app itself.

Starter Plugins (bundled, disabled by default)

Installing from the Marketplace

1. Go to Advanced tab → Plugins → Marketplace section → click Refresh
2. Select a plugin and click "Install Selected"
3. The package is downloaded and its SHA256 hash is verified against the catalog before anything is extracted — a mismatch aborts the install. The Marketplace list shows each catalog hash prefix and package size.
4. Enable it from the Installed list (new plugins install disabled by default) and use "View Log" to confirm it's running

Release verification uses scripts\test-plugin-marketplace.ps1 to confirm every catalog ZIP exists and matches its advertised size and SHA256 hash before publishing.

Installing Your Own Plugin

.zip is the real plugin format: it must contain plugin.json at its root, referencing an entry file that ProxyStack can execute. A standalone .dll can be imported too, but since it has no manifest and nothing to invoke it, it's stored under plugins/ for reference only and won't run automatically.

Plugin Storage

Each installed plugin lives in its own directory under plugins/, containing plugin.json, the entry script, and (once it has run at least once) plugin.log.

Cluster Management

The Cluster sidebar view enables multi-server management from a single dashboard. Requires Enterprise license.

Overview

Manage multiple ProxyStack instances (nodes) from one primary node. Each node runs its own REST API on port 9090, and the primary node pings remote nodes for health status.

Adding Nodes

1. Navigate to the Cluster view
2. Click "+ Add Node"
3. Enter the node name, API URL (e.g. http://192.168.1.100:9090), and role (secondary/standby/worker)
4. The node appears in the list and is pinged for health status

Node Roles

Health Checks

Click "Health Check All" to ping every node's /api/status endpoint. Results show Online/Offline status, web server state (Nginx/Apache), and version. Auto-refresh runs every 30 seconds.

Config Sync

1. Select a remote node in the list
2. Click "Sync Config →"
3. Your local proxystack.json is pushed to the remote node via POST /api/config/sync
4. The remote node creates a timestamped backup before applying the new config

Auto-Failover

Enable "Auto-Failover" to monitor nodes every 15 seconds. After 3 consecutive failures on a primary node, ProxyStack automatically promotes a standby node and notifies it via POST /api/cluster/promote.

Blue-Green Deploy

Zero-downtime config deployment in 4 steps:

1. Push current config to all standby/secondary nodes
2. Wait for nodes to apply config (5s)
3. Health check all standby nodes
4. If healthy: swap roles (standby → primary, primary → standby). If unhealthy: rollback with no changes.

Manual Node Promotion

Select any remote node and click "Promote" to make it the new primary. All current primaries are demoted to secondary. The promoted node is notified via its API.

Configuration File

Cluster nodes are stored in config/cluster-nodes.json:

{
  "clusterId": "MY-PC",
  "updatedAt": "2026-02-12T...",
  "nodes": [
    { "Id": "a1b2c3d4", "Name": "web-server-2", "Url": "http://192.168.1.100:9090", "Role": "secondary" }
  ]
}

Cloud Deployment

Deploy ProxyStack CLI to cloud servers (AWS EC2, DigitalOcean, etc.) and manage them from the GUI Cluster view.

Automated Setup (cloud-init)

Use the cloud-init script as EC2 User Data for fully automated provisioning:

#!/bin/bash
curl -sL https://proxystack.iamvcholdings.com/cloud/setup.sh | sudo bash

This installs Nginx, ProxyStack CLI, configures UFW firewall (ports 22/80/443/9090), and sets up systemd services.

Manual Setup

1. SSH into your server
2. Download and extract:

   curl -sL https://proxystack.iamvcholdings.com/downloads/proxystack-cli-v14.19.0-linux-x64.tar.gz -o proxystack.tar.gz
   sudo mkdir -p /opt/proxystack
   sudo tar xzf proxystack.tar.gz -C /opt/proxystack
   sudo chmod +x /opt/proxystack/proxystack
   sudo ln -sf /opt/proxystack/proxystack /usr/local/bin/proxystack

3. Start the API server for cluster health checks:

   sudo proxystack serve --port 9090

4. Set up as a systemd service for persistence:

   sudo tee /etc/systemd/system/proxystack-api.service <<EOF
   [Unit]
   Description=ProxyStack API Server
   After=network.target nginx.service
   
   [Service]
   Type=simple
   ExecStart=/opt/proxystack/proxystack serve --port 9090
   WorkingDirectory=/opt/proxystack
   Restart=always
   RestartSec=5
   
   [Install]
   WantedBy=multi-user.target
   EOF
   sudo systemctl daemon-reload
   sudo systemctl enable proxystack-api
   sudo systemctl start proxystack-api

5. Add the node in the GUI: Cluster → + Add Node → enter http://YOUR_IP:9090

CLI serve Command

The proxystack serve command starts a lightweight HTTP API server that responds to cluster health checks from the GUI:

CLI Cloud Commands

Updating the CLI on Remote Nodes

To update a remote node to the latest version:

# SSH into the node
ssh ubuntu@YOUR_IP

# Download the latest version
curl -sL https://proxystack.iamvcholdings.com/downloads/proxystack-cli-v14.19.0-linux-x64.tar.gz -o /tmp/proxystack-update.tar.gz

# Stop the API service, extract, restart
sudo systemctl stop proxystack-api
sudo tar xzf /tmp/proxystack-update.tar.gz -C /opt/proxystack --overwrite
sudo chmod +x /opt/proxystack/proxystack
sudo systemctl start proxystack-api

# Verify
proxystack --version
curl -s http://localhost:9090/api/health

The update preserves your proxystack.json config. The API server restarts automatically via systemd.

Team & Roles

The Team tab manages a list of named users, each with a free-text role (typically Administrator, User, or ReadOnly), stored in team.json.

Role Enforcement (v14.6.0+)

An "Acting as" dropdown selects which team member the app is currently acting on behalf of. Once a team is configured and an "Acting as" user is selected, destructive/admin actions require the Administrator role (case-insensitive): removing sites/apps, revealing secrets, deactivating a license, Docker lifecycle/removal/prune actions, managed import rollback, plugin install/enable/disable/remove, certificate generation/import/ACME requests, Zero Trust policy/zone removal, and automatic Process Reputation enforcement changes.

This is opt-in and backward-compatible: if no team is configured, or no "Acting as" user is selected, nothing is restricted — a single-user install is never locked out. Enforcement only begins once you explicitly set up team members and pick a non-admin "Acting as" user. No other actions in the app are currently role-gated.

Audit Log

Service start/stop and config-related actions taken through the Team tab itself are recorded with timestamp, user, and action. This is a local activity log, not a comprehensive audit trail of every action across the app.

GUI Views Overview

ProxyStack v14.11.0 has 22 sidebar views in the modern dark-themed GUI. Launch with --classic flag for the legacy tabbed interface.

Auto-Update System

ProxyStack includes a built-in update system that checks for new versions and applies updates while preserving your data.

Checking for Updates

1. Go to the Dashboard view
2. Click "Check for Updates"
3. ProxyStack fetches the update manifest from https://proxystack.iamvcholdings.com/api/updates/latest
4. If a newer version is available, the changelog and download button appear

Update Process

1. Click "Download & Install"
2. The update ZIP is downloaded with a progress bar
3. SHA256 hash is verified against the manifest to ensure integrity
4. ProxyStackUpdater.exe launches, waits for the GUI to exit
5. Updater backs up current binaries to _update_backup/
6. New files are extracted, preserving all user data
7. GUI restarts automatically

Preserved During Updates

The following files and folders are never overwritten:

• proxystack.json, proxystack.settings.json, team.json, plugins.json
• certs/, logs/, backups/, profiles/, sites/
• config/ (secrets, zero-trust settings, WAF rules)
• postgres/data/ (database data)

Rollback

If the update fails, the updater automatically restores from _update_backup/. You can also manually restore by copying the backup files back.

Network Resilience

The update checker accepts self-signed SSL certificates and falls back to HTTP if HTTPS fails, ensuring connectivity even behind corporate proxies or firewalls.

File Locations

Troubleshooting

Apache won't start

• Check port conflict: netstat -ano | findstr :80
• Click "Validate" to check configuration
• Review logs/error.log
• Verify all certificate paths exist

Apache won't stop

• Run ProxyStackGUI.exe as Administrator
• Manual kill: taskkill /F /IM httpd.exe

Let's Encrypt fails

• Verify DNS points to this server: nslookup yourdomain.com
• Ensure port 80 is open in Windows Firewall
• Check for rate limiting (wait 1 hour)
• ProxyStack auto-stops Apache during validation; ensure no other process holds port 80

Docker not found

• Start Docker Desktop and wait 30-60 seconds
• Verify: docker --version and docker ps

PostgreSQL won't start

• Check port 5432: netstat -ano | findstr :5432
• Verify postgres/pgsql/bin/pg_ctl.exe exists
• Check postgres/data/log/ for errors

REST API not responding

• Ensure GUI is running with API enabled (Security tab)
• Check port 9090 is not blocked
• Test: curl http://localhost:9090/api/status

Logs Location

• Apache access log: logs/access.log
• Apache error log: logs/error.log
• Per-site logs: logs/{domain}-access.log, logs/{domain}-error.log
• PostgreSQL: postgres/data/log/