Configuration

Complete reference for all Octoporty configuration options.

Gateway Configuration

Environment variables for the Gateway service deployed on your cloud server.

Variable	Required	Default	Description
`Gateway__ApiKey`	Yes	`-`	Pre-shared key for Agent authentication. Must be at least 32 characters. Use a strong, randomly generated value.
`Gateway__CaddyAdminUrl`	No	`http://localhost:2019`	URL to the Caddy Admin API. Used to dynamically configure routes.
`Gateway__Port`	No	`17200`	Port the Gateway listens on for WebSocket connections from Agents.
`Gateway__AllowedOrigins`	No	`*`	Comma-separated list of allowed CORS origins. Set to specific domains in production.
`Gateway__RemoveRoutesOnTunnelUnavailable`	No	`false`	Remove Caddy routes when the tunnel is unavailable. Disabled by default to avoid Caddy reloads dropping long-lived connections (e.g., when the Agent tunnels through Caddy).

Agent Configuration

Environment variables for the Agent service deployed in your private network.

Variable	Required	Default	Description
`Agent__GatewayFqdn`	No	`-`	Gateway domain (e.g., gateway.example.com). Recommended over GatewayUrl. Automatically derives the WebSocket URL and sends FQDN to Gateway for landing page routing.
`Agent__GatewayUrl`	No	`Derived from GatewayFqdn`	WebSocket URL to the Gateway. If not set, derived from GatewayFqdn as wss://{GatewayFqdn}/tunnel.
`Agent__ApiKey`	Yes	`-`	Pre-shared key matching the Gateway's ApiKey. Must be identical on both sides.
`Agent__JwtSecret`	Yes	`-`	Secret key for signing JWT tokens. Must be at least 32 characters.
`Agent__Auth__PasswordHash`	Yes	`-`	SHA-512 crypt hash for web UI login. Generate with: openssl passwd -6 "your-password"
`Agent__Port`	No	`17201`	Port the Agent web UI listens on.
`ConnectionStrings__DefaultConnection`	No	`SQLite`	Database connection string. Defaults to SQLite file storage.
`Agent__HeartbeatIntervalSeconds`	No	`30`	Interval between heartbeat messages to keep the tunnel alive.
`Agent__ReconnectDelaySeconds`	No	`5`	Initial delay before attempting reconnection after disconnect.
`Agent__MaxReconnectDelaySeconds`	No	`300`	Maximum delay between reconnection attempts (exponential backoff cap).
`Logging__FilePath`	No	`/var/log/octoporty/agent-.log`	Rolling log file path. Required for the Agent Logs UI. The directory must be writable by the container.

Port Assignments

Octoporty uses the 17200-17299 port range by default. All ports are configurable.

Port	Service	Description
`17200`	Gateway	WebSocket endpoint for Agent connections
`17201`	Agent Web UI	Management interface for port mappings
`17202`	Caddy Admin	Caddy Admin API (internal)
`17280`	Caddy HTTP	HTTP ingress (redirects to HTTPS)
`17243`	Caddy HTTPS	HTTPS ingress for tunneled services

Environment File Example

Complete .env file template with all configuration options.

 .env # Gateway Configuration
GATEWAY_API_KEY=your-secure-api-key-at-least-32-characters-long

# Agent Configuration
AGENT_GATEWAY_FQDN=gateway.yourdomain.com
AGENT_API_KEY=your-secure-api-key-at-least-32-characters-long
AGENT_JWT_SECRET=your-jwt-secret-at-least-32-characters-long
# Generate password hash with: openssl passwd -6 "your-password"
AGENT_AUTH_PASSWORD_HASH=$6$rounds=5000$yoursalt$yourhash

# Optional: Custom database path
# CONNECTION_STRING=Data Source=/custom/path/octoporty.db

Caddy Configuration

Example Caddyfile for the Gateway server. Caddy automatically provisions TLS certificates.

 Caddyfile {
    admin :2019
}

# Gateway WebSocket endpoint
gateway.yourdomain.com {
    reverse_proxy gateway:17200
}

# Tunneled services (managed dynamically by Gateway)
*.tunnel.yourdomain.com {
    reverse_proxy gateway:17200
}

Note: The Gateway automatically manages Caddy routes via the Admin API when you create port mappings in the web UI. The wildcard domain configuration above is for initial setup.

Database Configuration

The Agent uses SQLite for lightweight local storage. No external database is required.

Default Location

No configuration needed. Data is stored in /app/data/octoporty.db inside the container. Mount a volume to /app/data to persist data across container restarts.

Container Permissions

The /app/data directory is created at runtime and inherits the container's UID. Ensure the container runs as a user with write access to the mounted volume:

Docker Compose: Add user: "1000:1000" to match your host user, or run sudo chown -R 1000:1000 /path/to/data
TrueNAS SCALE: Set Security Context User ID to 568 (the apps user) and ensure your dataset is owned by apps (568:568)
Other NAS platforms: Run the container as a user with write access to the data directory

Custom Path

 .env # Custom SQLite database path
ConnectionStrings__DefaultConnection=Data Source=/custom/path/octoporty.db

Security Best Practices

Follow these guidelines to secure your Octoporty deployment.

Use Strong API Keys

Generate API keys with at least 32 characters using a cryptographically secure random generator: openssl rand -base64 32

Always Use HTTPS

Configure the Gateway URL with wss:// (WebSocket Secure) in production. Never use unencrypted ws:// connections over the internet.

Restrict Agent Access

The Agent web UI should only be accessible from your internal network. Do not expose port 17201 to the public internet.

Rotate Credentials

Periodically rotate API keys and passwords. Update both Gateway and Agent simultaneously to avoid connection issues.

Monitor Logs

Review request logs regularly for suspicious activity. The Agent web UI provides an audit trail of all tunneled requests.