Skip to main content
One YAML file, midplane.yaml, named with --config. Relative paths in it are relative to the file. Secrets never appear inline: a DSN, the mask salt, the identity and the enrollment token each name an environment variable or a file, so the config itself can be committed.
Unknown keys are errors, and so is anything that doesn’t validate: the gateway won’t start on a config it can’t fully read.

Both modes

Automatic certificates

(0.23.0+) With tls.acme, the gateway gets its certificate from Let’s Encrypt for the host of its one https public URL, and keeps it current:
  • Before it listens, it uses the certificate it kept, if that covers the host and has more than 30 days left, or gets a new one. If Let’s Encrypt refuses and the kept certificate still covers the host and is in date, the gateway serves it, logs certificate renewal failed, and renews it at the next check. With no certificate it can serve, the gateway exits, its last log line saying why with acme_type and acme_detail (troubleshooting).
  • Every 12 hours it renews a certificate with 30 days or fewer left, and serves the new one to new connections without a restart. A renewal that fails logs certificate renewal failed and is tried at the next check; the current certificate is served meanwhile.
  • Let’s Encrypt checks the host with an HTTP-01 challenge: it fetches a token from port 80 of the host, which must reach http_port (in Docker, -p 80:7480). The listener there answers a token pending right now and nothing else: every other request, /mcp included, gets an empty 404, so no agent’s token is read in the clear.
  • It keeps the certificate, its key and the account’s key in acme/ beside the config, closed to other users. Keep the folder: Let’s Encrypt issues at most five certificates for the same host a week.
The host must be a name, not an IP address, and must be the only https host in public_urls: a tunnel’s or proxy’s URL leads Let’s Encrypt somewhere else. Getting a certificate agrees to Let’s Encrypt’s subscriber agreement. Setup with --acme (midplane setup --url https://… --acme) writes tls: { acme: {} } and gets the first certificate before it joins the project.

Behind the relay

With relay, agents reach a linked gateway through Midplane’s relay, at its Midplane URL, and the gateway only connects out. midplane setup --relay, or setup from environment variables without MIDPLANE_URL, asks Midplane Cloud for its relay and writes:
  • relay.control is the relay’s name, relay. and the relay domain. The gateway keeps 4 connections open to it on port 443, authenticated with its link token, and takes agents’ connections over them.
  • public_urls holds one URL, the gateway’s Midplane URL: https://gw- and 8 characters, on the relay domain, with no port or path. It gets one only when it joins a project, and it is never given to another gateway, even after this one is revoked.
  • tls.acme is required, without http_port: the gateway gets its certificate from Let’s Encrypt through the relay, which forwards the check of port 80 to it, so it binds no port for it. directory_url may name another ACME directory.
  • listen.host must be loopback: the listener is for health checks, and agents come through the relay.
Each of these is checked at start, and a config that breaks one is refused by its key. A config with relay in local mode is refused too. What the relay sees, and what it can’t, is in security. Two more rules the config can’t check:
  • It needs a disk. The gateway keeps its certificate in acme/ beside the config, on its volume, and never in a variable. Without a disk it gets a new certificate at every start, and Let’s Encrypt issues at most five for one name a week.
  • Run at most two copies of it. The relay holds 8 idle connections per gateway, and each copy keeps 4. Each copy orders its own certificate, out of the same five a week, and the relay passes Let’s Encrypt’s check to one of the gateway’s connections after another until the copy that ordered it answers. For more copies, use your own URL (replicas).

Local mode only (midplane local)

Linked mode only (midplane gateway)

Linked databases have no policy: policies come in signed bundles from Midplane Cloud.

Setup from environment variables

(0.24.0+) midplane start, the image’s default command, serves the first of these that exists:
  1. /etc/midplane/midplane.yaml, a config you mounted.
  2. /var/lib/midplane/midplane.yaml, the config of a volume set up before.
  3. With MIDPLANE_ENROLLMENT_TOKEN set, a gateway it sets up in /var/lib/midplane from the variables below, then serves: behind the relay, as midplane setup --relay would from its answers, or with MIDPLANE_URL at that URL, as midplane setup --acme would. It joins the project first and gets the certificate as it starts, so a token the project refuses gets none.
Without any of them, it exits with no config. Each variable is read on the first start only, but for the connection strings: Setup’s messages are log lines. It checks the variables before it writes anything: it names at once every one that is missing and every MIDPLANE_DSN_* that is wrong, then the first other value that is wrong, and never a connection string’s value. A failure before the gateway joins the project removes what it wrote and leaves the token unused. A certificate it can’t get is tried again at each start. A start that fails exits at once, its error the last log line, and a restart policy starts it again. Once the volume has a config, a new MIDPLANE_DSN_* alone is ignored: add the database to the config too (adding databases).

Commands

Every command needs Node 24.16 or newer. (0.26.2+) --help after any command prints the usage, and so does a flag the command doesn’t know, which exits 2. enroll and keygen never write over a file.

Setup flags

Without --relay or --url, setup makes a gateway for your computer: on loopback, at http://gw-….localhost and its port, with no TLS.

The policy

A database’s policy, in local mode under databases.<id>.policy, in linked mode authored in the dashboard (which shows it as JSON too). Strict: an unknown key anywhere refuses the whole policy, never part of it.
Whatever the policy says, a statement must be one statement Midplane can parse and resolve; writes need a WHERE; writes hidden inside a WITH are denied; and reads run in read-only transactions. Tested by apps/gateway/test/config.test.ts (secrets and paths, TLS off loopback, tls.acme, public URLs, the salt, retention, unknown keys, both modes), apps/gateway/test/certificates.test.ts and apps/gateway/test/acme.e2e.test.ts (getting, keeping, renewing and reloading certificates), apps/gateway/test/setup.test.ts and apps/gateway/test/cli.e2e.test.ts (setup’s flags and the commands), and the core’s corpus (packages/corpus) for what a policy means.