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.
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 withacme_typeandacme_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 failedand 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,/mcpincluded, gets an empty404, 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.
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
Withrelay, 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.controlis 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_urlsholds 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.acmeis required, withouthttp_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_urlmay name another ACME directory.listen.hostmust be loopback: the listener is for health checks, and agents come through the relay.
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:
/etc/midplane/midplane.yaml, a config you mounted./var/lib/midplane/midplane.yaml, the config of a volume set up before.- With
MIDPLANE_ENROLLMENT_TOKENset, a gateway it sets up in/var/lib/midplanefrom the variables below, then serves: behind the relay, asmidplane setup --relaywould from its answers, or withMIDPLANE_URLat that URL, asmidplane setup --acmewould. It joins the project first and gets the certificate as it starts, so a token the project refuses gets none.
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 underdatabases.<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.