Configuration

Configure Octoprox using environment variables and YAML configuration files.

Overview

Configuration is loaded from YAML files in the config/ directory based on the OCTOPROX_ENV environment variable. Environment variables take precedence over YAML configuration.

Environment Variables

Authentication

Octoprox requires authentication for all web UI and API access. On first startup, an admin user is automatically created from OCTOPROX_AUTH_USERNAME and OCTOPROX_AUTH_PASSWORD.

There are three roles:

• Admin - Full access including user management
• Editor - Can manage projects, proxies, credentials, and connectors (no user management)
• Viewer - Read-only access to all data

Besides a password, a user can sign in with a Google, Microsoft or GitHub account once an admin has set the provider up, and scripts can authenticate with a personal access token instead of a password. See Single Sign-On and API Tokens.

Configuration

Set the following environment variables:

export OCTOPROX_AUTH_USERNAME=admin
export OCTOPROX_AUTH_PASSWORD=your-secure-password
export OCTOPROX_JWT_SECRET=your-random-secret-key

Or create a .env file in the project root:

OCTOPROX_AUTH_USERNAME=admin
OCTOPROX_AUTH_PASSWORD=your-secure-password
OCTOPROX_JWT_SECRET=your-random-secret-key

Security Notes

• Always set a strong OCTOPROX_JWT_SECRET in production. The default value is insecure.
• Never commit credentials to version control. Use environment variables or .env files (which should be gitignored).
• The /api/v1/auth/login and /api/v1/auth/status endpoints are always public, as are the /api/v1/auth/sso/* endpoints the browser’s sign-in round trip uses.
• The /health endpoint is always public for load balancer health checks.
• All other API endpoints require authentication.

YAML Configuration

Example Configuration File

Create a configuration file at config/development.yaml or config/production.yaml:

server:
  host: "0.0.0.0"
  api_port: 8000
  proxy_port: 8080

proxy:
  default_strategy: round_robin
  health_check:
    enabled: true
    interval_seconds: 60
    timeout_seconds: 30

tls_mitm:
  ca_cert_path: "data/ca/octoprox-ca.crt"
  ca_key_path: "data/ca/octoprox-ca.key"

Server Configuration

Proxy Configuration

The proxy.geo_lookup endpoint seeds the echo endpoint of the IP attribution policy on a fresh install; once an admin saves the policy in the UI, the policy’s echo_url is what is used.

IP Attribution

The install-wide settings (default conflict rule and city radius, echo endpoint, preflight, retention) are edited in Settings → IP attribution and stored in the database; projects may override the conflict rule and the city radius. The config file describes this process and seeds a fresh install:

Connector config keys read by the health checker: healthcheck_url (custom check URL; without it the attribution echo endpoint is checked), healthcheck_ip_path (JMESPath, or @text, of the exit IP in that URL’s response; unset means the response carries no IP unless the URL is the echo or httpbin endpoint) and healthcheck_country_path.

WireGuard

tunnel:                    # the data plane every tunnel protocol shares
  transparent_port: 8081   # tunnel TCP is redirected here (bound on the tunnel gateway addresses)
  dns_port: 5353           # tunnel DNS is redirected here
  fake_ip_range: 198.18.0.0/15
  sniff_timeout_seconds: 2
  block_encrypted_dns: true  # close DoT and known DoH resolvers so devices keep the tunnel resolver

wireguard:
  enabled: false           # terminate the tunnel on this instance (CAP_NET_ADMIN, wireguard-tools, nftables)
  interface: wg0
  # listen_port: 51820     # only when it differs from the install's endpoint port
  mtu: 1420
  defaults:                # seeds the install-wide row on a fresh install
    endpoint_host: vpn.example.com
    endpoint_port: 51820
    subnet: 10.66.0.0/16

Environment variables: OCTOPROX_TUNNEL_TRANSPARENT_PORT, OCTOPROX_TUNNEL_DNS_PORT, OCTOPROX_TUNNEL_FAKE_IP_RANGE, OCTOPROX_TUNNEL_SNIFF_TIMEOUT_SECONDS, OCTOPROX_TUNNEL_BLOCK_ENCRYPTED_DNS, OCTOPROX_WIREGUARD_ENABLED, OCTOPROX_WIREGUARD_INTERFACE, OCTOPROX_WIREGUARD_LISTEN_PORT, OCTOPROX_WIREGUARD_MTU.

The key pair, public endpoint and tunnel subnet are install-wide, stored in Postgres and edited under Settings → WireGuard. See WireGuard Devices for what each setting does and what the terminating instance needs.

OpenVPN

openvpn:
  enabled: false           # run the daemon on this instance (CAP_NET_ADMIN, /dev/net/tun, openvpn, nftables)
  interface: ovpn0
  # listen_port: 1194      # only when it differs from the install's endpoint port
  mtu: 1500                # tun-mtu of the daemon's interface
  defaults:                # seeds the install-wide row on a fresh install
    endpoint_host: vpn.example.com
    endpoint_port: 1194
    protocol: udp          # or tcp
    subnet: 10.67.0.0/16

Environment variables: OCTOPROX_OPENVPN_ENABLED, OCTOPROX_OPENVPN_INTERFACE, OCTOPROX_OPENVPN_LISTEN_PORT, OCTOPROX_OPENVPN_MTU.

The CA, server certificate, public endpoint, transport and subnet are install-wide, stored in Postgres and edited under Settings → OpenVPN. The tunnel: block above is shared with WireGuard. See OpenVPN Devices.

Logging

logging:
  level: INFO
  format: json

Application, uvicorn and SQLAlchemy log lines all render through the same formatter, so a log shipper sees one shape. Use json in production and console in development.

Every line carries an instance field holding OCTOPROX_INSTANCE_ID, so the output of several replicas can be collected in one place and still be told apart. Set a stable, human-readable value per replica as the cluster compose file does; the default is a random UUID per boot.

Request IDs

Every API request gets a request ID. The API accepts one from the caller in the X-Request-ID header (up to 128 characters of letters, digits, ., _, : and -) and generates one otherwise. The ID used is always returned in the X-Request-ID response header, including on error responses.

While a request is being handled, every log line carries request_id, and once the bearer token is verified, user_id and username as well. A user report of a failed action can therefore be matched to the server logs by the ID shown in the response, and log lines can be filtered to one person without any per-call-site plumbing.

The web UI sends its own ID on every call, so browser-side failures are traceable the same way.

Host Metrics

Every request is counted against the destination host it was for, under the connector that carried it, for the project’s Hosts page (see Metrics). Every host is kept by default. It is the one history table whose size depends on what clients request rather than on how the pool is set up, so an install that crawls the open web has two dials:

metrics:
  hosts:
    enabled: true   # false records nothing per host; the Hosts page then stays empty
    max_hosts: 0    # 0 keeps every host; N names the N busiest per project per 5-second window

A ceiling is for pools that crawl: a project that touches a million new domains a day writes a row per domain, and the Hosts page then has to aggregate tens of millions of rows per load. For a pool aimed at a few to a few thousand target sites the table stays small with no ceiling at all.

Both can also be set as OCTOPROX_HOST_METRICS_ENABLED and OCTOPROX_HOST_METRICS_MAX_HOSTS. Rows follow the project’s metrics retention and the same compaction tiers as the other history tables.

Failure Log

Why requests failed or were refused, per project, for the Failures page (see Metrics). Every failure is counted into the failure_metrics history table, which follows the project’s metrics retention and compaction like the other history tables. Examples of failures are kept in Redis, one capped stream per project and kind; identical failures within a 5-second window are folded into one example with a count.

failure_log:
  enabled: true
  max_entries: 1000      # examples per project and kind, newest kept
  retention_hours: 168
  max_per_window: 100    # distinct examples per project and kind per 5-second window, per instance

An example is a few hundred bytes, so a kind that fills its stream at the default takes a few hundred kilobytes of Redis, and a project takes that for each kind it actually sees. Lower max_entries on an install with many projects: the counts stay complete whatever it is set to. The settings can also be set as OCTOPROX_FAILURE_LOG_ENABLED, OCTOPROX_FAILURE_LOG_MAX_ENTRIES, OCTOPROX_FAILURE_LOG_RETENTION_HOURS and OCTOPROX_FAILURE_LOG_MAX_PER_WINDOW.

Database Configuration

Octoprox uses PostgreSQL for persistent storage:

Redis Configuration

Redis is used for session storage and caching:

Production Recommendations

1. Set strong secrets: Always use secure, random values for OCTOPROX_JWT_SECRET and OCTOPROX_AUTH_PASSWORD.

2. Use environment variables: Don’t hardcode sensitive values in configuration files.

3. Set a strong admin password: Use a secure value for OCTOPROX_AUTH_PASSWORD.

4. Use HTTPS: Deploy behind a reverse proxy (nginx, Caddy) with TLS termination.

5. Monitor health: Use the /health endpoint for load balancer health checks.