Running a relay

You have been working locally for a while. Now you want your board somewhere other than this laptop — as a backup, or so a colleague (or another of your machines) can see the same work.

That needs a relay: a small server that holds the op log and hands it to every replica that asks. There is no hosted one; you run it. The good news is that you already have it.

Read this first: the relay has no authentication yet. Anyone who can reach its address can read and write the whole stream. Run it on a private network, a VPN, or behind something that does the authenticating — not on a public address. This is a known gap, not a configuration you can fix from the outside.

You already have the binary

Every release tarball ships two programs: nxs (the CLI you already use) and nxf-relay. The installer keeps the relay out of your PATH by default, because most people never run one:

NXF_INSTALL_RELAY=1 curl -fsSL https://nxsflow.com/nxs/install.sh | sh

If nxs is already installed, re-running the installer that way adds the relay beside it.

The smallest thing that works

NXF_RELAY_ADDR=127.0.0.1:8787 NXF_RELAY_DB=/var/lib/nxf/relay.sqlite nxf-relay

That is the whole server. It stores everything in one SQLite file — which is also the whole backup story: stop it (or snapshot the volume), copy the file, done. For one person with a few machines, or a small team on one box, this is not a compromise; it is the right answer.

Point your workspaces at it and bind a stream:

nxs sync endpoint http://relay.internal:8787   # once per machine
nxs sync bind                                  # once per workspace
nxs sync run                                   # push + pull

In a git repo, bind needs no arguments: the stream id is derived from the origin remote, so every clone lands on the same stream. See migration for the other binding modes.

Sync to a Postgres, for example Supabase

When you would rather have a managed database keep the data — someone else's backups, someone else's disks — point the relay at Postgres instead. Any Postgres works: Supabase, Neon, RDS, or your own.

export NXF_RELAY_BACKEND=postgres
export NXF_RELAY_PG_URL='postgres://user:pass@db.example.com:5432/nxf?sslmode=require'
nxf-relay

The relay creates its own tables on first boot, so there is no migration step to run.

A few things worth knowing:

sslmode=require is what you want for anything reachable over the internet; every managed provider requires it. The default (prefer) negotiates TLS when the server offers it and falls back to plaintext when it does not, which is right for a database on your own private network and wrong for one on the public internet — so say require and mean it. If you point the relay at a non-local host and leave it on prefer, it says so at startup rather than quietly sending your op log in the clear.
A private or self-signed CA is trusted by pointing NXF_RELAY_PG_CA_FILE at its PEM file. Public certificate authorities are built in and need no setup — but do not assume a managed provider uses one. Supabase signs its Postgres and pooler certificates with its own root, so a relay pointed there fails the handshake with invalid peer certificate: UnknownIssuer until you download that certificate (Project Settings → Database → SSL Configuration) and set NXF_RELAY_PG_CA_FILE=/path/to/prod-ca-2021.crt. This is the one extra step Supabase needs, and it applies to any provider with its own CA.
The pool is NXF_RELAY_PG_POOL_MAX_SIZE (default 16) and NXF_RELAY_PG_ACQUIRE_TIMEOUT_SECS (default 30).

Switching backends changes nothing a client can see: same HTTP surface, same convergence, same stream ids. You can move from SQLite to Postgres by standing up a second relay and re-binding.

DynamoDB: build it yourself

The relay also has a DynamoDB backend, for serverless deployments where there is no disk to own. It is not in the released binary, on purpose — it drags a native cryptography toolchain (cmake, a C compiler) into every build to add ~19 MB to every download, for something almost nobody runs. It is a supported configuration, just a source-built one:

git clone https://github.com/nxsflow/nexus-flow.git && cd nexus-flow
git checkout v0.55.0                                     # pin an exact release
cargo build --release -p nxs-server --bin nxf-relay --features dynamodb

You need cmake and a C toolchain on the build host, and you must create the two tables yourself — the relay never creates or migrates them. Their required shape is documented at the top of crates/server/src/store_ddb.rs.

If you point a released binary at NXF_RELAY_BACKEND=dynamodb, it will refuse to start and tell you exactly this: the backend is a build-time feature, and this build does not carry it.

What is not here yet

Authentication. See the warning at the top. Until it ships, treat relay reachability as the access control, because it is.
A container image. docker run …/nxf-relay is the obvious way to run this, and it is specified — but publishing a one-command way to stand up an unauthenticated shared board is the wrong order to do things in. It follows authentication.