Configuration¶

# Operating mode: "server" or "client".
# Determines which commands are available and which services start.
mode: server

# Log verbosity: debug, info, warn, error.
# Can also be set with --log-level flag (persisted on use).
log_level: info

# Log output format: "text" (default, human-readable) or "json".
# JSON maps attributes to OpenTelemetry semantic-convention names.
# Can also be set with --log-format flag (persisted on use).
log_format: text

# Outbound proxy for all connections (Xray, SSH, Terraform).
# Supported formats:
#   socks5://host:port
#   socks5://user:pass@host:port
#   http://host:port
#   http://user:pass@host:port
# Leave empty for direct connections.
proxy: ""

# Shared transport layer (used by both server and client).
xray:
  # Xray client UUID — unique per user, generated during user creation.
  uuid: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

  # Domain or IP of the relay server.
  relay_host: relay.example.com

  # Port for the HTTPS/WebSocket connection to the relay.
  relay_port: 443

  # WebSocket path used by Xray.
  path: /tw

  # X.509 client certificate presented to the relay's mutual-TLS gate.
  # Auto-populated at runtime from <config-dir>/client.{crt,key} when present,
  # so you normally leave these empty. See Security → Relay Authentication.
  client_cert_path: ""
  client_key_path: ""

# Server-only settings (ignored in client mode).
server:
  # Port the internal SSH server listens on.
  ssh_port: 2222

  # Port the gRPC API listens on (CLI-to-daemon communication).
  api_port: 50051

  # Port the web dashboard listens on.
  dashboard_port: 8080

  # SSH port on the relay server (for the reverse tunnel).
  relay_ssh_port: 22

  # SSH user on the relay server.
  relay_ssh_user: ubuntu

  # Remote port on the relay that maps back to the local SSH port.
  remote_port: 2222

  # Local port the embedded Xray instance listens on. Optional; leave 0
  # to use the built-in default.
  xray_port: 0

  # Port used for temporary Xray tunnel during relay config updates
  # (user creation, user registration). Change if 59000 is in use.
  temp_xray_port: 59000

  # Application templates — reusable port mapping bundles.
  # Used when creating or editing users to pre-fill port mappings.
  applications:
    - name: "web-app"
      mappings:
        - { client_port: 3000, server_port: 3000 }
        - { client_port: 5432, server_port: 5432 }

# Bandwidth analytics (opt-in, works in both modes).
analytics:
  enabled: true
  history_size: 720  # snapshots to keep (default 720 = 1h at 5s intervals)

# Client-only settings (ignored in server mode).
client:
  # SSH user to authenticate as on the server.
  ssh_user: tunnel

  # SSH port on the server (matches server.ssh_port via the tunnel).
  server_ssh_port: 2222

  # Local port the embedded Xray dokodemo-door listens on (default 54001).
  xray_port: 54001

  # Local interface forwarded tunnels bind to.
  # 127.0.0.1 = local only (default); 0.0.0.0 = all interfaces (required
  # when running tw inside a container that publishes ports to the host).
  listen_address: 127.0.0.1

  # Port forwarding rules — each entry creates a local listener.
  tunnels:
    - local_port: 3389
      remote_host: 127.0.0.1
      remote_port: 3389
    - local_port: 8443
      remote_host: 127.0.0.1
      remote_port: 443