Skip to content

Tunnel Types

Tunnel types are registered in the agent and fall into two categories:

  • Reverse tunnels (traffic.tunnels) — expose a local service to the internet via the Connect Server.
  • Forward tunnels (traffic.forward-tunnels) — expose a remote service on the local network via the Agent.

The endpoint field should use the appropriate path for the service type (e.g. /connect/https for standard HTTPS tunnels). Set tunnel-defaults.endpoint in agent.yaml to avoid repeating it per tunnel — see Agent Configuration Reference for the full key reference behind every example below.

Exposing a tunnel carries risk, particularly for the file, httpreverseproxy, or tcp types, since they can expose arbitrary local data or services to the internet. See Authentication for gating access to a tunnel's traffic.


Reverse Tunnels

Echo

Example service that echoes HTTP requests back to the client. Useful for verifying connectivity end to end.

agent.yaml:

traffic:
  tunnels:
    - type: echo
      name: echo
      endpoint: https://connect.dioad.dev/connect/https
      tls-server:
        acme:
          cache-directory: /path/to/.autocert
      config:
        enable-prometheus-metrics: true
        debug: true

Hello

Minimal template service that shows a templated page mentioning the authenticated principal — the default tunnel type in the dioad/connect Docker image, good for a first smoke test.

agent.yaml:

traffic:
  tunnels:
    - type: hello
      name: hello
      endpoint: https://connect.dioad.dev/connect/https
      tls-server:
        acme:
          cache-directory: /path/to/.autocert
      config:
        custom-message: "your message here"

Dynamichello

Like hello, with a greeting you can change while the tunnel is running, from its panel in the management console. It is the reference for a tunnel type with a management extension.

agent.yaml:

traffic:
  tunnels:
    - type: dynamichello
      name: dynamichello
      endpoint: https://connect.dioad.dev/connect/https
      tls-server:
        acme:
          cache-directory: /path/to/.autocert
      config:
        custom-message: "your message here"

Dummy

The smallest working service: it answers every request with one line of plain text naming the time, host and platform. Useful as a placeholder while you set up a tunnel's hostname and certificate.

agent.yaml:

traffic:
  tunnels:
    - type: dummy
      name: dummy
      endpoint: https://connect.dioad.dev/connect/https
      tls-server:
        acme:
          cache-directory: /path/to/.autocert

File

Shares files or a directory from the local machine. Secure by default: a randomised path prefix is generated each time the agent connects (a new connection gets a new prefix), and it supports HTTP Basic Auth (recommended) — see Authentication § Per-Tunnel Traffic Authentication.

agent.yaml:

traffic:
  tunnels:
    - type: file
      name: file
      endpoint: https://connect.dioad.dev/connect/https
      tls-server:
        acme:
          cache-directory: /path/to/.autocert
      config:
        enable-prometheus-metrics: true
        debug: true
        root-directory: .
        prefix: /something-custom
        disable-dynamic-prefix: false
        authentication:
          type: basic
          basic:
            htpasswd-file: /path/to/htpasswd

For one-off sharing without writing a config file at all, use connect agent share instead — see the CLI reference (SHA-256 URL prefixes, per-download logging, download limits, optional QR code).

HTTP Reverse Proxy

Proxies HTTP(S) traffic to a local (or reachable) upstream — the tunnel type for exposing a web app, API, or internal dashboard.

agent.yaml:

traffic:
  tunnels:
    - name: nginx
      type: httpreverseproxy
      endpoint: https://connect.dioad.dev/connect/https
      tls-server:
        local:
          cert: /path/to/TestServerCertificate.pem
          key: /path/to/TestServerCertificate.key
      config:
        target-url: http://127.0.0.1:8080

Also supports config.authentication (basic/GitHub/HMAC/JWT — see the caveat on OIDC) — see Authentication § Per-Tunnel Traffic Authentication. When configured, the authenticated principal is forwarded to target-url as X-Forwarded-User — see Authentication § Forwarding the Authenticated Principal Upstream.

TCP

Raw TCP passthrough — for anything that isn't HTTP (SSH, databases, etc.). Use HTTP Reverse Proxy instead for HTTP backends.

agent.yaml:

traffic:
  tunnels:
    - name: ssh
      type: tcp
      endpoint: https://connect.dioad.dev/connect/https
      tls-server:
        local:
          cert: /path/to/TestServerCertificate.pem
          key: /path/to/TestServerCertificate.key
      config:
        target-address: 127.0.0.1:22

See the Cookbook for a worked SSH-over-TCP-tunnel example.

CoreDNS

Runs an authoritative DNS server (via CoreDNS) as a tunnel — useful both for serving your own DNS records and as an ACME dns-01 challenge helper for other tunnels on the same agent.

agent.yaml:

traffic:
  tunnels:
    - type: coredns
      name: ns
      endpoint: https://connect.dioad.dev/connect/https
      tls-server:
        acme:
          cache-directory: .autocert
      tags:
        - "dns"
      config:
        listen-address: 127.0.0.1:8555
        listen-protocol: "http"
        enable-debug: true
        enable-logging: true

If another tunnel's tls-server.acme uses type: dns-01 instead of the default tls-alpn-01, it needs a DNS-01 challenge provider — a CoreDNS tunnel serving authoritative DNS for that tunnel's domain can act as one. See agent.dioad-dev-mail.yaml in this repository for a complete working example, and Agent Configuration Reference § TLS Server for the dns01-* keys.

CoreDNS also supports a richer smtp-domains config for serving DKIM/DMARC/SPF/MTA-STS/TLS-RPT DNS records for mail-hosting setups (used together with Mailrouter below) — this is the most complex config surface in the codebase and isn't fully documented here; see internal/servers/coredns/config.go and the worked example in agent.dioad-dev-mail.yaml if you need it.

Mailrouter

Runs an SMTP server and routes inbound mail to pluggable handlers by recipient — DMARC aggregate-report ingestion, attachment archiving, TLS-RPT report ingestion, and more.

agent.yaml (minimal — the default when routes: is omitted is a single catch-all route to the dmarc handler):

traffic:
  tunnels:
    - type: mailrouter
      name: mailrouter
      endpoint: https://connect.dioad.dev/connect/https   # or your server's SMTP-capable service endpoint
      tls-server:
        acme:
          cache-directory: .autocert
      config:
        domain: example.com

See Agent Configuration Reference § mailrouter for the full routes/handler-type reference (multiple recipient-matched routes, per-handler config, message-size limits).

Webhookdebug

A minimal webhook inspector: exposes a public HTTPS endpoint, logs and displays incoming requests in a small ring buffer via its management UI. Useful for debugging what a third-party service is actually sending you (payload shape, headers) before wiring up a real handler.

agent.yaml:

traffic:
  tunnels:
    - type: webhookdebug
      name: webhookdebug
      endpoint: https://connect.dioad.dev/connect/https
      tls-server:
        acme:
          cache-directory: .autocert
      config:
        history: 50   # number of recent requests to retain

View captured requests at the agent's management UI (http://localhost:4444, under this tunnel's extension).

Forward Tunnels

SOCKS5 (forward tunnel)

Provides SOCKS5 proxy access from the local machine to services reachable by the Connect Server. This is a forward tunnel: the agent listens locally and forwards traffic outward through the server.

agent.yaml:

traffic:
  forward-tunnels:
    - type: socks5
      name: proxy
      endpoint: https://connect.dioad.dev/connect/socks5
      listen-address: 127.0.0.1:1080

Configure your local applications to use socks5://127.0.0.1:1080 as a proxy.

Managed Exec Services

Not a tunnel type — a way to have the agent launch and supervise a companion process (e.g. a mail server like maddy) alongside your tunnels, typically one that a tunnel then exposes.

agent.yaml:

services:
  exec:
    - name: maddy
      type: maddy
      command: /path/to/maddy
      args:
        - "--config"
        - "{{ .ConfigFile }}"
        - run
      depends-on:
        - type: mailrouter
          name: mailrouter

depends-on makes the agent wait for the listed tunnels to be established before starting the process — see Agent Configuration Reference § services for the full reference, including dependency-timeout and environment/working-directory options.

TLS certificates for a maddy exec service: by default, maddy extracts a certificate from a sibling HTTPS tunnel's ACME cache directory. As an opt-in alternative, maddy can issue its own certificate directly via DNS-01, using its built-in acmedns libdns provider against a local, loopback-only ACME-DNS API this agent exposes — see Agent Configuration Reference § acme-dns and services.exec[].config.acme-dns in the same reference. Requires a coredns tunnel and maddy built with the libdns_acmedns build tag.

Docker Discovery

The agent can watch the Docker daemon and automatically create tunnels for any container that opts in via labels — no manual tunnel config required.

Add these labels to any container you want to expose:

labels:
  dioad.connect.enable: "true"
  dioad.connect.tunnel.type: httpreverseproxy   # or: tcp

agent.yaml:

tunnel-defaults:
  endpoint: https://connect.dioad.dev/connect/https
  tls-server:
    acme:
      cache-directory: .autocert

discovery:
  docker:
    - socket: unix:///var/run/docker.sock
      label-prefix: dioad.connect

When the agent itself runs as a container, set use-container-name: true so it reaches sibling services by their Docker DNS name rather than a host-mapped port. Both containers must share a user-defined Docker network.

discovery:
  docker:
    - socket: unix:///var/run/docker.sock
      label-prefix: dioad.connect
      use-container-name: true

A ready-to-use Compose file ships in examples/docker-compose.docker-discovery.yml:

# Authenticate once (device-flow login; saves token to a named volume)
docker run --rm -it -v dioad-connect-persist:/persist dioad/connect auth

# Start the agent and your service
docker compose -f examples/docker-compose.docker-discovery.yml up

Any container with dioad.connect.enable=true that joins the shared network gets a tunnel automatically; watch the agent logs for the tunnel URL.

Supported labels:

Label Required Default Description
dioad.connect.enable yes — Set to true to opt in
dioad.connect.tunnel.type no httpreverseproxy Tunnel type: httpreverseproxy or tcp. Other types need allowed-types
dioad.connect.tunnel.name no sanitised container name Tunnel name (shown in management UI and logs)
dioad.connect.tunnel.subdomain no tunnel-defaults.subdomain Subdomain prefix for the tunnel hostname
dioad.connect.tunnel.endpoint no tunnel-defaults.endpoint Connect server endpoint URL. Must be on the default endpoint's host or one in allowed-endpoint-hosts
dioad.connect.tunnel.tags no — Comma-separated tags
dioad.connect.tunnel.config.target-url no inferred from exposed ports Target URL (httpreverseproxy only)
dioad.connect.tunnel.config.target-address no inferred from exposed ports Target address host:port, no scheme (tcp only)

Labels are untrusted

Labels can come from any image you run, so the agent restricts the tunnel types, endpoints and targets they may choose. See Agent Configuration § discovery.docker for the policy and the settings that widen it.

Hosted vs. self-hosted

The hosted connect.dioad.dev server uses a separate endpoint for TCP tunnels. Set tunnel-defaults.endpoint: https://connect.dioad.dev/connect/tcp (or dioad.connect.tunnel.endpoint per container) when using tunnel.type: tcp against the hosted service.

Network ACLs

All tunnel types support per-tunnel network ACLs to restrict inbound connections by source CIDR:

traffic:
  tunnels:
    - name: internal-api
      type: httpreverseproxy
      config:
        target-url: http://127.0.0.1:9000
      network-acl:
        allow:
          - 10.0.0.0/8
          - 192.168.0.0/16
        deny: []
        allow-by-default: false   # default; deny all unless explicitly allowed

Custom server types

If you fork and compile the agent yourself, you can add and register your own tunnel types — see Extension Authoring, including the "Built-in Tunnel Types" table for what each built-in type's source looks like as a reference implementation, and the registration step (internal/cmd/agent/registry_init.go).