---
title: Self-Hosting
description: "Run NoLag yourself. Three ways: the whole stack on your own machine, your broker with NoLag as the control plane, or fully hosted. Both kraken and nolag-core are Apache 2.0."
---

# Self-Hosting

NoLag is open source. The broker and the authorization layer behind it are both
Apache 2.0 and both on GitHub, so you can run as much or as little of it as you
want.

| Repository | What it is |
| --- | --- |
| [NoLagApp/kraken](https://github.com/NoLagApp/kraken) | The broker. WebSocket and MQTT ingress, topics, rooms, presence, QoS, replay. |
| [NoLagApp/nolag-core](https://github.com/NoLagApp/nolag-core) | The authorization and configuration layer. Projects, apps, rooms, actors, tokens, signing keys. |

There are three ways to run it, and the difference is only *who holds what*.

## Option 1: the whole stack, on your machine

Everything local. Nothing contacts NoLag, and you do not need an account.

```bash
git clone https://github.com/NoLagApp/nolag-core
cd nolag-core
./quickstart/quickstart.sh
```

That brings up Postgres, core, kraken and an admin UI, and seeds a demo project.
The first run compiles kraken from source and takes a few minutes; after that it
is seconds.

| | |
| --- | --- |
| Admin UI | `http://localhost:3401` |
| Core API | `http://localhost:3400`, OpenAPI at `/swagger` |
| Broker | `ws://localhost:8410/ws` |

Access tokens for the demo project are written to `quickstart/credentials.json`.
They are shown once, because core stores only their hashes.

Connecting is then identical to connecting to hosted NoLag, with a different
URL:

```js
import { NoLag } from "@nolag/js-sdk";

const client = NoLag(TOKEN, { url: "ws://localhost:8410/ws" });
await client.connect();
client.subscribe("my-app/general/messages");
```

The quickstart is a demonstration, not a production deployment. The example host
authenticates nobody, which is why every port binds to `127.0.0.1`. Read
[what the quickstart is not](https://github.com/NoLagApp/nolag-core#what-the-quickstart-is-not)
before pointing anything real at it.

### Just the broker

If you only want the broker and intend to supply your own auth, kraken runs on
its own with no database and no external message broker:

```bash
git clone https://github.com/NoLagApp/kraken
cd kraken
docker compose up
```

That gives you a complete realtime backend on `ws://localhost:8080/ws`, with
tokens read from `examples/auth.json`. Four things are pluggable, and each has a
zero-dependency default:

| Slot | Default | Swap in |
| --- | --- | --- |
| Auth | `static` (token file) | your control plane or IdP |
| Broker fan-out | `syn` (built in) | EMQX, Mosquitto, VerneMQ |
| Store | `ets` (in memory) | your database |
| Control | `noop` | your billing or quota system |

## Option 2: your broker, our control plane

Run kraken yourself, and let NoLag answer the authorization questions. Token
validation, ACLs, rooms, presence and quota come from NoLag, while fan-out and
message history stay on your infrastructure, so **NoLag never sees a message
payload**.

Mint a link key in the [portal](https://portal.nolag.app), then:

```bash
NOLAG_LINK_KEY=nlg_link_xxxx.<secret> \
  docker compose -f docker-compose.cloud.yml up
```

One environment variable is the whole difference. This is the middle ground
between the `auth.json` quickstart and the fully hosted product, and it is the
right answer if you cannot send data to a third party but would rather not build
an auth control plane either.

[docs/CLOUD.md](https://github.com/NoLagApp/kraken/blob/main/docs/CLOUD.md) in
the kraken repository sets out exactly what NoLag does and does not receive.

## Option 3: hosted

We run all of it. No infrastructure, and you get the portal, usage dashboards,
replay and billing. See [pricing](/pricing), or start with the
[quick start](/docs/getting-started).

## Which one

| | Data stays with you | You run infrastructure | You build auth |
| --- | --- | --- | --- |
| Whole stack | yes | yes | no, core does it |
| Broker only | yes | yes | yes |
| Linked | yes | broker only | no |
| Hosted | no | no | no |

## What is not open source

The hosted portal, usage metering and billing are not. Everything that exists
only because someone runs NoLag as a commercial service lives outside the two
repositories above.

We are not currently accepting external code contributions. Issues and bug
reports are welcome.