Configuration

Every CompassVPN setting lives in a single file: env_file, in the folder where you cloned the agent. Copy env_file.example to env_file, fill in your values, and run sudo ./agent.sh start to apply them.

You only need to fill in a few values to get started; everything else has a sensible default. Use this page as a reference when you want to understand or change a setting.

Complete Configuration File

Below is the complete example of the env_file with all available settings:

# Where metrics get shipped: the Grafana remote-write endpoint and its basic-auth
# credentials, from your monitoring setup (e.g. Grafana Cloud).
ALLOY_REMOTE_WRITE_URL=
ALLOY_REMOTE_WRITE_USER=
ALLOY_REMOTE_WRITE_PASSWORD=

# Name of the donor - shows up as a label on every metric.
DONOR=compass

# How often to re-deploy (which also renews TLS certs), e.g. 10d or 1m. Empty = never.
REDEPLOY_INTERVAL=

# Cloudflare API token + the zone ID of your domain - used to manage DNS records and
# pass the TLS cert challenge. CF_CLEAN_IP_DOMAIN is a clean (unblocked) domain to front
# CDN inbounds with.
CF_API_TOKEN=
CF_ZONE_ID=
CF_CLEAN_IP_DOMAIN=

# Egress mode: "direct", or "warp" to route out through a WireGuard/WARP tunnel.
XRAY_OUTBOUND=direct

# Inbounds to enable (comma-separated). Append :<count> for replicas via path-based
# routing, e.g. vless-hu-tls-cdn:3
XRAY_INBOUNDS=vless-hu-direct,vless-hu-cdn,vless-tcp-tls-direct,vless-tcp-reality-direct,vless-xhttp-reality-direct,vless-hu-tls-direct,vless-hu-tls-cdn,vless-xhttp-quic-direct,vless-xhttp-quic-cdn,vless-xhttp-direct,vless-xhttp-cdn

# TLS certificate authority: "letsencrypt" or "zerossl".
SSL_PROVIDER=letsencrypt

# Check for updates hourly and apply them automatically. Use on/off.
AUTO_UPDATE=off

# The secret URL path that carries real proxy traffic - everything else hits the decoy.
NGINX_PATH=compass

# The decoy website shown to anyone who isn't a real client, also used to
# disguise the reality inbound.
FAKE_WEBSITE=www.divar.ir

# DNS resolver for outbound lookups: "default", "cf", "controld", a full
# https+local:// (DoH) / quic+local:// (DoQ) / tls+local:// (DoT) URL,
# or a plain IPv4 address (UDP).
CUSTOM_DNS=controld

# true = verbose logging across all containers, plus xray DNS-query logging and
# a debug.log file. Use true/false.
DEBUG=false

Detailed Parameter Explanations

Below is a comprehensive breakdown of each configuration parameter in the env_file:

ALLOY_REMOTE_WRITE_URL

Example: https://prometheus-prod-XXX-grafana.grafana.net/api/prom/push
Description: The Prometheus remote-write endpoint where metrics are shipped via Grafana Alloy. This can be a Grafana Cloud endpoint or your own self-hosted Prometheus instance.

ALLOY_REMOTE_WRITE_USER

Example: XXX
Description: Username for authenticating with the remote-write endpoint.

ALLOY_REMOTE_WRITE_PASSWORD

Example: glc_XXX
Description: Password (or API key) for authenticating with the remote-write endpoint.

DONOR

Example: your_identifier
Default: compass
Description: An identifier used as a label in all metrics. This helps identify this specific server instance in your monitoring system.

REDEPLOY_INTERVAL

Example: 10d (10 days)
Format: 1d (1 day), 14d (14 days), 1m (1 month)
Default: (empty, meaning never)
Description: How often CompassVPN re-deploys itself, which regenerates the configuration identifiers and renews TLS certificates. Leave it empty to disable scheduled re-deploys. This helps maintain the security and freshness of the configuration.

CF_API_TOKEN

Example: YOUR_CF_API_TOKEN
Description: Authentication token for Cloudflare API access. This token is required to manage DNS records and SSL certificates through Cloudflare’s API when using CDN-proxied configurations.

To create this token:

1. Log in to your Cloudflare dashboard
2. Select your domain
3. Navigate to My Profile > API Tokens
4. Click Create Token > Create Custom Token
5. Set a descriptive name (e.g., “CompassVPN”)
6. Add these permissions:
   • Zone - DNS - Edit
   • Zone - SSL and Certificates - Edit
7. Under Zone Resources, select:
   • Include - Specific zone - [your-domain.com]
8. Set expiration time (optional)
9. Create token and copy the value

CF_ZONE_ID

Example: YOUR_CF_ZONE_ID
Description: Cloudflare zone identifier for your domain. This unique identifier is required for managing your domain’s DNS and SSL settings through Cloudflare’s API when using CDN-proxied configurations.

To find your Zone ID:

1. Log in to your Cloudflare dashboard
2. Select your domain
3. Scroll down on the overview page
4. Look for Zone ID in the right sidebar
5. Copy the value for your CompassVPN configuration

CF_CLEAN_IP_DOMAIN

Example: npmjs.com or 104.17.223.1
Default: (empty in env_file.example; the agent falls back to npmjs.com when unset)
Description: A clean (unblocked) domain or IP address used to front CDN inbounds when CDN configurations are enabled. This must be either a domain behind Cloudflare CDN or a Cloudflare IP address to ensure accurate testing.

XRAY_OUTBOUND

Value options: direct or warp
Default: direct
Description: How outbound connections are routed. Choose between direct connections or routing through Cloudflare WARP.

XRAY_INBOUNDS

Example: vless-tcp-tls-direct,vless-hu-tls-cdn
Default: all eleven inbounds enabled (see the sample env_file above)
Description: Comma-separated list of the inbound configurations you want to enable, chosen from the available types below. All inbounds use the VLESS protocol.

Available Inbound Types:

• Direct Connections:
  • vless-tcp-tls-direct: VLESS over TCP with TLS 1.3 and XTLS Vision flow (port 443)
  • vless-tcp-reality-direct: VLESS over TCP with REALITY and XTLS Vision flow (port 2083)
  • vless-xhttp-reality-direct: VLESS over XHTTP with REALITY (port 2087)
  • vless-hu-tls-direct: VLESS over HTTPUpgrade with TLS (port 2053)
  • vless-hu-direct: VLESS over HTTPUpgrade without TLS, secured by VLESS Encryption (port 8080)
  • vless-xhttp-quic-direct: VLESS over XHTTP with QUIC / HTTP3 (port 8443)
  • vless-xhttp-direct: VLESS over XHTTP without TLS (port 8880)
• CDN-Proxied Connections: (Route traffic via Cloudflare CDN)
  • vless-hu-tls-cdn: VLESS over HTTPUpgrade with TLS (port 2053)
  • vless-hu-cdn: VLESS over HTTPUpgrade without TLS, secured by VLESS Encryption (port 8080)
  • vless-xhttp-quic-cdn: VLESS over XHTTP with QUIC / HTTP3 (port 8443)
  • vless-xhttp-cdn: VLESS over XHTTP without TLS (port 8880)

Per-Inbound Replicas: Append :<count> to any inbound name to run multiple instances of it behind path-based routing (e.g., vless-hu-tls-cdn:3 creates three replicas). This is useful for spreading load or rotating endpoints. Note that vless-tcp-tls-direct, vless-tcp-reality-direct, and vless-xhttp-reality-direct bind a port directly with no HTTP path and therefore cannot be replicated (their count is always 1).

SSL_PROVIDER

Value options: letsencrypt or zerossl
Default: letsencrypt
Description: Which SSL certificate provider to use for securing connections. This setting determines which Certificate Authority (CA) will issue your SSL certificates.

AUTO_UPDATE

Value options: on or off
Default: off
Description: Controls whether the agent automatically updates itself. When enabled, a cron job checks hourly for new code and re-converges the server when an update is available, preserving your existing configuration.

NGINX_PATH

Example: example_path
Default: compass
Description: The URL path used in NGINX’s internal routing system. This path is used by NGINX to properly route traffic to the VPN service and must be set to a valid value. The specific value doesn’t affect security or visibility to firewalls and DPIs, as it’s only used internally by NGINX for routing purposes.

FAKE_WEBSITE

Example: www.example.com
Default: www.divar.ir
Description: The decoy website shown to anyone who isn’t a real VPN client. When someone visits your domain, they will see content from this website instead of the VPN service, which helps maintain a low profile and avoid detection. It is also used as the SNI/target to disguise the REALITY inbounds (vless-tcp-reality-direct, vless-xhttp-reality-direct), so it must be a real TLS 1.3 website.

CUSTOM_DNS

Value options: default, cf, controld, a custom https+local:// / quic+local:// / tls+local:// URL, or a plain IPv4 address
Default: controld (as shipped in env_file.example; if the variable is removed entirely, the agent falls back to default)
Description: DNS resolver Xray uses for outbound lookups. This setting determines how your server resolves domain names, affecting both security and performance.

DEBUG

Value options: true or false (case-insensitive)
Default: false
Description: Whether to enable debug logging mode. With DEBUG=false, every container logs at the WARN level for a quiet production baseline. Setting DEBUG=true turns on verbose logging across the whole stack, enables Xray DNS-query logging, and writes a debug.log file, which is useful for troubleshooting connection issues or diagnosing problems.

Auto-Generated and Optional Variables

These variables are not part of env_file.example, but you may encounter them:

IDENTIFIER

Description: A stable 10-character node ID, generated automatically on the first run and appended to your env_file. It labels this node’s metrics and is used to derive the REALITY and VLESS Encryption keys, so the configuration links survive re-deploys.

SERVER_IP

Description: Optional override for the server’s public IP address. If unset, the agent auto-detects it via a public IP lookup. Set it only when auto-detection picks the wrong address (e.g., on multi-homed servers).

Applying Configuration Changes

After editing your env_file, apply the changes by re-running:

sudo ./agent.sh start

This command is idempotent and safe to run as often as you like. It re-converges the server with your updated configuration.

Next, proceed to the Monitoring guide to configure monitoring for your CompassVPN installation.