Where to run it
Your computer
To try Midplane: with agents on your computer, or with claude.ai and
ChatGPT too, at a Midplane URL.
A server, with Docker
For a team or production: agents anywhere reach it at an HTTPS URL,
claude.ai and ChatGPT included, even in a private network.
A cloud platform
The same, from a template: AWS, Fly.io, Render or Kubernetes.
Your computer
You need Node 24.16 or newer, and macOS, Linux or WSL on Windows. Under Agents reach it at, the page offers two URLs where Midplane has a relay:1
Create an enrollment token
In your project, open step 1 of the setup (or Gateways, then Set up
a gateway), and click Create enrollment token. The gateway uses it
once, to join your project. Keep the page open: the command below it now
holds the token.
2
Run setup
Choose Your computer, keep This computer only or choose
Midplane URL, and paste the command into a terminal. It runs
midplane setup, with --relay for a Midplane URL, which asks for each
database’s connection string (prepare your database):
paste it and press Enter. What you paste isn’t shown, and stays in the
gateway’s folder: it never reaches Midplane Cloud.3
Check each database
Setup connects as the gateway will and says what it found, such as
ok: database app on db.internal, 12 tables. If it fails, it says why: paste
a corrected string, or type keep to save it anyway. It suggests a name
for each database new to the project, such as shop, which you can
change.4
Start it
Setup joins your project, writes the gateway’s folder where you ran it,
such as
gw-k3m9x2qa, and starts the gateway. The page shows it
connected; with a Midplane URL, it shows the URL for agents once the
gateway’s connections to the relay are up. It keeps running in that
terminal; Ctrl-C stops it, and npx -y midplane@latest gateway --config gw-k3m9x2qa/midplane.yaml starts it again.http://gw-….localhost URL setup prints. Hosted agents such as claude.ai and
ChatGPT can’t, unless a tunnel or a URL of your own is in front of it
(hosted agents). Setup takes the first port from
7433 to 7442 that is free when it runs, so a gateway that was stopped then may
have its port taken: give the new one another with --port.
With a Midplane URL, agents anywhere reach it at the URL the page shows,
such as https://gw-k3m9x2qa.eu.midplane.app/mcp, which setup’s last line
names too. Agents on your computer use it as well: the gateway answers on no
other URL. It listens only on loopback and connects out to the relay, which
passes agents’ encrypted traffic to it without reading it, as for a
server.
- The URL is on the internet. Anyone can reach it, and an agent reaches your data only once a member of your project signs it in, as at any gateway’s URL. Its certificate, and so its name, is published in Certificate Transparency logs (watch them).
- Its certificate comes through the relay as the gateway first starts, and stays in its folder, where the gateway renews it.
- While your computer sleeps or is offline, agents can’t reach the gateway. It reconnects to the relay on its own once your computer wakes, as it does when the relay is down.
Docker
You need a server with Docker that can reach your databases and connect out to the internet on port 443. Agents reach the gateway at a Midplane URL, such ashttps://gw-7hq2m4xd.eu.midplane.app/mcp, through
Midplane’s relay: no host name, DNS record or open port, and it runs in a
private network. The relay passes agents’ encrypted traffic to the gateway
without reading it, and TLS ends at the gateway, with a certificate it gets
from Let’s Encrypt and a key that never leaves its volume (how it
works, what the relay
sees).
Let an AI assistant (Claude, ChatGPT, Cursor) set the server up with you: copy
this prompt into it. It asks how you want to work first, never asks for your
connection strings or token, and asks before creating anything that costs
money.
Set up a server gateway behind the relay with your AI assistant
Read the prompt
Read the prompt
Help me run a Midplane gateway on a server, so AI agents can reach my Postgres database through Midplane’s relay. First read
https://midplane.ai/docs/gateway/deploy (the Docker section). Where this prompt and that page disagree, follow the page.Ask me first:- Should you run the commands yourself, asking me before each one, or tell me what to run?
- Where should the server run: a cloud I already use (AWS, Google Cloud, Azure, Hetzner, DigitalOcean…) or a server I have? Which account and region? On AWS, Fly.io, Render or Kubernetes, tell me first that Midplane has a template for it (the page’s “On a platform”), and ask whether I’d rather use that.
- Where is the database, and can that server reach it?
- A server you create takes no inbound traffic: its firewall or security group allows nothing in. Don’t open SSH or any other port to get in: use a shell that connects out, such as AWS Systems Manager Session Manager, or the provider’s web console. On a server I have, leave its firewall as it is.
- The gateway only connects out: to the internet on port 443, and to the database. Leave the server’s outbound traffic open unless I ask you to restrict it.
- Before creating anything that costs money, tell me the account, region, size and price per hour, and wait for my yes. Tag what you create so it can be found and removed.
- Never ask me for a connection string, password or enrollment token in this chat, and don’t run anything that prints them, such as
cat midplane.envordocker inspecton the gateway’s container. I put them in the env file on the server myself. - In the gateway’s container,
localhostis the container. For a database on the same server, use the address the page gives for that case.
- Prepare the server with Docker. From inside a container, as the gateway connects, check that it reaches the database’s host and port, which needs no password, and connects out on port 443.
- I open my project in Midplane Cloud, choose “A server (Docker)” and “Midplane URL”, and click “Create enrollment token”.
- I save the env file the page shows as
midplane.envon the server, fill in each connection string, and runchmod 600 midplane.env. - The page’s one
docker runcommand runs in that folder: I paste it, or you run it once I say the file is saved. It holds no secret and publishes no port. - Check: the container’s logs (
docker logs) end setup with thehttps://gw-….midplane.app/mcpURL agents reach it at, and the page shows that URL with the relay connected and the gateway enforcing. - If the server was a test, offer to remove everything you created, then check that nothing is left.
1
Create an enrollment token
In your project, open step 1 of the setup (or Gateways, then Set up
a gateway), choose A server (Docker), keep Midplane URL and,
under Runs on, A server with Docker. Click Create enrollment
token, above the tabs. Keep the page open: the env file and the command
it shows now hold the token.
2
Save the env file
On the server, save the file the page shows as
midplane.env with an
editor, and close it to other users (chmod 600 midplane.env). It has a
line per database of the project, such as MIDPLANE_DSN_SHOP=<shop's connection string>: put each database’s connection string after its =
(prepare your database). The gateway connects from
inside its container, where localhost is the container: use the
database’s host as the server’s network knows it.If the database runs on the same server, the container reaches the
server at Docker’s bridge address, by default 172.17.0.1 on Linux
(ip addr show docker0 shows it), so use that as the host. Postgres
must listen there and admit the container: set
listen_addresses = '*', since Postgres can start before Docker adds
that address, keep port 5432 closed to the outside in the server’s
firewall, and add a pg_hba.conf line for the bridge’s network, by
default 172.17.0.0/16. A Postgres in another container publishes its
port there: -p 172.17.0.1:5432:5432. On Docker Desktop, use
host.docker.internal.3
Run the gateway
In the folder that holds the file, run the command. It starts the
gateway, detached and again whenever the server restarts, and publishes
no port: nothing connects in. At its first start it asks Midplane Cloud
for the relay, tests each connection string, joins your project and
writes its config to the Docker volume the command names, such as
midplane-gw-k3m9x2qa. Then it connects out to the relay and gets its
certificate through it. docker logs -f midplane-gw-… shows what it
says; setup’s last line is the URL agents reach it at. The gateway picks
the name in that URL itself, so it isn’t the container’s.4
Check it on the page
Once the gateway connects, the page shows its URL for agents, and the
setup step says Relay · connected. If it says why the relay refused
it, see cannot reach the relay.
- A variable per database.
MIDPLANE_DSN_SHOPis the databaseshop: the name afterMIDPLANE_DSN_, lowercased. A database not in the project yet is added, with nothing readable until you publish its policy. - Each connection string is tested as setup tests it:
docker logssays what it found, such asok: database shop on db.internal, 12 tables, or why it failed, but never the string. One that fails is kept, and the gateway reports it unreachable until it answers. - The connection strings stay in the env file. The config on the volume
names each one’s variable (
dsn: { env: MIDPLANE_DSN_SHOP }), so keep the file: the gateway reads them each time it starts, and never sends them to Midplane Cloud. - The rest is read once. Restarted, the container serves what the volume holds, without joining the project again, and no longer needs the token.
- If setup fails before the gateway joins the project, the log’s last
line says why (troubleshooting).
Setup removed what it wrote and left the token unused, but the container
keeps restarting and trying, about once a minute: Docker reads the env file
only when it creates the container. Remove it (
docker rm -f midplane-gw-…), fix the file, and run the command again. - Keep the volume. The gateway’s certificate is on the volume: a gateway that loses it orders a new one as it starts, and Let’s Encrypt issues at most 5 for one name a week, to all its copies together. Behind the relay, run at most two copies of one gateway, each with a volume of its own (replicas); for more, use your own URL.
- If the relay is down, the gateway keeps enforcing your policies, but agents can’t reach it until the relay is back. It reconnects on its own (when the relay is down).
ghcr.io/midplaneai/midplane:0.26.0, which you can verify; the
server keeps it until you upgrade the gateway.
Every variable is in
configuration.
Your own URL
You need a server with Docker and a URL for the gateway, such ashttps://midplane.example.com. The gateway serves HTTPS itself whenever it’s
reachable from other machines, with a certificate it gets from Let’s Encrypt
and renews, or with your own. Nothing of Midplane’s is between agents and
the gateway.
1
Point the URL at the server
Point the URL’s DNS at the server: an
A record, and AAAA if it has
IPv6. Then, for the certificate:- Automatic certificate
- My own certificate
Open ports 80 and 443 to the internet, or the port agents will use
instead of 443. Let’s Encrypt checks port 80 before it issues the
certificate, and again each time the gateway renews it: there it
reaches a listener that answers its challenge and nothing else.
Getting the certificate agrees to Let’s Encrypt’s subscriber
agreement.
2
Create an enrollment token
In your project, open step 1 of the setup (or Gateways, then Set up
a gateway), and click Create enrollment token.
3
Enter the gateway's URL
Choose A server (Docker), then Your own URL if the page offers a
Midplane URL, and enter the gateway’s URL:
https:// and
the name you pointed at the server, such as
https://midplane.example.com. Agents reach the gateway at it. Under
Certificate, keep Automatic (Let’s Encrypt) or choose My own.
With an automatic certificate, the page lists what must be true before
you run the commands, and looks up where the name points now, such as
midplane.example.com points at 203.0.113.7. If it says the name
doesn’t resolve yet, wait a few minutes for the record and press Check
again. The page then shows two commands, with the token in them.4
Run setup in the image
Run the first command on the server. Setup asks for each connection
string and tests it from inside the container, where
localhost is the
container: use the database’s host as the server’s network knows it.
With an automatic certificate it then gets one for the URL, saying ok: valid until and its date; if Let’s Encrypt can’t reach the server, it
says why (troubleshooting),
removes what it wrote and leaves the token unused. It writes the config,
the connection strings, the certificate and the gateway’s identity to a
Docker volume named after the gateway, such as midplane-gw-k3m9x2qa,
and joins your project.5
Start it
Run the second command. It starts the gateway from that volume, and again
whenever the server restarts. The page shows it connected;
docker logs -f midplane-gw-… shows what it says. An automatic certificate is renewed
in its last 30 days, without a restart.docker rm -f midplane-gw-… && docker volume rm midplane-gw-…, which deletes its audit
log, and set the new one up with a new token.
On a platform
Behind the relay the gateway needs no port, domain or certificate of yours, so it runs anywhere its image keeps a disk and connects out. Each template reads the same env file as the Docker steps, and the page shows its steps under Runs on.AWS
A CloudFormation stack in your VPC, next to RDS or Aurora: one EC2
instance with nothing inbound.
Fly.io
One machine with a volume, and no IP address.
Render
A background worker with a disk, from a Blueprint.
Kubernetes
A Helm chart: one pod with its own disk, and no Service.
Other setups
Your own URL, with one command
Your own URL, with one command
With your own URL, the image can also set itself up from
environment variables when it first starts, then serve: one Start the gateway with it:With
docker run, or a platform’s secrets, with no terminal. Point the URL at the
server and open ports 80 and 443, as for an automatic
certificate, and create an enrollment token. Then, on the
server, write an env file such as midplane.env with an editor, and
close it to other users (chmod 600 midplane.env). Its MIDPLANE_URL
is what makes it your own URL; without it, the gateway is set up behind
the relay, as above:midplane.env
<version> the newest release’s, such as 0.26.0
(upgrading).The variables per database, the connection tests, what stays in the
file and what happens when setup fails are as above, with
midplane for the container’s name. Restarted, the container doesn’t
get a certificate again either.- The certificate comes after joining, as the gateway starts, so a token the project refuses gets none. If Let’s Encrypt refuses, the log’s last line says why (troubleshooting): fix the DNS or the ports, and the gateway tries again each time it restarts, with no new token. Let’s Encrypt allows five failed tries an hour for a name.
/etc/midplane/midplane.yaml is served instead, as
before. Every variable is in
configuration.Behind your TLS proxy
Behind your TLS proxy
If a proxy or load balancer on the same host already serves TLS for the
URL, keep the gateway on loopback and have the proxy forward the URL to
it, keeping the
Host header.- With
npx: follow your computer. Then add the URL topublic_urlsin the gateway’smidplane.yaml, such aspublic_urls: [http://gw-k3m9x2qa.localhost:7433, https://midplane.example.com], and restart it. A URL added after the gateway joined waits on the project’s Gateways page until an owner or admin presses Register. Point the proxy athttp://127.0.0.1:7433, or the port setup chose. - With Docker: write the config yourself,
with
listen: { host: 127.0.0.1, port: 7433 }, your URL inpublic_urlsand notls, and run the container with--network host(Linux only). The gateway registers the URLs in its config when it first starts.
A platform without a disk
A platform without a disk
At your own URL only: behind the relay, the gateway keeps its certificate
on its disk, and without one it would order a new one at every start.Some platforms keep no files across restarts, so the gateway can’t keep the
identity it gets when it joins. Enroll it once and store the identity as a
secret instead:
- Write the config yourself, with
link.identity: { env: MIDPLANE_IDENTITY }. - Run
npx -y midplane@latest enroll --config midplane.yamlwith the token in place. It prints the identity as one line of JSON. It reads the whole config, so every file and variable it names must exist there. - Store that line in the platform’s secrets as
MIDPLANE_IDENTITY, and delete any copy: it holds the gateway’s private key.
Write the config yourself
Write the config yourself
For what setup doesn’t cover, such as a proxy in front, a secret manager
or Kubernetes, write the config by hand. The gateway joins the project
the first time it starts, with the token from the file the config names.
-
Make the gateway’s folder, with a
secrets/folder closed to other users:mkdir -p gw/secrets && cd gw && chmod 700 secrets. -
Make the mask salt:
openssl rand -hex 32 > secrets/mask-salt. -
With an editor, write each connection string to
secrets/<database id>.dsn, and the token tosecrets/enrollment-token. The token is the--tokenvalue in the command the page shows after Create enrollment token. -
Save the config as
midplane.yaml, with a line per database: -
Start it:
npx -y midplane@latest gateway --config midplane.yaml.
in its config, not in this project, with Add beside it. In
Docker, mount the folder read-only at /etc/midplane, where the image
reads midplane.yaml, and let uid 1000 read the secrets (sudo chown -R 1000:1000 secrets). Put what the gateway writes (audit.file,
link.identity and link.bundle_cache) under /var/lib/midplane/, on a
volume. With tls.acme, the gateway keeps its certificate in acme/
beside the config, so mount the folder writable instead. Every key is in
configuration.What the gateway's folder holds
What the gateway's folder holds
midplane-gw-k3m9x2qa. Keep the folder or the volume: a new one is a new
gateway, with a new mask salt.apps/gateway/scripts/package-smoke.ts (setup with the packed
npm package; setup then the gateway in the image on one volume, with your own
certificate and with an automatic one from Pebble, Let’s Encrypt’s test CA;
one docker run --env-file that sets itself up against Pebble, then restarts,
in CI’s package job), and apps/gateway/test/setup-relay.test.ts (setup
behind a stand-in relay, from flags and from the environment, then the
gateway serving through it).