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) - Outbound UDP to the HyperDHT bootstrap nodes
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:3000A Gateway started with a Kernel, as above, or with a Gateway credential checks a bearer access token and a spec.rbac rule on
every app route before the request reaches the app, so write the policy before you expose the port. A route
an app declares with "auth": true and its own permissions is authorized the same way, as auth and permissions
describes. A custom authVerifier function is for a Gateway started with no authority at all; it is not how you add
authentication to this path. 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.