Run the Gateway
Start the MDK Gateway programmatically, as a standalone process, or connected to a remote Kernel over HRPC
Overview
This guide covers three ways to run the Gateway: programmatically via startGateway() (the standard production path), connected to
a remote Kernel over HRPC (cross-host deployments), and as a standalone process from the source tree (for contributors).
If Gateway, Kernel, or plugin are unfamiliar, read terminology first. For a deeper explanation of what the Gateway owns and how it connects to Kernel, read the Gateway concept page.
Prerequisites
- Node.js >=24 (LTS)
- npm 11 (< 12)
- Commands are run from the repository root
- A Kernel instance running and reachable, or
kernelKey: falseto start without a Kernel connection (development only)
Programmatic path
Most teams embed startGateway() in their own Node.js application rather than running the Gateway as a separate process.
This is the standard production path.
const { getKernel, startGateway } = require('@tetherto/mdk-core')
const kernel = await getKernel()
const server = await startGateway({ kernel, port: 3000 })
// HTTP server is up at http://localhost:3000The Gateway ships no identity layer. Routes a manifest marks "auth": true answer 401 until you pass startGateway() an authVerifier
backed by your own identity layer, as auth and permissions describes; every other route is served to any caller. Only
localhost, 127.0.0.1 and [::1] on the bound port pass the Host check by default, so list the names your clients use in allowedHosts
when you bind to a LAN address.
The full configuration reference, including all startGateway() options, is in the Gateway API reference.
Cross-host path (HRPC)
Use this path when Kernel runs on a separate host. Pass the Kernel HRPC listener public key to startGateway() instead of a Kernel instance.
(On a single host, neither is needed: startGateway() reads the key from the well-known key file that getKernel() publishes —
see the key resolution order.)
2.1 Obtain the Kernel listener key
On the host running Kernel, start Kernel and print its public key:
const { getKernel } = require('@tetherto/mdk-core')
const kernel = await getKernel()
console.log('Kernel listener key:', kernel.getPublicKey().toString('hex'))Share that hex string with the Gateway host.
2.2 Start the Gateway with kernelKey
const { startGateway } = require('@tetherto/mdk-core')
const server = await startGateway({
kernelKey: '<kernel-listener-pubkey-hex>',
port: 3000
})Kernel's allowlist auth.whitelist is fail-closed: empty admits nobody. startGateway({ kernel }) admits the Gateway's key on an
in-process Kernel, and a same-machine Kernel admits it from the shared trusted-keys dir. For a Kernel on another host, add the Gateway's
DHT public key (status.rpcClientKey in its status file, stable across restarts) to Kernel's allowlist — see the
Gateway concept page and opts.kernelKey reference.
Standalone path
To run the Gateway directly from the source tree without embedding it:
cd backend/core/gateway
npm install
npm run devFor production mode:
npm startThe standalone path is intended for contributors working on the Gateway itself. For application development, embed startGateway()
in your own project rather than running it standalone.