Skip to content

Agent config file reference

Every key a connect agent config file can set, generated from the structs the agent loads its config into. For what the settings do and how they fit together, see the agent configuration guide. An editor can check a config file as you type with the JSON Schema at https://dioad.github.io/connect/schema/agent.schema.json; "connect agent config validate" also checks the rules the schema cannot express.

Top level

Config is the top-level configuration for the agent.

Key Type Default Description
log object
identity object identity provides the OIDC client configuration for agent identity.
management object management defines the configuration for the agent's management interface.
acme-dns object acme-dns defines the configuration for the agent-local acme-dns-compatible HTTP API. It lets an external ACME client running as a sibling exec process (e.g. maddy, via its built-in "acmedns" libdns provider) publish DNS-01 challenge values into the same ChallengeStore this agent's own dns-01 tunnels already use, instead of depending on a sibling tunnel's certificate lifecycle. See doc/architecture/agent/future/MADDY_LIBDNS_ACME_DESIGN.md. Optional - leave ListenAddress empty (the default) to disable it entirely.
traffic object traffic defines how the agent handles network traffic.
tunnel-defaults object tunnel-defaults provides default values for tunnel configurations.
services object services defines the services (like exec) that the agent should run.
discovery object discovery configures dynamic tunnel discovery sources.
plugins object plugins configures external tunnel server plugins: where signed plugin releases are found and which signing keys are trusted. See doc/user/PLUGINS.md.
status object status configures the status file the agent keeps for connect agent status and other tools.
shutdown-timeout duration shutdown-timeout bounds the agent's graceful-shutdown sequence: drain all tunnels, stop all exec child processes (maddy, coredns, ...), then stop the management and acme-dns HTTP servers. When unset or non-positive it defaults to defaultShutdownTimeout (5s). Raise it for an agent running several exec processes or many tunnels, where 5s can be too short and Stop deadlines start biting.
profile-cpu-output string profile-cpu-output specifies the file path where CPU profile data should be saved.
profile-memory-output string profile-memory-output specifies the file path where the heap profile is written when the agent stops.
profile-block-output string profile-block-output specifies the file path where the blocking profile is written when the agent stops.

log

Config contains all configuration options for logging behavior.

Fields support struct tags for configuration file unmarshaling:

YAML Example:

Key Type Default Description
level string level specifies the logging level: trace, debug, info, warn, error, fatal, panic. Empty string defaults to application-configured level or zerolog.WarnLevel.
file string file specifies the path to the log file. Supports home directory expansion (~). Empty string disables file logging (logs to stdout only).
max-size integer max-size is the maximum size of the log file in MB before rotation occurs. Default is 100 MB.
max-age integer max-age is the maximum number of days to keep old log files. Default is 0 (no limit).
max-backups integer max-backups is the maximum number of old log files to retain. Default is 0 (keep all).
use-local-time boolean use-local-time determines if rotated filenames use local time instead of UTC. Default is false.
compress boolean compress determines if old log files are gzip-compressed after rotation. Default is false.
mode string mode is reserved for future use.

identity

ClientConfig captures client credentials and token acquisition options for an OIDC provider.

Key Type Default Description
type string type selects a provider-specific behaviour. Accepted values are "github", "githubactions", "keycloak", "flyio" and "aws". Leave empty for a generic OIDC provider discovered from URL.
url string url is the OIDC issuer URL, for example "https://accounts.example.com". Provider metadata and signing keys are discovered from it.
keycloak-realm string keycloak-realm is the Keycloak realm name. It is only used when Type is "keycloak".
client-id string client-id is the OAuth 2.0 client identifier registered with the provider.
client-secret string client-secret is the OAuth 2.0 client secret, used for the client credentials flow. Set at most one of ClientSecret and ClientSecretFile.
client-secret-file string client-secret-file is the path to a file containing the client secret, for example a mounted container secret. Surrounding whitespace is trimmed. The file is read when the token source is built, not when the config is validated; an unreadable or empty file is an error. Set at most one of ClientSecret and ClientSecretFile.
audience string audience is the audience requested for issued tokens. It is required by platform identity providers such as "githubactions", "flyio" and "aws" and ignored by providers that do not support it.
token-file string token-file is the path to a file used to persist the interactive login token between runs. When set, the token is loaded from the file and refreshed with its refresh token once it expires.
tls-client object tls-client configures TLS for connections to the provider, such as a custom CA bundle.

management

ManagementConfig configures the agent's local management interface.

Key Type Default Description
listen-address string listen-address is the address the management interface will listen on (e.g., ":4444").
operations-listen-address string OperationsListenAddress, when set, starts a second listener serving /health/live, /health/ready and /metrics with no authentication, for a platform health check and metrics scraper that cannot log in. The management interface keeps its authentication. Bind it where only the platform can reach it: a private network or loopback. Needs listen-address.
session-secret string
session-secret-file string session-secret-file is a file holding the session secret, for deployments that mount secrets as files instead of putting them in the config. Set at most one of session-secret and session-secret-file. Surrounding whitespace is ignored.
local-auth-disabled boolean local-auth-disabled explicitly opts out of local basic-auth for the management interface. By default, when the management interface is enabled (ListenAddress is non-empty), a missing or empty htpasswd file causes the agent to refuse to start rather than run the management interface unauthenticated.
local-auth object local-auth configures local HTTP Basic authentication for the management interface, backed by a bcrypt-hashed htpasswd-style credentials file (HTPasswdFile, one "user:bcrypt-hash" entry per line). HTPasswdFile defaults to ~/.config/dioad/connect/htpasswd when left empty. Users is not read by the basic-auth handler - credentials always come from HTPasswdFile, not this list.
allow-unauthenticated-non-loopback boolean allow-unauthenticated-non-loopback explicitly opts in to serving the management interface - including the full tunnel-control API (POST /api/tunnels, POST /api/tunnel/{id}/state, GET /api/events) - unauthenticated on a non-loopback listener. By default the agent refuses to start in that combination (LocalAuthDisabled: true, bound to a non-loopback address) because anyone who can reach the listener then has full tunnel control with no credential. Only set this when a trusted TLS-terminating proxy or equivalent network control already sits in front of this listener.

acme-dns

ACMEDNSConfig configures the agent-local acme-dns-compatible HTTP API.

Key Type Default Description
listen-address string listen-address is the address this API listens on (e.g. "127.0.0.1:8556"). Defaults to "127.0.0.1:8556" if left empty. It must be a loopback address: unlike the coredns tunnel's own DNS listener, this HTTP API is never bridged across the reverse tunnel, and the internally generated per-account credentials below are only a safe authentication mechanism because the listener itself is unreachable from anywhere but this host. See validateACMEDNSListenAddress.
accounts list of object accounts are the identities external ACME clients authenticate as, mirroring the acme-dns protocol's per-account model. Each account maps to exactly one target domain: an accepted update publishes "_acme-challenge.<domain>." into the shared ChallengeStore. The API runs when there is at least one account here or a "maddy" exec sets config.acme-dns.enable - there is no separate enable flag. A maddy exec needs no account here: the agent creates one for its MX hostname.

traffic

TrafficConfig used to contain tunnel configuration.

Key Type Default Description
tunnels list of object
forward-tunnels list of object

tunnel-defaults

TunnelConfigDefaults holds default tunnel settings that individual tunnels inherit when they do not set their own.

Key Type Default Description
endpoint string
subdomain string
tls-client object tls-client and TLSServer are pointers, not values, so WithOverrides can tell "not set at this level" (nil) apart from an explicit empty override.
tls-server object
network-acl object network-acl is a *authz.NetworkACLConfig, not a value, so WithOverrides can tell "not set at this level" (nil) apart from an explicit zero-value ACL - the zero value is deny-all, a meaningful explicit choice that a more permissive default must not silently override.

services

ServiceConfig configures the services run by the agent.

Key Type Default Description
exec list of object

discovery

DiscoveryConfig holds configuration for all dynamic tunnel discovery sources.

Key Type Default Description
docker list of object docker lists Docker-based discovery sources. Each entry configures the agent to watch a Docker daemon for labelled containers and create tunnels for them automatically.
file list of object file lists file-based discovery sources. Each entry configures the agent to load tunnels from a YAML file (under that file's own traffic: key) and watch it for changes. The agent's own traffic: block is always available as an implicit, unnamed entry of this kind (see ServiceFactory.buildFileSources) - File is for additional or separate files.

plugins

Config is the agent's plugins section.

Key Type Default Description
directory string directory holds one sub-directory per plugin, each containing manifest.json, manifest.json.sig and the plugin binaries. Plugins are disabled when it is empty.
cache-directory string cache-directory receives digest-verified copies of plugin binaries; only these copies are ever executed. Defaults to a "plugins" directory under the user cache directory.
require-signature boolean require-signature rejects plugins without a valid signature from a trusted key. Defaults to true.
trusted-keys list of object trusted-keys are the public keys plugin manifests may be signed with.
allow-unsigned list of string allow-unsigned names plugins exempt from RequireSignature, for local development. Every load of such a plugin is logged as a warning.
env-allowlist list of string env-allowlist names the agent environment variables passed to plugin processes. Nothing else from the agent's environment is passed.

status

StatusConfig configures the status file the agent keeps for connect agent status and other tools. See doc/user/AGENT_STATUS_FILES.md.

Key Type Default Description
directory string directory is where the agent keeps its status file, shared with any other agents that use it. Defaults to $CONNECT_AGENT_STATUS_DIR, or ~/.config/dioad/connect/status.d when that is unset.
disabled boolean disabled turns the status file off. connect agent status then only reports this agent through its management interface.

identity.tls-client

ClientConfig specifies TLS client configuration.

Key Type Default Description
root-ca-file string
cert string
key string
insecure-skip-verify boolean

management.local-auth

ServerConfig configures HTTP Basic authentication for a server.

Key Type Default Description
allow-insecure-http boolean
htpasswd-file string
users list of string
realm string
throttle object throttle limits failed logins per client address. It is enabled by default; see ThrottleConfig for the limits.

acme-dns.accounts[]

ACMEDNSAccountConfig is the YAML shape of one ACMEDNSConfig.Accounts entry. It is intentionally self-contained rather than cross-referenced by name from a maddy exec's own config - the same duplication-by-convention already accepted elsewhere in this codebase for e.g. tls-server.acme.cache-directory (see doc/architecture/agent/future/CONNECT_AGENT_SERVICE_DESIGN.md's Background section), and simpler than adding a cross-reference lookup mechanism for a single, config-time-static relationship. There is deliberately no Password field: it is generated internally, fresh on every agent start, and never appears in any config file on either side - see internal/servers/coredns.ACMEDNSResource.Password.

Key Type Default Description
username string
subdomain string
domain string

traffic.tunnels[]

ReverseConfig represents the configuration for a reverse tunnel.

Key Type Default Description
name string name is the name of the tunnel.
type string type is the type of the tunnel (e.g., "forward", "reverse").
endpoint string endpoint is the endpoint URL of the tunnel.
tags list of string tags is a list of tags associated with the tunnel.
config map
tls-server object tls-server and TunnelTLSClient are pointers, not values, so callers merging this config against a layered default (global tunnel defaults, per-discovery-source defaults) can tell "not set at this level" (nil) apart from an explicit empty override.
tls-client object
network-acl object network-acl is a *authz.NetworkACLConfig, not a value, so callers merging this config against a layered default (global tunnel defaults, per-discovery-source defaults) can tell "not set at this level" (nil) apart from an explicit zero-value ACL - the zero value is deny-all (AllowByDefault is false with no allow/deny lists), which is a meaningful, security-relevant explicit choice that a permissive default must not silently override.
hostname string hostname is the endpoint name the tunnel registers in place of its name. It lets tunnels of one type share a hostname, such as several tcp tunnels serving the mx host on different ports, while each keeps the unique name that depends-on, discovery and the management API identify it by. When unset, the tunnel registers under its name.
extra-names list of string
subdomain string
custom-domains list of string
publish-public-ip string
dns object

The keys of config depend on type:

traffic.forward-tunnels[]

ForwardConfig represents the configuration for a forward tunnel.

Key Type Default Description
name string name is the name of the tunnel.
type string type is the type of the tunnel (e.g., "forward", "reverse").
endpoint string endpoint is the endpoint URL of the tunnel.
tags list of string tags is a list of tags associated with the tunnel.
config map
tls-server object tls-server and TunnelTLSClient are pointers, not values, so callers merging this config against a layered default (global tunnel defaults, per-discovery-source defaults) can tell "not set at this level" (nil) apart from an explicit empty override.
tls-client object
network-acl object network-acl is a *authz.NetworkACLConfig, not a value, so callers merging this config against a layered default (global tunnel defaults, per-discovery-source defaults) can tell "not set at this level" (nil) apart from an explicit zero-value ACL - the zero value is deny-all (AllowByDefault is false with no allow/deny lists), which is a meaningful, security-relevant explicit choice that a permissive default must not silently override.
listen-address string

tunnel-defaults.tls-server

ServerConfig specifies TLS configuration for a server.

Key Type Default Description
server-name string
acme object
self-signed object
local object
client-auth-type string
client-ca-file string
next-protos list of string
tls-min-version string

tunnel-defaults.network-acl

NetworkACLConfig describes the configuration for network-based access control.

Key Type Default Description
allow list of string
deny list of string
allow-by-default boolean

services.exec[]

Config describes an exec: what it is, how it is configured, and what it depends on.

Key Type Default Description
name string
type string
tags list of string
config map
depends-on list of object
dependency-timeout duration dependency-timeout bounds how long the supervisor waits for DependsOn to be met before logging an error and marking the exec as timed out. Zero uses the manager's default.
command string
args list of string
environment map of string
working-directory string

The keys of config depend on type:

discovery.docker[]

DiscoveryConfig configures a single Docker-based tunnel discovery source.

Key Type Default Description
socket string socket is the Docker socket path or URL (e.g. "unix:///var/run/docker.sock"). When empty, the default Docker socket is used.
label-prefix string label-prefix is the prefix used to identify connect-related labels on containers. Defaults to "dioad.connect" when empty.
use-container-name boolean use-container-name controls how the target host is inferred when constructing tunnel target URLs for discovered containers.

When false (default — agent running on the Docker host):

When true (agent running as a Docker container on the same network):

Note: "use-container-name" only affects auto-inferred target values. Per-container overrides via "tunnel.config.target-url" (httpreverseproxy) or "tunnel.config.target-address" (tcp) labels always take precedence.
allowed-types list of string allowed-types lists the tunnel types a container label may select via "tunnel.type". Containers requesting any other type are skipped. Defaults to "httpreverseproxy" and "tcp" when empty.

Container labels, including those baked into third-party images, are untrusted input: widen this list only for types you are willing to let any labelled container instantiate.
allowed-endpoint-hosts list of string allowed-endpoint-hosts lists the hostnames a container may name in its "tunnel.endpoint" label. The agent presents its identity token to the endpoint, so labels naming any other host are rejected. The host of the configured default endpoint is always allowed, so a label can still pick another path on it. Empty means labels cannot move the endpoint to a new host.
allow-custom-targets boolean allow-custom-targets permits "tunnel.config.target-url" and "tunnel.config.target-address" labels that point somewhere other than a port the container itself exposes. Link-local and unspecified addresses are rejected regardless.
defaults object defaults provides fallback tunnel configuration values for discovered containers that do not specify all tunnel fields via labels.

discovery.file[]

DiscoveryConfig configures a single file-based tunnel discovery source: a YAML file containing traffic.tunnels/traffic.forward-tunnels- shaped content under its own traffic: key, loaded at boot and watched for changes afterward.

Key Type Default Description
path string path is the file to load tunnels from and watch for changes.
defaults object defaults provides fallback tunnel configuration values for tunnels loaded from this file, merged over the global tunnel-defaults.

plugins.trusted-keys[]

TrustedKey is one plugin signing key.

Key Type Default Description
name string name identifies the key in logs.
public-key string public-key is "ed25519:<base64 PKIX>", as printed by "connect plugin keygen".

management.local-auth.throttle

ThrottleConfig limits failed logins per client address to slow down password guessing. Throttling is enabled unless Disabled is set.

Key Type Default Description
disabled boolean disabled turns failed-login throttling off. By default throttling is on.
max-failures integer max-failures is the number of rejected logins allowed within Window before the client address is locked out. Defaults to 10.
window duration window is how long a failed login counts towards MaxFailures. Defaults to 5 minutes.
lockout duration lockout is how long a client address is rejected with 429 once MaxFailures is reached, even if it then supplies the right password. Defaults to 5 minutes.

traffic.tunnels[].dns

TunnelDNSConfig holds the DNS records a tunnel declares it requires. It is decoded from the "dns:" YAML block on the tunnel stanza and is independent of any specific server type.

Key Type Default Description
mx list of object
txt list of object
cname list of object
srv list of object

traffic.tunnels[].config (type: coredns)

Config configures the embedded CoreDNS server.

Key Type Default Description
tls-server object
smtp-domains list of object
listen-address string
listen-protocol string
enable-logging boolean
enable-debug boolean

traffic.tunnels[].config (type: dummy)

Config configures the dummy server.

Key Type Default Description
local-listen-address string
enable-prometheus-metrics boolean
debug boolean

traffic.tunnels[].config (type: dynamichello)

Config configures the dynamic hello server.

Key Type Default Description
custom-message string
metadata map of string

traffic.tunnels[].config (type: echo)

Config configures the echo server.

Key Type Default Description
local-listen-address string
enable-prometheus-metrics boolean
debug boolean

traffic.tunnels[].config (type: file)

Config configures the file server.

Key Type Default Description
local-listen-address string
enable-prometheus-metrics boolean
debug boolean
root-directory string
prefix string
disable-dynamic-prefix boolean
metadata object
authentication object

traffic.tunnels[].config (type: hello)

Config configures the hello server.

Key Type Default Description
custom-message string
metadata map of string

traffic.tunnels[].config (type: httpreverseproxy)

Config configures the HTTP reverse proxy server.

Key Type Default Description
target-url string
authentication object
tls-client object
address-validation object

traffic.tunnels[].config (type: mailrouter)

Config holds configuration for the "mailrouter" tunnel type.

Unlike mailsupport, this has no auth config: the admin API and dashboard UI (see resource_extension.go, adminui) are reachable only through the agent's own local management API, never published through connect-server, so there is currently no way to obtain a token to validate against them (the agent may have no network path to an IdP at all). See doc/AGENT_CONFIGURATION.md's mailrouter section for the reasoning and what changes first if that ever needs to be revisited.

Key Type Default Description
domain string
limits object
routes list of object

traffic.tunnels[].config (type: mailsupport)

Config holds the configuration for the mail support tunnel server.

Key Type Default Description
metadata object
maddy-command string
maddy-config-file-path string
enable-debug boolean
jwt-validators list of object
principal-acl object principal-acl defines an explicit allow/deny list for the API and profile routes. When AllowList is empty the tunnel's own TunnelPrincipal (injected via metadata) is used as the sole allowed caller. If neither an explicit AllowList nor a TunnelPrincipal are available, all access is denied (default-deny policy).

traffic.tunnels[].config (type: mta-sts)

Config holds the configuration for the MTA-STS policy-hosting tunnel.

Key Type Default Description
mta-sts object
metadata object

traffic.tunnels[].config (type: socks5)

Config configures the SOCKS5 server. The server only accepts CONNECT requests.

Key Type Default Description
allowed-ports list of integer allowed-ports lists the destination ports the server connects to. Empty allows any port.
block-private-destinations boolean block-private-destinations refuses destinations that are not public internet addresses: loopback, private and unique local, link-local (including cloud metadata endpoints), multicast and other special-purpose ranges. Set it on any exit other principals use.
quota object quota limits connections per principal: the tenant whose forward tunnel the connection arrived on, which connect-server sends in the PROXY header. With a quota set, a connection without a principal is refused, so set one only behind a connect-server that sends it.

traffic.tunnels[].config (type: tcp)

Config configures the TCP forwarding server.

Key Type Default Description
target-address string target-address is the host:port each tunnel connection is forwarded to.
proxy-protocol-version integer proxy-protocol-version is the PROXY protocol version, 1 or 2, of a header sent ahead of each connection to name the client that connected to the tunnel; 0 sends none. The target must expect it. A maddy exec fed by this tunnel reads it automatically.

traffic.tunnels[].config (type: webhookdebug)

Config configures the webhook debug server.

Key Type Default Description
history integer

tunnel-defaults.tls-server.acme

ACMEConfig specifies parameters for obtaining a certificate via ACME, using either the tls-alpn-01 challenge (delegated to golang.org/x/crypto/acme/autocert) or the dns-01 challenge (a hand-rolled github.com/go-acme/lego/v5 client). The two challenge types share the same account identity and cache directory, but obtain certificates through entirely independent runtime implementations - only the config surface is unified here.

Key Type Default Description
type string type selects the ACME challenge mechanism: ACMEChallengeTLSALPN01 or ACMEChallengeDNS01. An absent/empty Type (the zero value) defaults to ACMEChallengeTLSALPN01, so callers who only need TLS-ALPN-01 can omit this field entirely.
email string
directory-url string
cache-directory string
domains list of string domains is, for Type=dns-01, the SANs to include on the single certificate obtained upfront (may include wildcards, e.g. "*.example.com"); for Type=tls-alpn-01 (default), the whitelist of hosts autocert will provision certificates for on demand via autocert.HostWhitelist. Wildcard entries are rejected for tls-alpn-01 - TLS-ALPN-01 cannot validate wildcard identifiers (RFC 8555 permits wildcards only via dns-01), and autocert's HostWhitelist silently ignores such entries rather than erroring, so NewACMETLSConfig validates this upfront instead.
dns01-propagation-timeout duration dns01-propagation-timeout bounds how long lego waits for DNS propagation of the challenge TXT record. Zero uses lego's default (60s).
dns01-polling-interval duration dns01-polling-interval controls how often lego polls while waiting for propagation. Zero uses lego's default (2s).

tunnel-defaults.tls-server.self-signed

SelfSignedConfig specifies parameters for generating a self-signed certificate.

Key Type Default Description
subject object
san object
duration string
ca boolean
bits integer
cache-directory string
alias string

tunnel-defaults.tls-server.local

LocalConfig specifies local certificate and key file locations.

Key Type Default Description
single-pem-file string
cert string
key string
file-wait-interval integer
file-wait-max integer

services.exec[].depends-on[]

Dependency names another exec or service that an exec needs to be running first.

Key Type Default Description
name string
type string
service-type string

services.exec[].config (type: maddy)

Config configures the maddy mail server run by the agent.

Key Type Default Description
state-dir string
runtime-dir string
config-dir string
aliases-path string
debug boolean
io-debug boolean
aliases map of string
enable-socks5 boolean enable-socks5 sends maddy's outbound mail through the agent's forward tunnel of type socks5, found by its listen-address: its port, and its host unless it listens on every address, which maddy reaches on loopback. Port 1080 stands in until that tunnel registers. It needs at most one forward tunnel of type socks5; other forward tunnels are ignored.
acme-dns object acme-dns configures maddy to obtain its own TLS certificate directly, via maddy's built-in "acmedns" libdns provider, instead of extracting one from a sibling HTTPS tunnel's autocert cache (this exec's default, and the only behavior when Enable is false). See doc/architecture/agent/future/MADDY_LIBDNS_ACME_DESIGN.md. Requires maddy itself to be built with the "libdns_acmedns" build tag, and a matching account configured under this agent's top-level "acme-dns.accounts" -- Username/Subdomain here must equal one of those accounts exactly (see ACMEDNSAccountConfig). There is no Password field: it is looked up automatically from the matching account at render time (see ACMEDNSPasswordLookup) -- nothing ever puts it in a config file.
cert-source object cert-source explicitly names the HTTPS tunnel maddy's certificate should be extracted from, removing the ambiguity of the default domain-based search in getMaddyServiceCertificate (finding 52, doc/claude-review-architecture.md: two tunnels can legitimately serve the same domain, and the implicit search has no way to break the tie). Both Type and Name must be set together, or both left empty to keep the legacy domain search for backward compatibility. Ignored entirely when ACMEDNS.Enable is set, since maddy then issues its own certificate and no cert-source lookup happens at all.

traffic.tunnels[].dns.mx[]

Record is a DNS MX record following the same Render pattern as dmarc.Record and spf.Record: fields may contain Go template strings expanded at render time.

Key Type Default Description
host string host is a Go template string for the mail exchange FQDN (must end in "."). Empty defaults to "{{.Domain}}." at render time — the tunnel's own FQDN.
prefix string prefix is the DNS owner label relative to the base domain. "" = apex.
ttl integer ttl is the DNS TTL in seconds advertised to resolvers. Zero uses dns.DefaultTTL.
priority integer priority is the MX preference value.

traffic.tunnels[].dns.txt[]

TXTRecord is a generic DNS TXT record with optional Go template expansion in Value.

Key Type Default Description
name string name is the DNS owner label relative to the base domain. "" = apex.
value string value is a Go template string for the TXT record content (e.g. "v=spf1 {{.OutboundIPList}} -all").
ttl integer ttl is the DNS TTL in seconds advertised to resolvers. Zero uses DefaultTTL.

traffic.tunnels[].dns.cname[]

CNAMERecord is a generic DNS CNAME record with optional Go template expansion in Target. It follows the same Render pattern as mx.Record and netdns.TXTRecord.

Key Type Default Description
name string name is the DNS owner label relative to the base domain. "" = apex.
target string target is a Go template string for the canonical name this record points to (must end in "."), e.g. "{{.BaseDomain}}.".
ttl integer ttl is the DNS TTL in seconds advertised to resolvers. Zero uses netdns.DefaultTTL.

traffic.tunnels[].dns.srv[]

SRVRecord is a generic DNS SRV record with optional Go template expansion in Target. It follows the same Render pattern as mx.Record and netdns.TXTRecord.

Key Type Default Description
name string name is the DNS owner label relative to the base domain. "" = apex.
priority integer
weight integer
port integer
target string target is a Go template string for the target host (must end in "."), e.g. "{{.Domain}}.".
ttl integer ttl is the DNS TTL in seconds advertised to resolvers. Zero uses netdns.DefaultTTL.

traffic.tunnels[].config.smtp-domains[] (type: coredns)

SMTPDomain is a mail domain together with the DNS records published for it.

Key Type Default Description
name string
records object

traffic.tunnels[].config.metadata (type: file)

TunnelMetadata is the canonical, typed representation of a tunnel's metadata: the agent's local metadata store, and the shape exposed by the JSON search/metadata APIs — see doc/claude-review-architecture.md finding 11. It is a superset of TunnelConnectMetadata (the 12 fields that also cross the wire as response headers) plus fields known only locally to the agent, plus Extra for metadata outside the fixed schema entirely.

Key Type Default Description
originaddr string --- shared with TunnelConnectMetadata (see ToTunnelMetadata) ---
connectionid string
principal string
servicetype string
directiontype string
visibilitytype string
principalemail string
forwardtargetinternetaddr string
basedomain string
trafficport string
endpointdomains list of string
grantedcustomdomains list of string
id string --- known, local-only (never sent as a header) ---
trafficprotocol string set locally by the tunnel.Server implementation
aliases list of string
externalurls list of string
dnsconfig string JSON-encoded TunnelDNSConfig blob
extra map of string extra holds metadata outside the fixed schema above: discovery-source labels (e.g. Docker container ID/image/name), per-server custom key/value pairs, or user-configured tags. Never sent as an HTTP header — TunnelConnectMetadata has no field for it.

traffic.tunnels[].config.authentication (type: file)

ServerConfig represents the authentication configuration for an HTTP server.

Key Type Default Description
type string type selects the auth handler explicitly: "github", "basic", "hmac", "jwt", "oidc". When set it takes precedence over zero-value detection. An unrecognised Type returns an error from NewHandler.
basic object
github object
hmac object
jwt object
oidc object
providers list of string

traffic.tunnels[].config.address-validation (type: httpreverseproxy)

AddressValidationConfig configures IP address validation for the reverse proxy.

Key Type Default Description
enabled boolean enabled controls whether address validation is performed Default: true (validation enabled for security) To disable, explicitly set to false
allowed-ip-ranges list of string allowed-ip-ranges defines custom IP ranges that are allowed If empty, defaults to RFC 1918 private ranges, loopback, and IPv6 private ranges Example: ["10.0.0.0/8", "192.168.0.0/16"]
allow-cloud-metadata boolean allow-cloud-metadata controls whether cloud metadata endpoints (e.g., 169.254.169.254) are permitted as proxy targets. Cloud metadata endpoints are ALWAYS blocked by default, even if 169.254.0.0/16 is included in AllowedIPRanges. This prevents accidental exposure through misconfiguration. Set to true to explicitly allow. Default: false (metadata endpoints always blocked)

traffic.tunnels[].config.limits (type: mailrouter)

Limits caps resource usage per SMTP session.

Key Type Default Description
max-message-bytes integer
max-recipients integer

traffic.tunnels[].config.routes[] (type: mailrouter)

RouteConfig configures one route: which recipient local-parts it matches, which registered handler type processes matching mail, and that handler type's own opaque configuration.

Key Type Default Description
name string name optionally labels this route for its admin-API mount point (see aggregateResource); defaults to Type if empty.
recipients list of string
type string
config map

The keys of config depend on type:

traffic.tunnels[].config.jwt-validators[] (type: mailsupport)

ValidatorConfig controls validation behavior for issued tokens.

Key Type Default Description
type string type selects a provider-specific behaviour. Accepted values are "github", "githubactions", "keycloak", "flyio" and "aws". Leave empty for a generic OIDC provider discovered from URL.
url string url is the OIDC issuer URL, for example "https://accounts.example.com". Provider metadata and signing keys are discovered from it.
keycloak-realm string keycloak-realm is the Keycloak realm name. It is only used when Type is "keycloak".
audiences list of string audiences lists the accepted values of the token "aud" claim. A token is accepted if it carries at least one of them.
issuer string issuer is the expected token "iss" claim. Signing keys are discovered from its JWKS endpoint.
cache_ttl_seconds integer cache_ttl_seconds is how long, in seconds, discovered signing keys are cached. Defaults to 300 when unset or not positive.
signature_algorithm string signature_algorithm is a single accepted signing algorithm, for example "RS256". Ignored when SignatureAlgorithms is set.
signature_algorithms list of string signature_algorithms lists the accepted signing algorithms, for example "RS256", "ES256". Takes precedence over SignatureAlgorithm.
allowed_clock_skew_seconds integer allowed_clock_skew_seconds is the tolerance, in seconds, applied to the token "exp", "nbf" and "iat" claims. Defaults to 60 when unset or not positive.
debug boolean debug enables debug logging of each token validation attempt and its outcome. Intended for troubleshooting.
claim_predicates map claim_predicates restricts which tokens are accepted by their claims. Each key is a claim name and its value is the required claim value; an array claim matches when it contains the value. All entries must match. Use the reserved keys "and" and "or", each holding a list of such maps, for nested combinations.
hmac_secret string hmac_secret is an optional shared secret for HS256/HS384/HS512 token validation. When non-empty, JWKS discovery is skipped and the secret is used directly as the signing key. Intended for local development and smoke testing only; never use a static shared secret in production. Requires AllowInsecureHMAC: true to prevent accidental production use.
allow_insecure_hmac boolean allow_insecure_hmac must be set to true when HMACSecret is used. This explicit opt-in acknowledges that HMAC shared secrets are not suitable for production deployments. Never set this to true in production config.

traffic.tunnels[].config.principal-acl (type: mailsupport)

PrincipalACLConfig describes the configuration for principal-based access control.

Key Type Default Description
allow-list list of string
deny-list list of string
allow-by-default boolean allow-by-default controls the outcome when AllowList is empty (no allow rule configured). Mirrors NetworkACLConfig.AllowByDefault; defaults to false (deny) so an unconfigured ACL fails closed.

traffic.tunnels[].config.mta-sts (type: mta-sts)

Config represents MTA-STS configuration used to create a policy.

Key Type Default Description
mode string
mx list of string
max-age integer

traffic.tunnels[].config.quota (type: socks5)

QuotaConfig limits how many connections each principal may open through the exit. The exit sees only connections, not what is sent over them, so on a mail exit the limit counts delivery attempts: a retry, or a fallback to another MX host, is another connection.

Counts are kept in memory, so they reset when the agent restarts, and each exit instance keeps its own.

Key Type Default Description
connections-per-day integer connections-per-day is how many connections a principal may open in a 24 hour window, which starts at its first connection. Zero means no limit.
suspend-for duration suspend-for is how long a principal is refused once it has used up its quota, counted from the connection that went over. The refusal lasts at least until the principal's window ends, so SuspendFor can only lengthen it: a value shorter than the time left in the window has no effect. Zero refuses it until its window ends. A new window starts when the suspension ends.

tunnel-defaults.tls-server.self-signed.subject

CertificateSubject defines X.509 certificate subject information.

Key Type Default Description
c list of string
o list of string
ou list of string
l list of string
st list of string
street list of string
postalcode list of string
serialnumber string
cn string

tunnel-defaults.tls-server.self-signed.san

SANConfig specifies Subject Alternative Names for a certificate (DNS names and IP addresses).

Key Type Default Description
dns-names list of string
ip-addresses list of string

services.exec[].config.acme-dns (type: maddy)

ACMEDNSConfig is maddy's own acme-dns client configuration, rendered directly into the generated maddy.conf's "tls.loader.acme" block. It is deliberately self-contained (not cross-referenced by name from the agent's top-level acme-dns account list) -- see ACMEDNSAccountConfig's doc comment in internal/cmd/agent/agent_config.go for why -- except for the password, which is never operator-configured on either side (see ACMEDNSPasswordLookup).

Key Type Default Description
enable boolean enable switches maddy from the default sibling-tunnel cert-extraction behavior to self-issuing its own certificate via dns-01.
email string email is the ACME account email maddy registers with. Defaults to the tunnel principal's email (the same source and precedent as tls-server.acme's own email default -- see sdk/agent/tunnel.BaseTunnelConfig.Update) if left empty.
server-url string server-url is the base URL of this agent's acme-dns API. Defaults to "http://127.0.0.1:8556" -- this agent's own "acme-dns.listen-address" default -- if left empty. Maddy's acmedns provider appends "/update" itself.
username string username and Subdomain name maddy's account on this agent's acme-dns API. Both default to maddy's MX hostname, the one name its certificate is for, and the agent creates that account itself, so neither needs setting. Set them to use an account from the top-level "acme-dns.accounts" list instead, which must then be for the MX hostname. The password is generated, never configured.
subdomain string

services.exec[].config.cert-source (type: maddy)

CertSourceConfig identifies exactly one tunnel via search.SearchOpts{Type, Name} -- the same way it's named under traffic.tunnels -- so a domain collision between two HTTPS tunnels can never make this ambiguous, unlike the domain-based fallback it replaces.

Key Type Default Description
type string
name string

traffic.tunnels[].config.smtp-domains[].records (type: coredns)

RecordsConfig configures the DNS records published for an SMTP domain.

Key Type Default Description
tls-rpt object
dkim object
mta-sts object
spf object Render
dmarc object Render
maddy-dane object Render
maddy-dkim object Render

traffic.tunnels[].config.authentication.github (type: file)

ServerConfig contains configuration for a GitHub authentication server.

Key Type Default Description
allow-insecure-http boolean
client-id string
client-secret string
config-file string config-file containing ClientID and ClientSecret
principals object

traffic.tunnels[].config.authentication.hmac (type: file)

ServerConfig contains configuration for an HMAC authentication server.

Key Type Default Description
allow-insecure-http boolean
shared-key string Inline shared key used to HMAC with value from HTTPHeader
signed-headers list of string HTTP Headers to include in the HMAC calculation.
timestamp-header string HTTP Header to use for the timestamp (default: X-Timestamp)
max-timestamp-diff duration Maximum allowed time difference for the timestamp (default: 5m)
max-future-timestamp-diff duration Maximum allowed time difference for future timestamps (default: 30s) This should be smaller than MaxTimestampDiff to prevent pre-signed replay attacks. A smaller value is appropriate since it only needs to account for clock skew.
max-request-size integer Maximum request size in bytes (default: 10 MB)

traffic.tunnels[].config.authentication.jwt (type: file)

ValidatorConfig contains configuration for a JWT token validator.

Key Type Default Description
issuer string issuer is the expected token "iss" claim. Signing keys are discovered from its JWKS endpoint. Required.
audiences list of string audiences lists the accepted values of the token "aud" claim. A token is accepted if it carries at least one of them.
signature_algorithm string signature_algorithm is a single accepted signing algorithm, for example "RS256". Ignored when SignatureAlgorithms is set.
signature_algorithms list of string signature_algorithms lists the accepted signing algorithms, for example "RS256", "ES256". Takes precedence over SignatureAlgorithm.
cache_ttl_seconds integer cache_ttl_seconds is how long, in seconds, discovered signing keys are cached. Defaults to 300 when unset or not positive.
allowed_clock_skew_seconds integer allowed_clock_skew_seconds is the tolerance, in seconds, applied to the token "exp", "nbf" and "iat" claims. Defaults to 60 when unset or not positive.
debug boolean debug enables debug logging of each token validation attempt and its outcome. Intended for troubleshooting.
claim_predicates map claim_predicates restricts which tokens are accepted by their claims. Each key is a claim name and its value is the required claim value; an array claim matches when it contains the value. All entries must match. Use the reserved keys "and" and "or", each holding a list of such maps, for nested combinations.

traffic.tunnels[].config.authentication.oidc (type: file)

OIDCServerConfig combines OIDC provider credentials with the login/session middleware settings (redirect-uri, cookies, login/logout paths) needed to complete a login when "type: oidc" is used as a server's sole auth gate.

Key Type Default Description
type string type selects a provider-specific behaviour. Accepted values are "github", "githubactions", "keycloak", "flyio" and "aws". Leave empty for a generic OIDC provider discovered from URL.
url string url is the OIDC issuer URL, for example "https://accounts.example.com". Provider metadata and signing keys are discovered from it.
keycloak-realm string keycloak-realm is the Keycloak realm name. It is only used when Type is "keycloak".
client-id string client-id is the OAuth 2.0 client identifier registered with the provider.
client-secret string client-secret is the OAuth 2.0 client secret, used for the client credentials flow. Set at most one of ClientSecret and ClientSecretFile.
client-secret-file string client-secret-file is the path to a file containing the client secret, for example a mounted container secret. Surrounding whitespace is trimmed. The file is read when the token source is built, not when the config is validated; an unreadable or empty file is an error. Set at most one of ClientSecret and ClientSecretFile.
audience string audience is the audience requested for issued tokens. It is required by platform identity providers such as "githubactions", "flyio" and "aws" and ignored by providers that do not support it.
token-file string token-file is the path to a file used to persist the interactive login token between runs. When set, the token is loaded from the file and refreshed with its refresh token once it expires.
tls-client object tls-client configures TLS for connections to the provider, such as a custom CA bundle.
scopes list of string
redirect-uri string
token-cookie object
state-cookie object
refresh-cookie object
token-expiry object
redirect-cookie object
id-token-cookie object
refresh-window duration
login-path string
logout-path string
allow-insecure-cookies boolean allow-insecure-cookies disables the default Secure attribute on session cookies, allowing them to be sent over plain HTTP. Session cookies carry live OAuth access and refresh tokens, so this must only be set for local HTTP development — never in production. Mirrors oidc.ValidatorConfig.AllowInsecureHMAC's explicit-opt-in shape.

traffic.tunnels[].config.routes[].config (type: attachment)

Config holds per-route configuration for the "attachment" handler type.

Key Type Default Description
max-attachment-bytes integer 26214400
root-directory string RootDirectory, if set, switches the handler from the default in-memory store to a disk-backed store rooted at this directory ("~" and environment variables are expanded). Attachments saved to the in-memory store do not survive a restart; a disk-backed store does.
path-template string {{.SenderDomain}}/{{.Year}}/{{.Month}} path-template controls the save-path directory hierarchy beneath RootDirectory. Only used when RootDirectory is set. See store.PathTemplateData for the available template fields.
subject-patterns list of object subject-patterns are matched against each attachment's message Subject; a match's named capture groups become additional path-template fields. Only used when RootDirectory is set. Tried before the built-in well-known vendor patterns (see DisableWellKnownSubjectPatterns), so a pattern here can override one of those by matching the same subject more specifically.
disable-well-known-subject-patterns boolean disable-well-known-subject-patterns turns off the built-in registry of well-known vendor subject-patterns (Stripe, AWS, Microsoft, GitHub, Xero), which is otherwise always available in addition to SubjectPatterns. Only used when RootDirectory is set.

traffic.tunnels[].config.routes[].config (type: dmarc)

Config holds per-route configuration for the "dmarc" mailrouter handler type. Domain and message-transfer limits are configured at the mailrouter tunnel level, not here — see internal/servers/mailrouter.Config.

Key Type Default Description
max-message-bytes integer 26214400
database-path string DatabasePath, if set, switches the handler from the default in-memory report store to a disk-backed SQLite store at this path ("~" and environment variables are expanded). Reports saved to the in-memory store do not survive a restart; a SQLite-backed store does, and also unlocks the additional analytics endpoints on the report resource (see resource.NewReportResource).

traffic.tunnels[].config.routes[].config (type: tls-rpt)

Config holds per-route configuration for the "tls-rpt" mailrouter handler type. Domain and message-transfer limits are configured at the mailrouter tunnel level, not here — see internal/servers/mailrouter.Config.

Key Type Default Description
max-message-bytes integer 26214400
database-path string DatabasePath, if set, switches the handler from the default in-memory report store to a disk-backed SQLite store at this path ("~" and environment variables are expanded). Reports saved to the in-memory store do not survive a restart; a SQLite-backed store does, and also unlocks the additional analytics endpoints on the report resource (see resource.NewReportResource).

traffic.tunnels[].config.smtp-domains[].records.tls-rpt (type: coredns)

Record represents a TLSRPT (TLS Reporting) DNS TXT record.

Key Type Default Description
version string
report-uri-aggregate list of string

traffic.tunnels[].config.smtp-domains[].records.dkim (type: coredns)

Record represents a DKIM DNS record.

Key Type Default Description
version string
key-type string
public-key string

traffic.tunnels[].config.smtp-domains[].records.mta-sts (type: coredns)

Record represents an MTA-STS DNS TXT record.

Key Type Default Description
version string
id string

traffic.tunnels[].config.smtp-domains[].records.spf (type: coredns)

Record represents an SPF DNS record.

Key Type Default Description
version string
mechanisms list of object
all boolean
all-qualifier string

traffic.tunnels[].config.smtp-domains[].records.dmarc (type: coredns)

Record represents a DMARC DNS record.

Key Type Default Description
version string
policy string
percent integer
report-uri-aggregate list of string
report-uri-failure list of string
subdomain-policy string
alignment-policy-dkim string
alignment-policy-spf string

traffic.tunnels[].config.smtp-domains[].records.maddy-dane (type: coredns)

MaddyDANERecord is a TLSA/DANE record derived from the certificate maddy serves for its MX hostname, in whichever of maddy's two certificate layouts its state directory holds (see maddyCertificatePath). It preserves the config schema (state-dir, port, auto-refresh, auto-refresh-period-seconds) maddy tunnel configs already use.

Key Type Default Description
state-dir string
port integer
auto-refresh boolean auto-refresh is rejected in a coredns tunnel's smtp-domains, which reads the certificate again every 30 seconds.
auto-refresh-period-seconds integer auto-refresh-period-seconds is rejected in a coredns tunnel's smtp-domains, which reads the certificate again every 30 seconds.

traffic.tunnels[].config.smtp-domains[].records.maddy-dkim (type: coredns)

MaddyDKIMRecord is a TXT record derived from the DKIM selector key file maddy writes for a domain. It preserves the config schema (state-dir, auto-refresh, auto-refresh-period-seconds) maddy tunnel configs already use.

Key Type Default Description
state-dir string
auto-refresh boolean auto-refresh is rejected in a coredns tunnel's smtp-domains, which reads the key file again every 30 seconds.
auto-refresh-period-seconds integer auto-refresh-period-seconds is rejected in a coredns tunnel's smtp-domains, which reads the key file again every 30 seconds.

CookieConfig configures a single session cookie's name, scope, and lifetime.

Key Type Default Description
name string
domain string
secure boolean
path string
max-age duration

traffic.tunnels[].config.routes[].config.subject-patterns[] (type: attachment)

SubjectPattern is one named regex matched against the message Subject.

Provider and Vendor are optional pattern-level metadata, not captured from the subject: Provider identifies the invoicing platform that sent the email (e.g. "stripe") and is always fixed per pattern. Vendor is the actual company being paid; set it here when the pattern's own vendor IS the provider (e.g. "Amazon Web Services" for an AWS pattern). Leave Vendor empty and capture a group named exactly "Vendor" in Pattern instead when the platform invoices on behalf of many different businesses (Stripe, Xero) — see extractSubjectFields for the precedence rule between the two.

Key Type Default Description
name string
provider string
vendor string
pattern string

traffic.tunnels[].config.smtp-domains[].records.spf.mechanisms[] (type: coredns)

Mechanism represents an SPF mechanism in a DNS record.

Key Type Default Description
qualifier string
name string
values list of string
value-list string