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 it connects out to Midplane Cloud to get your policy. Nothing connects in to it but agents.

​
Where to run it

This machine

To try Midplane. Only agents on this machine can use it.

A server, with Docker

For a team or production: agents anywhere reach it at an HTTPS URL.
Run it where it can reach your databases: on your laptop for a local or cloud database, inside the VPC for a private one.

​
This machine

You need Node 24.16 or newer, and macOS, Linux or WSL on Windows.
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 this machine 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 2 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 commands below it now hold the token.
2

Make the gateway's folder

Choose This machine and run the first block in a terminal. It makes a folder named after the gateway, such as gw-k3m9x2qa, with a secrets/ folder inside, and moves into it.
3

Save the config

Copy the config the page shows into that folder as midplane.yaml. It’s generated for your project, with every database listed.
4

Add the connection strings

For each database, write its connection string to the file the page names, such as secrets/shop.dsn, with an editor (prepare your database).
5

Start it

It joins your project and the page shows it connected. It keeps running in that terminal; Ctrl-C stops it, and the same command starts it again.
Agents on this machine reach it at the http://gw-….localhost:7433 URL in its config. A second gateway on the same machine needs another port: change it on the page before you copy the commands.

​
Docker

You need a server with Docker, a URL for the gateway, such as https://midplane.example.com, and a TLS certificate for it: the gateway serves HTTPS itself whenever it’s reachable from other machines.
1

Create an enrollment token

In your project, open step 2 of the setup (or Gateways, then Set up a gateway), and click Create enrollment token.
2

Enter the gateway's URL

Choose A server (Docker) and enter the URL agents will use. The page generates the config and commands for it.
3

Make the gateway's folder

On the server, run the first block. It makes the gateway’s folder with a secrets/ folder inside.
4

Save the config, connection strings and certificate

Save the config as midplane.yaml. Write each connection string to the file the page names, such as secrets/shop.dsn; inside the container, localhost is the container, so use the database’s real host. Put the certificate and its key in secrets/tls.crt and secrets/tls.key.
5

Start it

Run the last block. It gives the secrets to the container’s user and starts the container, which restarts with the server. The page shows the gateway connected; docker logs -f midplane-gw-… shows what it says.
For production, replace :latest in the command with a version you verified.

​
Other setups

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 http://127.0.0.1:7433, keeping the Host header. Change the config before the gateway’s first start, since it registers its URL then:
  • With npx: follow this machine, and in its config replace the public_urls line with public_urls: [https://midplane.example.com].
  • With Docker: follow Docker, and in its config replace the listen line with listen: { host: 127.0.0.1, port: 7433 } and delete the tls line. In the last block, run the container with --network host in place of -p … (Linux only).
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. In the config, set 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.
Running the commands again from the same place is safe: the salt and the identity are kept. In Docker, everything the gateway writes is in the container’s volume instead.
Every setting is in configuration. If the gateway doesn’t connect, see troubleshooting.