Skip to main content
The gateway is the part of Midplane that runs in your network. It’s a small program next to your databases: agents connect to it, it checks each statement against your policy and records it, and only then runs it. It holds your connection strings and opens its own connections: to your databases, and to Midplane Cloud for your policy. Behind Midplane’s relay, agents’ traffic comes in over connections the gateway opens too, so nothing connects in to it at all.

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.
Run it where it can reach your databases: on your computer for a local or cloud database, inside the VPC for a private one.

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:
The gateway runs as you, so an agent that runs commands as you, such as Claude Code with its shell, can read secrets/*.dsn and connect to the database without Midplane. Use your computer to try Midplane; to hold such an agent to your policy, run the gateway as another user or on another host.
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.
With This computer only, agents on your computer reach the gateway at the 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 as https://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

Open in Cursor
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:
  1. Should you run the commands yourself, asking me before each one, or tell me what to run?
  2. 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.
  3. Where is the database, and can that server reach it?
Rules:
  • 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.env or docker inspect on the gateway’s container. I put them in the env file on the server myself.
  • In the gateway’s container, localhost is the container. For a database on the same server, use the address the page gives for that case.
Steps:
  1. 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.
  2. I open my project in Midplane Cloud, choose “A server (Docker)” and “Midplane URL”, and click “Create enrollment token”.
  3. I save the env file the page shows as midplane.env on the server, fill in each connection string, and run chmod 600 midplane.env.
  4. The page’s one docker run command 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.
  5. Check: the container’s logs (docker logs) end setup with the https://gw-….midplane.app/mcp URL agents reach it at, and the page shows that URL with the relay connected and the gateway enforcing.
  6. 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_SHOP is the database shop: the name after MIDPLANE_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 logs says what it found, such as ok: 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).
The command names the newest release’s image by its version, such as 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 as https://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:
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.
Both commands name the newest release’s image by its version, which you can verify; the server keeps it until you upgrade the gateway. The volume holds the gateway’s config, connection strings, identity, certificate and audit log. To replace the gateway with a new one, revoke it on the Gateways page (its URL is taken until then), run 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

With your own URL, the image can also set itself up from environment variables when it first starts, then serve: one 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
Start the gateway with it:
With <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.
A config mounted at /etc/midplane/midplane.yaml is served instead, as before. Every variable is in configuration.
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 to public_urls in the gateway’s midplane.yaml, such as public_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 at http://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 in public_urls and no tls, and run the container with --network host (Linux only). The gateway registers the URLs in its config when it first starts.
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:
  1. Write the config yourself, with link.identity: { env: MIDPLANE_IDENTITY }.
  2. Run npx -y midplane@latest enroll --config midplane.yaml with 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.
  3. Store that line in the platform’s secrets as MIDPLANE_IDENTITY, and delete any copy: it holds the gateway’s private key.
Most platforms end TLS at their edge and forward plain HTTP, which the gateway refuses: run a TLS proxy beside it, as in hosted agents. Mount a volume for the audit log if you want to keep it.
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.
  1. Make the gateway’s folder, with a secrets/ folder closed to other users: mkdir -p gw/secrets && cd gw && chmod 700 secrets.
  2. Make the mask salt: openssl rand -hex 32 > secrets/mask-salt.
  3. With an editor, write each connection string to secrets/<database id>.dsn, and the token to secrets/enrollment-token. The token is the --token value in the command the page shows after Create enrollment token.
  4. Save the config as midplane.yaml, with a line per database:
  5. Start it: npx -y midplane@latest gateway --config midplane.yaml.
A database the config names that the project lacks shows on Gateways as 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.
In Docker, the same files are in the gateway’s volume, such as midplane-gw-k3m9x2qa. Keep the folder or the volume: a new one is a new gateway, with a new mask salt.
Every setting is in configuration. If the gateway doesn’t connect, see troubleshooting. Tested by 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).