Proxmox

How to enable?

Add a proxmox section to /config/tsdproxy.yaml. Each entry is one target provider connected to a Proxmox VE API endpoint, authenticated with an API token:

proxmox:
  pve:
    url: https://pve.example.com:8006
    apiToken: tsdproxy@pve!tsdproxy=e14b8a0c-1111-4bbb-9ccc-2222dddd3333
    tlsCaCertFile: /config/proxmox/pve-root-ca.pem
    defaultProxyProvider: default

The token can also be loaded from a file — useful to keep secrets out of the config file:

proxmox:
  pve:
    url: https://pve.example.com:8006
    apiTokenFile: /config/proxmox/token

Creating an API token

TSDProxy authenticates with a Proxmox API token in the format <user>@<realm>!<tokenid>=<secret>. It only needs read access to cluster resources, guest configs and the QEMU guest agent interface API.

pveum user add tsdproxy@pve --comment "TSDProxy"
pveum acl modify / --users tsdproxy@pve --roles PVEAuditor

pveum user token add tsdproxy@pve tsdproxy -privsep 0

tsdproxy@pve!tsdproxy=<printed-value>

scp root@pve.example.com:/etc/pve/pve-root-ca.pem /config/proxmox/pve-root-ca.pem

curl -k -H "Authorization: PVEAPIToken=tsdproxy@pve!tsdproxy=<value>" \
  https://pve.example.com:8006/api2/json/version

Enable a guest

Edit the guest’s notes (VMs) or description (containers) in the Proxmox web UI and add a tsdproxy: YAML block. A guest is enabled as soon as the block carries any data — an explicit enable: false opts out.

Two styles are accepted and can be mixed:

# Docker/Incus style — flat keys, port label grammar
tsdproxy:
  port:
    443: 443/https:8080/http
  dash.icon: jellyfin

# list provider style — same keys as a lists file entry
tsdproxy:
  hostname: myapp
  ports:
    "443/https":
      targets:
        - "http://10.0.0.5:8080"
      tailscale:
        funnel: true

The guest becomes available at https://<hostname>.<tailnet-name>.ts.net. The hostname defaults to the guest name; VMs and containers behave identically.

Flat config keys

Flat keys use the tsdproxy. prefix and mirror the Docker labels semantics:

List provider style

Entries inside the tsdproxy: block accept the same keys as a lists provider file: hostname, proxyProvider, domain, dnsProvider, tlsProvider, identityHeaders, dashboard, tailscale and ports with per-port targets, tlsValidate, isRedirect and tailscale.funnel.

When a port entry has no targets, the target URL is generated from the guest address (see below) instead of an explicit URL — the list format without hardcoded IPs:

tsdproxy:
  ports:
    "443/https": {}          # → http(s)://<guest-address>:443
    "8080/tcp:9090/tcp": {}  # → tcp://<guest-address>:9090

Flat keys are canonical: when both styles set the same field, the flat key wins.

Port options no_tlsvalidate and tailscale_funnel (or the list-style tlsValidate: false and funnel: true) require the provider options allowTlsValidateDisable and allowGuestFunnel respectively, matching the Docker provider’s security defaults.

Target resolution

1. targetHostname from the provider config with the port’s target port, if set
2. Otherwise the guest’s first usable address:
   • LXC containers — addresses from the Proxmox interfaces API
   • QEMU VMs — addresses reported by the QEMU guest agent via network-get-interfaces; the agent must be installed in the guest OS and enabled in the VM options (agent: 1)

VMs without a running guest agent resolve no addresses — set targetHostname or use explicit list-style targets for them.

Live updates

Guest notes are re-read on every poll. Changing tsdproxy data restarts the proxy automatically — only the tsdproxy block is compared, so editing unrelated notes never restarts proxies. Stopping, starting, deleting or disabling a guest tears the proxy down on the next poll.

Provider options