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
- 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')
const kernel = await getKernel()
const server = await startGateway({ kernel, port: 3000 })
// HTTP server is up at http://localhost:3000The Gateway ships no built-in authentication meaning that routes are unauthenticated by default.
To add identity and token endpoints, mount the @tetherto/mdk-plugin-auth plugin via extraPluginDirs.
Gateway plugins are the highly-apaptable method to customize your busines logic.
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')
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')
const server = await startGateway({
kernelKey: '<kernel-listener-pubkey-hex>',
port: 3000
})Pre v1.0, Kernel's allowlist auth.whitelist defaults to empty and admits any HRPC caller. For production deployments, add the Gateway's
DHT public key 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.