Incus

How to enable?

Add an incus section to /config/tsdproxy.yaml. Each entry is one target provider connected to an Incus daemon and project:

incus:
  local:
    # Local unix socket. Leave empty to auto-detect
    # (/run/incus/unix.socket or /var/lib/incus/unix.socket).
    socket: /var/lib/incus/unix.socket
    project: default
    defaultProxyProvider: default

For a remote Incus daemon over HTTPS:

incus:
  remote:
    url: https://incus.example.com:8443
    tlsClientCertFile: /config/incus/client.crt
    tlsClientKeyFile: /config/incus/client.key
    tlsServerCertFile: /config/incus/server.crt # optional, trust the remote CA
    project: production

Connecting to a remote Incus

The Incus API uses mutual TLS: tsdproxy needs a client certificate trusted by the remote server (for authentication) and the server certificate (to verify the server, since Incus self-signs by default). Here is how to get both.

incus config set core.https_address :8443

incus config trust add tsdproxy --restricted --projects production

incus remote add tsdproxy-remote <paste-token>

openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes \
  -keyout client.key -out client.crt -subj "/CN=tsdproxy"

incus config trust add-certificate client.crt

incus list tsdproxy-remote: --project production

When TSDProxy runs inside a Docker container on the same host as Incus, mount the Incus socket and set targetHostname to a host reachable from the container:

incus:
  local:
    socket: /var/lib/incus/unix.socket
    targetHostname: host.docker.internal

Enable an instance

Set user.tsdproxy.enable=true on any Incus instance:

incus config set myapp user.tsdproxy.enable=true
incus config set myapp user.tsdproxy.port.1=443/https:80/http

The instance becomes available at https://myapp.<tailnet-name>.ts.net. Virtual machines work identically — VM state addresses are used the same way as container addresses.

Config keys

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

Port options no_tlsvalidate and tailscale_funnel require the provider options allowTlsValidateDisable and allowInstanceFunnel respectively, matching the Docker provider’s security defaults.

Target resolution

Incus has no published ports, so the target is resolved as:

1. targetHostname from the provider config with the port’s target port, if set
2. The instance’s first global IPv4 address (IPv6 fallback) from the instance state — eth0 preferred

After an instance starts, TSDProxy polls its state for up to 10 seconds waiting for DHCP/cloud-init to assign an address.

Live updates

Editing user.tsdproxy.* keys triggers a proxy restart automatically — only tsdproxy keys are compared, so unrelated config changes (profiles, volatile keys, devices) never restart proxies:

incus config set myapp user.tsdproxy.port.1=443/https:8080/http

Freeze / unfreeze

Freezing an instance (incus freeze) suspends all its processes, so TSDProxy tears the proxy down — the Tailscale machine disappears while the instance is frozen. Unfreezing (incus unfreeze) re-creates it automatically. Instances that were already frozen when TSDProxy starts are skipped until unfrozen.

Tailscale exposure modes

Incus instances work with all Tailscale exposure modes — per-proxy, shared, and Services/VIP (services: true on the Tailscale provider). When using Services mode:

• Do not set user.tsdproxy.domain — VIP Services assign FQDNs automatically
• UDP ports are not supported (/tcp, /http, /https only)
• The instance hostname (or user.tsdproxy.name) becomes the VIP service name (svc:<hostname>)
• Per-instance user.tsdproxy.authkey is ignored — the shared services node authenticates via OAuth

Provider configuration reference