Skip to content

Agent Configuration Reference

The agent is configured via a YAML file (passed with --config). All top-level keys are described below.

Checking a config file

The agent refuses to start if its config file contains a key that matches no setting, such as a misspelled key or one that has been renamed, or a setting it would reject. It reports every problem at once, each with the key's full path:

Error: invalid configuration in agent.yaml:
traffic.tunnels[0].tls-server-config: unknown key
acme-dns.listen-address: "0.0.0.0:8556" must be a loopback address (e.g. 127.0.0.1:8556)

To check a file without starting the agent, run:

connect agent config validate --config agent.yaml

Without --config, it checks the file connect agent would load. The connect agent status, mail and share commands read the same file and reject the same unknown keys.

The same checks cover:

  • each tunnel's, exec's and mail route's own config: block, against its type;
  • each tunnel's and exec's type, which must be built in or provided by a plugin in the plugins directory;
  • tunnel names: no two tunnels of the same type may share a name, since depends-on and reloads identify a tunnel by its type and name; tunnels that register the same endpoint name set it as hostname instead;
  • the rules the server applies when a tunnel registers: a reverse tunnel's hostname (or its name when it has no hostname) and each of its extra-names must be a lowercase DNS name (or @ for the apex domain), and its subdomain, custom-domains, tags and network-acl must be valid, as must a forward tunnel's tags and network-acl;
  • connection settings: each endpoint must be a URL with a host, a forward tunnel's listen-address must be host:port, a tls-server block may set only one of acme, self-signed and local, and a certificate needs its key;
  • management.listen-address must be an IP address and port, a session-secret must be at least 32 bytes, and the interface may not run without authentication on a non-loopback address unless allow-unauthenticated-non-loopback is set;
  • a configured identity must have a way to get a token, and timeouts must not be negative;
  • every discovery.file file, whose problems are reported under its own path.

config validate reads and verifies plugin manifests but does not run any plugin. The config: blocks of tunnel types a plugin provides are checked by the plugin when it builds the tunnel, not by the agent.

Every key, and checking as you type

Agent config file keys lists every key an agent config file can set, generated from the code the agent loads its config with. connect agent config example prints an example file listing every key with its description and default, and connect agent config schema prints the JSON Schema of the file.

An editor can check a config file against the schema as you type. Add this line at the top of the file:

# $schema: https://dioad.github.io/connect/schema/agent.schema.json

The YAML language server (the VS Code YAML extension and other editors) and JetBrains IDEs read it. A file a discovery.file[] entry names uses discovery.schema.json in place of agent.schema.json. The schema checks each key and the type of each value, including each built-in type's config: block; connect agent config validate also checks the rules above.


Top-Level Structure

log:         # Logging settings
identity:    # Agent OIDC identity / credentials
management:  # Management UI and API
acme-dns:    # Local acme-dns-compatible API for external ACME clients
tunnel-defaults:  # Defaults applied to all tunnels
traffic:     # Tunnel definitions (reverse and forward)
services:    # Exec services launched alongside tunnels
discovery:   # Dynamic tunnel discovery (e.g. Docker)
plugins:     # External tunnel server plugins
status:      # The status file `connect agent status` reads

log — Logging

Key Type Default Description
level string warn Log level: trace, debug, info, warn, error, fatal, panic
file string (stdout) Path to log file. Supports ~ expansion. Omit to log to stdout only.
max-size int 100 Max log file size in MB before rotation.
max-backups int 0 Max number of rotated log files to retain (0 = keep all).
max-age int 0 Max number of days to keep rotated log files (0 = no limit).
use-local-time bool false Use local time in rotated filenames instead of UTC.
compress bool false Gzip-compress rotated log files.

Example:

log:
  level: info
  file: ~/.config/dioad/connect/logs/agent.log
  max-size: 50
  max-backups: 5
  max-age: 30
  compress: true


identity — Agent Identity (OIDC)

Configures how the agent authenticates itself to the Connect service.

Key Type Description
type string Provider type: keycloak, github, flyio, githubactions, aws
url string OIDC issuer URL (not required for machine-identity types like flyio)
keycloak-realm string Keycloak realm name (only for type: keycloak)
client-id string OAuth2 client ID
client-secret string OAuth2 client secret
client-secret-file string File to read the client secret from, such as a mounted secret; surrounding whitespace is trimmed. Use instead of client-secret, not with it.
token-file string Path to a file where the agent stores/reads cached tokens. Supports ~ expansion.
audience string Optional token audience override
tls-client object TLS Client config for connecting to the OIDC provider

Example (Keycloak):

identity:
  type: keycloak
  url: https://auth.lab.dioad.net
  keycloak-realm: dioad-labs
  client-id: connect-cli
  token-file: ~/.config/dioad/connect/auth.yaml

Example (GitHub):

identity:
  type: github
  client-id: YOUR_GITHUB_CLIENT_ID
  client-secret: YOUR_GITHUB_CLIENT_SECRET
  token-file: ~/.config/dioad/connect/auth.yaml


management — Management Interface

Configures the agent's local management HTTP server: the web UI, the tunnel-control API and status. Its login is the local password in management.local-auth; the management interface has no OIDC sign-in.

Key Type Description
listen-address string Address and port to listen on, e.g. 0.0.0.0:4445. No default — omit it to run headless with no management server at all (e.g. connect agent share). On first run with no config file at all, connect agent self-bootstraps a minimal config with this set to 127.0.0.1:4444 (see Quickstart).
operations-listen-address string Optional second listener serving /health/live, /health/ready and /metrics with no authentication, e.g. 0.0.0.0:4446, for a platform health check and metrics scraper that cannot log in. Needs listen-address, and its own port. See below.
session-secret string Secret for signing session cookies. At least 32 bytes. Randomly generated at startup if omitted (sessions don't survive restarts).
session-secret-file string File holding the session secret, for secrets mounted as files. Set at most one of session-secret and session-secret-file.
local-auth-disabled bool Explicitly opt out of local basic-auth (see below). Defaults to false.
local-auth object Local HTTP Basic authentication for the management interface (see below)
allow-unauthenticated-non-loopback bool Explicit opt-in to start listen-address on a non-loopback address with no authentication at all (local-auth-disabled: true). Defaults to false: without it, that combination refuses to start, since the full tunnel-control API would otherwise be reachable by anyone who can reach the listener. Only set this when a trusted TLS-terminating proxy or equivalent network control already sits in front of this listener.

The management server also serves /health/live and /health/ready without credentials, so a container or orchestrator probe can use them. /health/ready answers 503 while no configured tunnel is connected, an exec has given up waiting for its dependencies, or the management or acme-dns server has stopped. If the management or acme-dns server dies the agent shuts down and exits with an error, so a supervisor restarts it.

On a non-loopback listen-address, /metrics and /status need the same credentials as the rest of the interface; on a loopback address they stay open. The listener serves plain HTTP, so basic-auth credentials cross the network in cleartext unless a TLS-terminating proxy sits in front of it.

A scraper that cannot log in, such as a platform's metrics collector, can use operations-listen-address instead. That listener serves the management server's /health/live, /health/ready and /metrics (including agent_tunnel_state and agent_tunnel_connect_total) with no authentication, and nothing else: no API, UI, /status or pprof. The management interface keeps its login. Bind it where only the platform can reach it, such as a private network. It starts before the other services and stops after them, so health stays answerable through startup and shutdown.

management:
  listen-address: 0.0.0.0:4444
  operations-listen-address: 0.0.0.0:4446

management.local-auth — Local Basic Authentication

This is the management interface's login: a local username and password, backed by a bcrypt-hashed, htpasswd-style credentials file. It's separate from the agent's own Dioad Connect identity (identity, above), which the agent uses to authenticate to the Connect server and is never used to sign in to the management interface.

By default, when management.listen-address is set, the agent refuses to start unless the credentials file exists and contains at least one user - set management.local-auth-disabled: true to run without local authentication instead, for example when a reverse proxy in front of it already handles authentication. On a non-loopback listen-address that also needs allow-unauthenticated-non-loopback: true.

By default a client address that sends ten wrong passwords within five minutes is refused with 429 for the next five minutes, even if it then sends the right one; throttle changes or disables this. Behind a reverse proxy every request shares the proxy's address, so the lockout applies to everyone using that proxy.

Use connect agent management set-password to create or update the credentials file interactively - it prompts for a username and password and writes the bcrypt hash. connect agent init offers to set this up as part of its interactive wizard.

Key Type Description
htpasswd-file string Path to the credentials file (user:bcrypt-hash per line). Supports ~ expansion. Defaults to ~/.config/dioad/connect/htpasswd.
realm string HTTP Basic auth realm shown in the browser's credential prompt. Defaults to Dioad Connect.
allow-insecure-http bool Reserved for future use; not currently enforced. Local basic-auth credentials transit in cleartext unless listen-address is loopback or something is TLS-terminating in front of it.
throttle object Failed-login lockout per client address (see below)

management.local-auth.throttle:

Key Type Description
disabled bool Turn the lockout off. Defaults to false.
max-failures int Wrong passwords allowed within window before the address is locked out. Defaults to 10.
window duration How long a wrong password counts towards max-failures. Defaults to 5m.
lockout duration How long a locked-out address is refused with 429. Defaults to 5m.

Example:

management:
  listen-address: 127.0.0.1:4444
  local-auth:
    htpasswd-file: ~/.config/dioad/connect/htpasswd


acme-dns — Local ACME-DNS API

Configures an optional, agent-local HTTP API implementing the small part of the acme-dns protocol an ACME client needs to drive a DNS-01 challenge (POST /update). It exists so an external ACME client running as a sibling services.exec process (e.g. maddy, via its built-in acmedns libdns provider — see services.exec[].config.acme-dns below) can publish its own DNS-01 challenge values into the same ChallengeStore a coredns tunnel already answers challenge queries from, instead of depending on a sibling tunnel's certificate lifecycle. See doc/architecture/agent/future/MADDY_LIBDNS_ACME_DESIGN.md for the full design rationale. Optional: the API runs only when something uses it, which is either an entry in accounts or a maddy exec with config.acme-dns.enable. There is no separate enable flag. A maddy exec doesn't need an entry in accounts: the agent creates maddy's account itself, for its MX hostname.

A coredns tunnel must be declared under traffic.tunnels — it's what actually answers the DNS-01 challenge queries this API's accepted updates get published to, and config validation rejects startup without one: with acme-dns.accounts configured but no "coredns" tunnel found in traffic.tunnels when accounts is non-empty, and with services.exec: has a "maddy" entry with config.acme-dns.enable but no "coredns" tunnel found in traffic.tunnels when a maddy exec uses it. listen-address must be a loopback address (e.g. 127.0.0.1:8556) — also enforced at validation time, not just a recommendation — unlike a coredns tunnel's own DNS listener, this HTTP API is never bridged across the reverse tunnel, and that is what makes the internally generated per-account credentials below a safe authentication mechanism instead of needing something like TSIG.

Key Type Description
listen-address string Loopback address and port to listen on. Defaults to 127.0.0.1:8556 if omitted.
accounts []object Identities external ACME clients authenticate as (see below). A maddy exec doesn't need one.

acme-dns.accounts

Each entry maps one identity to exactly one target domain: an accepted update publishes _acme-challenge.<domain>. into the agent's shared ChallengeStore.

Key Type Description
username string Required. Sent as the X-Api-User header by the ACME client
subdomain string Required. Must match the value the ACME client submits in its update body
domain string Required. The real domain this account publishes challenge records for

There is no password field: each account's password is generated internally (crypto/rand), fresh every time the agent starts, and is never written to any config file on either side. A co-located client configured with the matching username (e.g. services.exec[].config.acme-dns below) picks it up automatically at render time. An entry here is only needed for a client other than the maddy exec, or to give maddy's account a name of your choosing.

Example:

acme-dns:
  accounts:
    - username: maddy
      subdomain: mail-primary
      domain: mail.example.com


tunnel-defaults — Default Tunnel Settings

Defaults applied to every tunnel that does not set the field explicitly. Per-tunnel values always override defaults.

Key Type Description
endpoint string Default Connect server endpoint URL, e.g. https://connect.dioad.dev/connect/https
subdomain string Default subdomain for reverse tunnels
tls-server object TLS Server config applied to reverse tunnels by default
tls-client object TLS Client config applied to tunnels by default
network-acl object Network ACL applied to reverse tunnels by default

Example:

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


traffic — Tunnels

Defines the tunnels the agent should establish.

traffic.tunnels — Reverse Tunnels

Expose a local service through the Connect server to the internet. Each entry is a reverse tunnel.

Key Type Description
name string Required. Tunnel name, unique among tunnels of its type. It is also the primary subdomain label unless hostname is set.
hostname string Primary subdomain label to register in place of name. Set it when several tunnels of one type serve the same host.
type string Required. Tunnel service type (e.g. hello, tcp, httpreverseproxy, file, coredns, mailsupport, mta-sts, mailrouter, socks5)
endpoint string Connect server endpoint URL. Overrides tunnel-defaults.endpoint.
subdomain string Custom subdomain label. Overrides tunnel-defaults.subdomain.
extra-names []string Additional subdomain aliases for this tunnel
custom-domains []string Fully-qualified custom domain names for this tunnel
publish-public-ip string Publish a specific public IP for this tunnel
tags []string Tags used by services in services.exec for dependency matching
tls-server object TLS Server config
tls-client object TLS Client config
network-acl object Network ACL
dns object DNS records this tunnel should publish
config object Tunnel-type-specific configuration (decoded by the server-side plugin)

Example — simple hello tunnel:

traffic:
  tunnels:
    - type: hello
      name: hello
      endpoint: https://connect.dioad.dev/connect/https
      extra-names:
        - goodbye
      tls-server:
        acme:
          cache-directory: .autocert
      config:
        custom-message: "Hello {{ .Principal }}"
      tags:
        - hello

Example — TCP proxy (SSH):

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

Example — HTTP reverse proxy:

traffic:
  tunnels:
    - type: httpreverseproxy
      name: proxy
      tls-server:
        acme:
          cache-directory: .autocert
      config:
        target-url: http://localhost:8080

Example — SOCKS5 exit for outbound mail:

A socks5 tunnel connects out on behalf of whoever reaches it through the server, so an exit other principals use should limit where it connects. It only ever accepts SOCKS CONNECT; BIND and UDP ASSOCIATE are refused.

traffic:
  tunnels:
    - type: socks5
      name: socks5
      endpoint: https://connect.example.com/connect/private-socks5
      config:
        # Only the SMTP, SMTPS and submission ports.
        allowed-ports: [25, 465, 587]
        # Refuse loopback, private, link-local (cloud metadata) and other
        # non-public addresses, after resolving any hostname.
        block-private-destinations: true
        # At most 50 connections per tenant in 24 hours. The connection
        # that goes over suspends the tenant until its 24 hours end, or for
        # suspend-for if that is longer.
        quota:
          connections-per-day: 50
          suspend-for: 24h

Refused requests are logged as socks request refused with the reason. See the generated reference for every key.

connect-server tells the exit which tenant each connection belongs to: the principal of the forward tunnel it arrived on, sent in the PROXY protocol header. Access logs and refusals carry it as principal, so traffic through a shared exit can be traced to a tenant.

quota limits each tenant's connections. The exit can't see what a tenant sends, only how many connections it opens, so on a mail exit the limit counts delivery attempts, not messages. A retry, or a fallback to a second MX host, counts as another connection. Counts are kept in memory: they reset when the agent restarts, and each exit instance counts separately. With a quota set, the exit refuses connections that don't name a tenant, so set one only behind a connect-server that sends the principal. A tenant's suspension is logged once, as principal suspended for exceeding connection quota.

mailrouter — Inbound Email Router

mailrouter is a reverse-tunnel type that runs an SMTP server and routes each incoming message to one or more pluggable handlers, based on the local-part of the RCPT TO recipient (e.g. dmarc@, tls-rpt@, invoices@). Each route is independently configured and backed by a registered handler type — today dmarc (parses DMARC aggregate reports, RFC 7489), tls-rpt (parses SMTP TLS Reports, RFC 8460 — the delivery-failure reporting format for MTA-STS and DANE), and attachment (files any email attachment for later retrieval).

mailrouter's config block:

Key Type Default Description
domain string tunnel's endpoint domain Domain the SMTP server answers as. Falls back to the tunnel's resolved endpoint domain if omitted.
limits.max-message-bytes int64 26214400 (25 MiB) Maximum size of an inbound message, enforced at the SMTP transfer level.
limits.max-recipients int 50 Maximum RCPT TO recipients per message.
routes []object (see below) List of recipient routes. If omitted entirely, a single catch-all route to the dmarc handler type is used — this preserves the behavior of the original dmarc tunnel type with no config changes beyond the type: rename.

No authentication on the admin API or dashboard. Every route's admin-API resource, and the reporting dashboard once mounted (see below), are unauthenticated by design. They're reachable only through the agent's own local management API (management.listen-address above), never published through connect-server, so the agent host's own access control (who can reach that listener at all) is the trust boundary today — the same model mailsupport's extension UI already relies on. A real authn/authz layer for this surface is a future consideration, not necessarily JWT/IdP-based: the agent may have no network path to an IdP at all, which is exactly why nothing OIDC-shaped is wired in yet. This changes if the agent's management API is ever made reachable somewhere an untrusted party could also reach it (e.g. bound to a non-loopback address without another access-control layer in front of it, or ever proxied through connect-server) — don't do that without adding real auth first.

Each entry in routes:

Key Type Description
name string Admin-API mount name for this route's extension endpoints (e.g. /extensions/<tunnel>/api/<name>/...). Defaults to type. Only relevant when 2+ routes expose an admin API — with exactly one, its endpoints are exposed without a name segment (/extensions/<tunnel>/api/...).
recipients []string Recipient local-parts this route matches (before the @), compared case-insensitively. Omit or leave empty for a catch-all route that matches any recipient not claimed by a more specific route.
type string Required. Handler type: dmarc, tls-rpt, or attachment.
config object Handler-type-specific configuration, decoded by that handler.

Recipient matching rules: - A recipient-scoped route always takes priority over a catch-all route for matching recipients. - If a RCPT TO recipient doesn't match any scoped route and no catch-all route is configured, the SMTP server rejects it at RCPT TO time with a 550 error.

Handler type dmarc config:

Key Type Default Description
max-message-bytes int64 26214400 (25 MiB) Guards against decompression-bomb DMARC report attachments. Independent of the tunnel-level limits.max-message-bytes.
database-path string (unset) If set, reports are persisted to a SQLite database at this path instead of the default in-memory store. ~ and environment variables are expanded; the parent directory is created if missing. In-memory reports are lost on restart; disk-backed reports are not, and unlock the analytics endpoints below.

Exposes GET /api/reports and GET /api/reports/{reportID} under its admin-API mount regardless of backend (see the name field above for how this shifts to /api/<name>/reports when 2+ routes are configured). When database-path is set, these additional endpoints are also mounted:

Endpoint Description
GET /api/reports/list?domain=&from=&to=&disposition=&offset=&limit= Paginated report list, each entry carrying a surrogate id (unambiguous even when report_id collides across reporting orgs — see below).
GET /api/reports/summary?domain=&from=&to=&disposition= Report count, total messages, pass/fail counts, pass rate.
GET /api/reports/timeseries?domain=&from=&to= Daily pass/fail message-count buckets.
GET /api/reports/dispositions?domain=&from=&to=&disposition= Message counts broken down by DMARC disposition (none/quarantine/reject).
GET /api/reports/top-sources?domain=&from=&to=&limit= (default limit 10) Source IPs with the highest total message count.
GET /api/reports/failing-domains?domain=&from=&to=&limit= (default limit 10) Header-From domains with the highest total failing-message count.
GET /api/reports/domains Distinct policy-published domains seen across all stored reports.

from/to accept a full RFC3339 timestamp or a bare YYYY-MM-DD date. report_id is only unique per reporting org per RFC 7489; GET /api/reports/{reportID} resolves ambiguously (most-recently-saved match) across orgs when two saved a report under the same report_id — the list/id-keyed endpoints above don't have this ambiguity.

Handler type tls-rpt config:

Parses SMTP TLS Reports (RFC 8460) — the mechanism MTA-STS and DANE use to report TLS delivery failures back to a domain owner (MTA-STS itself, RFC 8461, defines no report format of its own). Reports are gzip-compressed JSON per the spec (no zip variant); config and endpoints otherwise mirror dmarc exactly, substituting TLS session/policy concepts for DMARC's disposition/DKIM/SPF ones:

Key Type Default Description
max-message-bytes int64 26214400 (25 MiB) Guards against decompression-bomb TLS-RPT report attachments. Independent of the tunnel-level limits.max-message-bytes.
database-path string (unset) If set, reports are persisted to a SQLite database at this path instead of the default in-memory store. Same expansion/creation and analytics-unlock behavior as dmarc's database-path.

Exposes GET /api/reports and GET /api/reports/{reportID} under its admin-API mount regardless of backend (see the name field above for how this shifts to /api/<name>/reports when 2+ routes are configured). When database-path is set, these additional endpoints are also mounted:

Endpoint Description
GET /api/reports/list?domain=&from=&to=&offset=&limit= Paginated report list, each entry carrying a surrogate id.
GET /api/reports/summary?domain=&from=&to= Report count, total TLS sessions, success/failure counts, success rate.
GET /api/reports/timeseries?domain=&from=&to= Daily successful/failed TLS session-count buckets, summed from each policy's reported totals.
GET /api/reports/failure-reasons?domain=&from=&to=&limit= (default limit 10) Failed-session counts broken down by RFC 8460 failure-reason-code (e.g. certificate-expired, starttls-not-supported).
GET /api/reports/top-mx?domain=&from=&to=&limit= (default limit 10) Receiving MX hostnames with the highest total failed-session count.
GET /api/reports/domains Distinct policy domains seen across all stored reports.

domain here filters on a report's policy domain, not the report itself — a single TLS-RPT report can cover multiple policy domains.

The mail delivery health dashboard. When at least one configured route's handler exposes a reporting SPA (today: dmarc and tls-rpt), it's served at /extensions/<tunnel>/ui — the same path the agent management dashboard's "Extension" tab embeds automatically as a Web Component (see doc/sdk/EXTENSION_AUTHORING.md). One dashboard covers every dashboard-capable route on the tunnel: an Overview tab with combined pass/fail and TLS success/failure timelines, plus per-handler-type tabs with the breakdowns/tables above rendered as charts and paginated lists. The dashboard relies entirely on the analytics endpoints above, so database-path must be set on every route you want represented in it — without it, the dashboard still loads but its data requests 404 against the in-memory store's unmounted analytics routes. Its browser JS calls those endpoints with plain axios requests and no auth of its own, consistent with the "no authentication" note above; see that note before ever exposing this surface beyond the agent's local management API.

Handler type attachment config:

Key Type Default Description
max-attachment-bytes int64 26214400 (25 MiB) Maximum size of a single stored attachment.
root-directory string (unset) If set, attachments are saved to disk under this directory instead of the default in-memory store. ~ and environment variables are expanded. In-memory attachments are lost on restart; disk-backed attachments are not.
path-template string {{.SenderDomain}}/{{.Year}}/{{.Month}} Go template controlling the save-path directory hierarchy beneath root-directory. Only used when root-directory is set. Each attachment is additionally saved under its own generated ID beneath the rendered path, so the template need not guarantee uniqueness. The default groups by sending organization and month — the common case of recurring monthly mail (e.g. vendor invoices), where the exact day or sending mailbox rarely matters.
subject-patterns []object (none) Named regexes matched against the message Subject (see below); a match's named capture groups become additional path-template fields. Only used when root-directory is set. Tried in order, before the built-in well-known vendor patterns, so a pattern here can override one of those by matching the same subject more specifically.
disable-well-known-subject-patterns bool false Disables the built-in registry of well-known vendor subject-patterns (Stripe, AWS, Microsoft, GitHub, Xero — see below), which is otherwise always available in addition to subject-patterns.

Exposes GET /api/attachments and GET /api/attachments/{id} under its admin-API mount. Stored attachments are always served with Content-Type: application/octet-stream and X-Content-Type-Options: nosniff regardless of the sender-declared content type, to prevent a malicious attachment from being rendered instead of downloaded.

path-template fields (all pre-sanitized for safe use as path components — separators and other unsafe characters are replaced, so a crafted sender address or filename cannot escape the configured directory):

Field Description
.Year, .Month, .Day The attachment's received date (UTC), e.g. 2026, 03, 05.
.Sender The full envelope MAIL FROM address.
.SenderDomain The part of .Sender after the @.
.SenderLocalPart The part of .Sender before the @ (the RFC 5321/5322 "local-part").
.ID The attachment's generated ID (a UUID) — always safe to use verbatim.
.Filename The sender-declared attachment filename.
.ContentType The sender-declared MIME type.

Subject-patterns. For recurring vendor mail (invoices, receipts), the message Subject is often more useful to group by than the raw envelope sender: Subject text typically survives forwarding intact, while the envelope sender becomes the forwarder's own mailbox once a human forwards the mail. Each entry in subject-patterns:

Key Type Description
name string Identifies this pattern in debug logs when it matches.
pattern string An RE2 regex matched anywhere in the Subject (not anchored — a "Fwd: " or "Re: " prefix does not prevent a match). Named capture groups, e.g. (?P<InvoiceID>[0-9]+), become additional path-template fields.
provider string Fixed value for the .Provider field when this pattern matches — the invoicing platform that sent the email (e.g. stripe). Always fixed per pattern, never captured.
vendor string Fixed value for the .Vendor field when this pattern matches and its pattern does not itself capture a group named Vendor. Set this when the pattern's own vendor is the provider (e.g. Amazon Web Services for an AWS pattern). Leave unset and capture a Vendor group in pattern instead when the platform invoices on behalf of many different businesses (Stripe, Xero) — a captured Vendor always takes precedence over a fixed one.

Patterns are tried in order; the first match wins, and all patterns' capture groups are added into the fields available to path-template alongside four canonical, always-available fields (empty until a matching pattern populates them):

Field Description
.Provider The invoicing platform, from a pattern's fixed provider.
.Vendor The actual company being paid — fixed for a pattern whose platform is the vendor, captured otherwise.
.AccountID An account-level numeric/alphanumeric identifier, when a pattern captures a group named exactly AccountID.
.AccountAlias An account-level alias/slug, when a pattern captures a group named exactly AccountAlias.

A capture group must not use the same name as any of the fields in the path-template fields table above (.Sender, .Year, .ID, etc.) or Provider — this fails validation at agent startup, alongside a path-template typo. A Subject that matches no configured pattern, or a matched pattern that leaves some field unpopulated, is not an error: the attachment still saves, just with that field rendering as an empty path segment.

Built-in well-known vendor patterns. Unless disable-well-known-subject-patterns: true is set, these patterns are always available in addition to any configured subject-patterns (which are tried first, so a configured pattern can override one of these by matching the same subject more specifically):

Provider Vendor Captures Example Subject
stripe captured ReceiptID Your receipt from Anthropic, PBC #2661-3629-7085
aws Amazon Web Services AccountID, InvoiceID Amazon Web Services Invoice Available [Account: 205644708149] [Invoice ID: EUINGB26-3287944]
microsoft Microsoft InvoiceID Your Microsoft invoice G169618693 is ready
github GitHub InvoiceID, AccountAlias GitHub Invoice INV143876857 - dioad
xero captured AccountID, InvoiceID Invoice #ADREA/39095 from Cooper Parry Advisory Limited is due

Example — group by the actual company being paid, regardless of billing platform:

routes:
  - recipients: ["invoices"]
    type: attachment
    config:
      root-directory: ~/mail-attachments
      path-template: "{{.Vendor}}/{{.Year}}/{{.Month}}"
      subject-patterns:
        - name: acme-portal-invoice
          provider: acme-billing
          pattern: 'ACME Billing Portal: Invoice (?P<InvoiceID>[0-9]+) for (?P<Vendor>.+)'

On disk, each attachment's raw bytes are saved under its own original filename where safely possible, alongside a meta.json sidecar holding its metadata. A filename that would collide with meta.json (case-insensitively, so this holds on case-insensitive filesystems too) is encoded safely instead of overwriting or being mistaken for the sidecar.

Example — disk-backed attachment storage:

routes:
  - recipients: ["invoices"]
    type: attachment
    config:
      max-attachment-bytes: 10485760
      root-directory: ~/mail-attachments
      path-template: "{{.SenderDomain}}/{{.Year}}/{{.Month}}"

Example — zero-config, backward-compatible with the original dmarc tunnel type:

traffic:
  tunnels:
    - type: mailrouter
      name: dmarc
      endpoint: https://connect.dioad.dev/connect/https
      tls-server:
        acme:
          cache-directory: .autocert
      dns:
        mx:
          - priority: 10
      config:
        limits:
          max-message-bytes: 10485760
          max-recipients: 10
        # no "routes:" key -> single catch-all route to "dmarc", any recipient accepted

Example — multiple recipient-routed handlers:

traffic:
  tunnels:
    - type: mailrouter
      name: mail
      endpoint: https://connect.dioad.dev/connect/https
      tls-server:
        acme:
          cache-directory: .autocert
      dns:
        mx:
          - priority: 10
      config:
        limits:
          max-message-bytes: 10485760
          max-recipients: 10
        routes:
          - recipients: ["dmarc"]
            type: dmarc
            config:
              max-message-bytes: 10485760
          - recipients: ["invoices"]
            type: attachment
            config:
              max-attachment-bytes: 10485760

Example — DMARC + TLS-RPT with SQLite persistence and the reporting dashboard:

traffic:
  tunnels:
    - type: mailrouter
      name: mail
      endpoint: https://connect.dioad.dev/connect/https
      tls-server:
        acme:
          cache-directory: .autocert
      dns:
        mx:
          - priority: 10
      config:
        routes:
          - recipients: ["dmarc"]
            type: dmarc
            config:
              database-path: ~/mail-reports/dmarc.sqlite
          - recipients: ["tls-rpt"]
            type: tls-rpt
            config:
              database-path: ~/mail-reports/tls-rpt.sqlite
# Dashboard at /extensions/mail/ui covers both routes; each route's admin
# API is mounted at /extensions/mail/api/<name>/... (2+ routes -> aggregate
# mount, per the `name` field above). Unauthenticated -- see the note above.


traffic.forward-tunnels — Forward Tunnels

Pull remote traffic from the Connect server down to a local listener. Each entry is a forward tunnel.

Key Type Description
name string Required. Tunnel name
type string Required. Tunnel type (e.g. socks5)
endpoint string Connect server endpoint URL
listen-address string Local address and port to listen on, e.g. 0.0.0.0:1080
tags []string Tags for dependency matching
tls-server object TLS Server config
tls-client object TLS Client config
network-acl object Network ACL
config object Tunnel-type-specific configuration

Example — SOCKS5 forward tunnel:

traffic:
  forward-tunnels:
    - type: socks5
      name: mailsocks
      endpoint: https://connect.dioad.dev/connect/socks5
      listen-address: 0.0.0.0:1080
      tags:
        - dns/spf

The dns/spf tag tells the agent's coredns tunnel to publish this forward tunnel's exit addresses in the SPF record.

Don't give your own tunnels tags starting with dioad/. That prefix is for tunnels Dioad manages, and a server that reserves it refuses any other tunnel that asks for one, with 403 Forbidden.


services — Exec Services

Managed processes launched and supervised by the agent alongside tunnels.

services.exec

A list of processes to run.

Key Type Description
name string Required. Service name
type string Required. Service type (e.g. maddy)
command string Path to the executable
args []string Command-line arguments. Supports Go template syntax (e.g. {{ .ConfigFile }}).
environment map Environment variables to set for the process
working-directory string Working directory for the process
tags []string Tags for this service
config map Service-type-specific configuration passed to the service plugin
depends-on []object Tunnels that must be established before this service starts (see below)
dependency-timeout duration Max time to wait for depends-on to be met before logging an error and marking the exec as timed out. Zero uses the manager's default.

services.exec[].depends-on

Key Type Description
name string Name of the tunnel this service depends on
type string Type of the tunnel (e.g. mailsupport, tcp, coredns)
service-type string Service type qualifier for disambiguating tunnels with the same name (e.g. imap, smtp, submission)

maddy: the client's real address

maddy's smtp, submission and imap listeners are fed by tcp tunnels, so by default every connection reaches maddy from the agent on loopback, and SPF, DNSBL checks and Received: headers see 127.0.0.1. Set proxy-protocol-version: 2 on those tcp tunnels to pass the real client address on:

traffic:
  tunnels:
    - type: tcp
      name: mx-smtp
      hostname: mx
      endpoint: https://connect.dioad.dev/connect/smtp
      config:
        target-address: 0.0.0.0:26
        proxy-protocol-version: 2

maddy's config follows each tunnel: a listener whose tunnel sends a PROXY header reads it, trusting loopback only, and terminates TLS after it. Leave the setting off and maddy expects TLS straight away, as before.

services.exec[].config.acme-dns — maddy: self-issued certificate via ACME-DNS

Optional, opt-in alternative to maddy's default behaviour of extracting a certificate from a sibling HTTPS tunnel's autocert cache. When enabled, maddy obtains its own certificate directly via dns-01, using its built-in acmedns libdns provider against this agent's own acme-dns API (requires maddy to be built with the libdns_acmedns build tag). See doc/architecture/agent/future/MADDY_LIBDNS_ACME_DESIGN.md.

Key Type Description
enable bool Switch from the default sibling-tunnel cert extraction to self-issuance
email string ACME account email maddy registers with. When omitted, the email of the agent's identity, which the server sends with each tunnel, the same default tls-server.acme.email itself uses. A value set here takes precedence.
server-url string Base URL of this agent's acme-dns API. Defaults to http://127.0.0.1:8556 if omitted, matching acme-dns.listen-address's own default.
username string Optional. Defaults to maddy's MX hostname. Set it, with subdomain, to use an acme-dns.accounts[] entry, which must be for the MX hostname.
subdomain string Optional. Defaults to maddy's MX hostname.

The agent creates maddy's account on its acme-dns API itself, for the MX hostname of the smtp tunnel maddy serves (mx.<domain>), when maddy's config is rendered, so nothing in this block names a domain and the same config works for any agent. There is no password field: the account's password is generated when the account is created. A config that sets acme-dns.enable: true but whose username names an acme-dns.accounts[] entry for another domain, or that has no email to register with, fails config rendering with a clear error rather than producing a maddy.conf with no working credentials.

The DANE record for mx is derived from whichever certificate maddy has written most recently, so it follows maddy when it switches between this and a cert-source.

Example (minimal — everything but enable defaults):

services:
  exec:
    - name: maddy
      type: maddy
      command: ~/Code/go/src/github.com/dioad/maddy/build/maddy
      args:
        - "--config"
        - "{{ .ConfigFile }}"
        - run
      depends-on:
        - type: mailsupport
          name: mx
        - type: tcp
          name: mx-imap
          service-type: imap
        - type: tcp
          name: mx-submission
          service-type: submission
        - type: coredns
          name: ns
        - type: socks5
          name: mailsocks
      config:
        state-dir: ~/maddy/maddy-state
        runtime-dir: ~/maddy/maddy-runtime
        debug: true
        io-debug: false
        enable-socks5: true
        acme-dns:
          enable: true

services.exec[].config.cert-source — maddy: disambiguate the default certificate lookup

Only relevant when acme-dns.enable is not set (the default): maddy's default certificate source is found by searching for the one HTTPS tunnel serving the same domain as the mail listener. If two HTTPS tunnels happen to serve the same domain, that search is ambiguous and config rendering fails with an error listing every colliding tunnel's type/name. Set cert-source to name the intended tunnel explicitly and skip the search entirely.

Key Type Description
type string Type of the tunnel to extract the certificate from (e.g. reverse, mta-sts)
name string Name of that tunnel

type and name must be set together, or both left unset to keep the default domain-based search. This has no effect when acme-dns.enable is set — maddy issues its own certificate in that mode and no lookup happens at all.

Example:

config:
  cert-source:
    type: mta-sts
    name: mx


discovery — Dynamic Tunnel Discovery

Configures sources that automatically create tunnels from discovered services.

discovery.docker

Watch a Docker daemon for labelled containers and create tunnels automatically.

Key Type Description
socket string Docker socket path, e.g. unix:///var/run/docker.sock
label-prefix string Container label prefix to watch for tunnel configuration
use-container-name bool Use the container name as the tunnel name
allowed-types list Tunnel types a container label may select. Default: httpreverseproxy, tcp
allowed-endpoint-hosts list Hosts a tunnel.endpoint label may name, besides the default endpoint's host. Default: none
allow-custom-targets bool Let target-url / target-address labels point somewhere other than a port the container exposes. Default: false
defaults object TunnelConfigDefaults applied to discovered tunnels

Example:

discovery:
  docker:
    - socket: unix:///var/run/docker.sock
      label-prefix: dioad.connect
      use-container-name: true
      defaults:
        endpoint: https://connect.dioad.dev/connect/https
        tls-server:
          acme:
            cache-directory: .autocert

A container whose labels describe a tunnel the agent would reject, such as one of an unknown type or with a config key its type does not have, is skipped and the problem is logged; the agent and its other tunnels keep running.

Container labels are untrusted input

Anyone who can start a container, or publish an image the host pulls, can set its labels, and Docker merges an image's LABEL instructions into the container's labels. The agent therefore treats labels as a request, not an instruction, and skips (and logs) a container whose labels:

  • select a tunnel type outside allowed-types;
  • set tunnel.endpoint to a host other than the default endpoint's host or one in allowed-endpoint-hosts, because the agent presents its identity token to that endpoint;
  • set target-url or target-address to anything but the container's own address, unless allow-custom-targets is true: with the agent on the Docker host that is loopback and a port the container publishes on the host; with use-container-name: true it is the container's name and one of its container ports. Link-local addresses, which include cloud metadata services, are always rejected. A target the agent infers itself from the container's ports is not checked.

Widen these only for sources you control. A tcp:// or http:// socket sends container metadata over an unencrypted connection and logs a warning; prefer the local Unix socket.

discovery.file

Load tunnels from a separate YAML file (under that file's own traffic: key) and watch it for changes — editing the file takes effect without restarting the agent. The agent's own traffic: block is always available this way too, as an implicit entry watching the main config file itself; discovery.file is for additional files, or for keeping tunnel definitions out of the main config entirely.

Key Type Description
path string YAML file to load tunnels from and watch for changes
defaults object TunnelConfigDefaults applied to tunnels loaded from this file

Example:

discovery:
  file:
    - path: /etc/dioad/connect/tunnels.yaml
      defaults:
        endpoint: https://connect.dioad.dev/connect/https

Where /etc/dioad/connect/tunnels.yaml has the same shape as the main config's traffic: block:

traffic:
  tunnels:
    - type: httpreverseproxy
      name: web
      config:
        target-url: http://localhost:8080

A discovery file is checked as strictly as the main config: it may hold only a traffic: block, and every key in it must match a setting. A problem in a discovery file stops the agent from starting. An edit that introduces one, to a discovery file or to the main config's traffic: block, is rejected with the problem logged, and the tunnels already running are left as they were.


plugins — External Tunnel Server Plugins

Loads tunnel types from signed plugin binaries instead of only the types built into the agent. A tunnel uses a plugin type exactly like a built-in one: set type: in traffic.tunnels[] to a type the plugin declares. For the plugin release layout, signing keys and how to write a plugin, see External Plugins.

Plugins are disabled unless directory is set. The agent verifies every plugin at startup but only runs a plugin when a tunnel first uses one of its types.

Key Type Default Description
directory string "" Directory holding one sub-directory per plugin, each with manifest.json, manifest.json.sig and the plugin binaries. On Linux and macOS, the agent rejects plugin files that are group- or world-writable, or owned by another user.
cache-directory string user cache dir + /dioad/connect/plugins Where the agent copies each plugin binary after checking its SHA-256 digest. The agent only ever runs these copies.
require-signature bool true Reject plugins whose manifest has no valid signature from a key in trusted-keys.
trusted-keys list [] Keys plugin manifests may be signed with. Each entry has a name (used in logs) and a public-key in the ed25519:<base64> form printed by connect plugin keygen.
allow-unsigned list [] Plugin names exempt from require-signature, for development only. The agent logs a warning each time it loads one. A signature that is present must still verify.
env-allowlist list [HOME, TMPDIR, TZ, SSL_CERT_FILE, SSL_CERT_DIR, SYSTEMROOT, TEMP, TMP] Agent environment variables passed to plugin processes. Nothing else from the agent's environment, such as OIDC secrets or tokens, reaches a plugin.

A tunnel type provided by a plugin can't replace a built-in type or another plugin's type: the agent rejects the whole plugin and logs the clash.

When a plugin tunnel terminates TLS and tls-server.next-protos is unset, the agent offers only http/1.1 to clients, because plugins can't serve HTTP/2 yet.

Example:

plugins:
  directory: ~/.config/dioad/connect/plugins
  trusted-keys:
    - name: dioad-release
      public-key: "ed25519:MCowBQYDK2VwAyEA..."

traffic:
  tunnels:
    - name: hello
      type: pluginhello
      endpoint: https://connect.dioad.dev/connect/https
      config:
        custom-message: "Hello {{ .Principal }} from a plugin"


Shared Sub-Configurations

TLS Server

Configures TLS for inbound connections to a tunnel. Exactly one of acme, self-signed, or local should be set.

tls-server:
  # Option 1: Automatic certificates via Let's Encrypt (ACME)
  acme:
    type: ""                            # Challenge type: tls-alpn-01 (default) or dns-01
    cache-directory: .autocert          # Directory to cache certificates/account data
    email: admin@example.com            # Contact email for certificate issuance
    directory-url: ""                   # ACME directory URL (defaults to Let's Encrypt)
    domains: []                         # tls-alpn-01: hosts to provision certificates for on demand (no wildcards)
                                         # dns-01: SANs for the certificate obtained upfront (wildcards allowed)
    dns01-propagation-timeout: 60s      # dns-01 only: max wait for DNS propagation (default 60s)
    dns01-polling-interval: 2s          # dns-01 only: how often to poll for propagation (default 2s)

  # Option 2: Self-signed certificate
  self-signed:
    cache-directory: .autocert          # Directory to cache the generated certificate
    alias: my-service                   # Filename prefix for the generated certificate files
    duration: 8760h                     # Certificate validity duration
    ca: false                           # Generate a CA certificate
    bits: 2048                          # RSA key size
    subject:
      cn: my-service.example.com
      o: [My Org]
    san:
      dns-names: [my-service.example.com]
      ip-addresses: [127.0.0.1]

  # Option 3: Local certificate files
  local:
    cert: /path/to/server.crt           # PEM-encoded certificate file
    key: /path/to/server.key            # PEM-encoded private key file
    single-pem-file: /path/to/combo.pem # Combined cert+key PEM (alternative to cert/key)
    file-wait-interval: 5               # Seconds between retries waiting for cert files
    file-wait-max: 12                   # Max number of retries

  # Additional options (apply to any mode above)
  client-auth-type: ""                  # mTLS client auth: NoClientCert, RequestClientCert, RequireAnyClientCert, VerifyClientCertIfGiven, RequireAndVerifyClientCert
  client-ca-file: ""                    # CA file for verifying client certificates
  tls-min-version: ""                   # Minimum TLS version: TLS10, TLS11, TLS12, TLS13
  next-protos: []                       # ALPN protocols (default: [h2, http/1.1])
  server-name: ""                       # SNI server name override

TLS Client

Configures TLS for outbound connections (e.g. to the Connect server or OIDC provider).

tls-client:
  root-ca-file: /path/to/ca.crt    # Custom CA certificate for verifying the server
  cert: /path/to/client.crt        # Client certificate for mTLS
  key: /path/to/client.key         # Client private key for mTLS
  insecure-skip-verify: false      # Skip server certificate verification (not for production)

Network ACL

Controls which client IP addresses can connect to a reverse tunnel.

network-acl:
  allow:
    - 10.0.0.0/8
    - 192.168.1.0/24
  deny:
    - 10.1.0.0/16
  allow-by-default: false   # If true, allow IPs not matched by any rule; if false, deny them

DNS Records

Declares DNS records the tunnel should publish. Supported on reverse tunnels only. Record values support Go template syntax (template variables: {{ .Domain }}, {{ .BaseDomain }}, {{ .Email }}, {{ .OutboundIPList }}).

dns:
  txt:
    - name: ""              # DNS owner label relative to base domain ("" = apex)
      value: "v=spf1 {{ .OutboundIPList }} -all"
      ttl: 300              # TTL in seconds (0 = default)

  mx:
    - priority: 10          # MX preference value
      host: ""              # Mail exchange FQDN template ("" = tunnel's own FQDN)
      prefix: ""            # DNS owner label relative to base domain ("" = apex)
      ttl: 300

Example — tunnel with DNS records:

traffic:
  tunnels:
    - type: hello
      name: hello
      endpoint: https://connect.dioad.dev/connect/https
      tls-server:
        acme:
          cache-directory: .autocert
      dns:
        txt:
          - value: "v=hello {{ .TunnelPrincipal }}"
        mx:
          - priority: 10
      config:
        custom-message: "Hello {{ .Principal }}"

Example — several tcp tunnels serving one host: each tunnel has its own name, which depends-on refers to, and all three register mx.

traffic:
  tunnels:
    - type: tcp
      name: mx-smtp
      hostname: mx
      endpoint: https://connect.dioad.dev/connect/smtp
      config:
        target-address: 0.0.0.0:26
    - type: tcp
      name: mx-imap
      hostname: mx
      endpoint: https://connect.dioad.dev/connect/imap
      config:
        target-address: 0.0.0.0:994


status — Status File

While it runs, the agent keeps a status file: a JSON document with each tunnel's state and public URLs, whether the agent is signed in, and whether it is ready. connect agent status reads these files, so it works without the management interface, and lists every agent that shares the directory. See Agent Status Files for the format.

Key Type Default Description
directory string $CONNECT_AGENT_STATUS_DIR, or ~/.config/dioad/connect/status.d Where the agent keeps its status file. Agents that share a directory are listed together by connect agent status.
disabled bool false Turn the status file off. connect agent status then reaches this agent only through its management interface.
status:
  directory: /var/lib/connect-agent/status.d

shutdown-timeout — Graceful Shutdown Deadline

Optional top-level key bounding the whole graceful-shutdown sequence (drain all tunnels, stop all services.exec child processes, then stop the management and acme-dns HTTP servers).

Key Type Default Description
shutdown-timeout duration 5s Total time allowed for graceful shutdown. Accepts a Go duration string (e.g. 10s, 1m). Values <= 0 fall back to 5s. Raise it for an agent running several exec processes or many tunnels; the agent logs a warning if shutdown does not finish within this deadline.

profile-* — Debug Profiling

Optional pprof-style profiling output paths. Hidden from --help since they're a debugging aid, not a day-to-day setting, but they are ordinary top-level YAML keys like any other.

Key Type Description
profile-cpu-output string File path to write CPU profile data to
profile-memory-output string File path to write the heap profile to when the agent stops
profile-block-output string File path to write the blocking profile to when the agent stops

Complete Minimal Example

identity:
  type: keycloak
  url: https://auth.lab.dioad.net
  keycloak-realm: dioad-labs
  client-id: connect-cli
  token-file: ~/.config/dioad/connect/auth.yaml

log:
  level: info

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

traffic:
  tunnels:
    - type: hello
      name: hello
      config:
        custom-message: "Hello {{ .Principal }}"