Skip to content
dockmesh

Agent mTLS

Every dockmesh server is its own private certificate authority. When you add a host, the server issues a short-lived client certificate for the agent — the agent uses it to authenticate every connection, and the server validates both the certificate and its own issuing chain.

Why an internal CA?

Section titled “Why an internal CA?”
  • No public CA — agents don’t need internet access to verify certs
  • Revocable per-agent — pull a cert, the host is locked out immediately
  • Short-lived — certs rotate automatically, limiting blast radius if leaked
  • Simple ops — one trust root per server, backed up with the database

The CA private key lives in the database, encrypted with a key derived from DOCKMESH_DB_PATH parent directory permissions plus an optional DOCKMESH_CA_PASSPHRASE env var. Protect the data directory with standard filesystem permissions.

Enrollment

Section titled “Enrollment”

When you generate an enrollment token:

  1. Server issues a one-time bootstrap certificate tied to the token
  2. Agent uses the bootstrap cert for the first connection
  3. During the first handshake, agent generates a long-term keypair and requests a cert
  4. Server issues the long-term cert signed by its CA, with the agent’s host ID as the Common Name and any extra SANs you configured via DOCKMESH_AGENT_SANS

After enrollment, the bootstrap cert is invalidated — the token can’t be reused.

Rotation

Section titled “Rotation”

Long-term agent certificates expire after 30 days by default. An agent requests a renewal 7 days before expiry over its existing connection — the new cert is hot-swapped with no downtime.

If an agent is offline past expiry, it falls back to its bootstrap cert and prompts you in the UI to re-enroll.

Revocation

Section titled “Revocation”

Hosts → select → Remove adds the cert serial to the server’s revocation list. The agent’s next handshake is rejected; the agent exits cleanly.

The revocation list is checked on every handshake. Server-side revocations propagate within seconds — there is no “wait for CRL refresh” delay.

Server certificate

Section titled “Server certificate”

For the UI and agent listener, you have two options:

  • Let dockmesh’s embedded Caddy obtain a public cert via ACME (Let’s Encrypt) — zero config
  • Provide your own cert and key in DOCKMESH_TLS_CERT / DOCKMESH_TLS_KEY — useful behind a corporate reverse proxy or with a private CA

See also

Section titled “See also”