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).