Configuration¶

# Operating mode: "relay", "server", or "client".
# Determines which commands are available and which services start.
# The legacy value "admin" is accepted on read and rewritten to "relay".
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 all modes).
xray:
  # Profile identity UUID (VLESS client id). On a server/relay it also derives
  # the server-id (<hostname>-<first 8 hex of uuid>); on a client it is the
  # per-user UUID issued at user creation.
  uuid: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

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

  # HTTPS port on the relay.
  relay_port: 443

  # XHTTP path used by Xray. Default /tw; rewritten to /tw/<server-id> when a
  # relay is provisioned or an invite is granted (tw relay create / tw join).
  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 settings (used in server mode; the relay_ssh_* / remote_port fields
# are also used in relay mode for the relay SSH connection, and api_port is
# read in every mode to find a running daemon).
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

  # Interface the web dashboard binds. Defaults to 127.0.0.1 (local only).
  # The dashboard requires a login token (see `tw dashboard token`), but it is
  # served over cleartext HTTP, so an off-loopback bind is REFUSED unless
  # dashboard_allow_lan is also set. Also settable per run with
  # `tw dashboard --listen`.
  dashboard_listen: 127.0.0.1

  # Explicit opt-in to bind the dashboard off-loopback over cleartext. Only set
  # this behind a TLS terminator on a trusted network — the bearer token and
  # session cookie travel unencrypted otherwise.
  dashboard_allow_lan: false

  # 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/relay 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

  # Client-owned local-port overrides, keyed by server port (remote_port).
  # Set with `tw client set-port`; omitted when empty. Wins over the
  # tunnel's local_port; `tw client connect --map` wins over both for one run.
  port_overrides:
    3389: 13389

# Tamper-evidence signature over (mode, profile identity). Written by
# enrollment / bundle export / relay self-signing — never by hand.
mode_auth:
  sig: "base64-ed25519-signature"
  issuer: "base64-ed25519-public-key"

current-context: hetzner-relay
contexts:
  hetzner-relay:
    role: relay          # relay | server | client
    relay: relay.example.com
    id: 3f2a9c1b         # short ID of the profile's xray.uuid
    created: "2026-07-01T10:00:00Z"
  alice:
    role: client
    relay: relay.example.com
    user: alice          # client contexts only: client.ssh_user
    id: 9b1e4d02
    created: "2026-07-02T09:30:00Z"