A Rust workspace for the Selvage Session Protocol. selvaged is a memory-only
reference server that seats peers in a room and relays sealed frames it cannot
read; the client library the protocol is proved with lives beside it. This
repository is the protocol's reference implementation. A client with a host-run relay does not need this process for its own room. With the editor clients documented in docs/rooms.md, the host starts selvaged separately or joins an existing server, then gives the editor its address. selvaged is kept as the conformance server the wire vectors replay against and as an optional standalone relay for testing. See the specification's docs/peer-host-relay.md; guests reach a host-run relay over Tailscale or a LAN.
The published image is the server alone, and a server alone is enough for a client
to join a room; the page is a second container, and the pair is printed by the
landing page's Run card, which owns the reader-facing commands: the three steps it
prints name the repositories bare, which docker reads as :latest — the tag the
release publishes — and it prints no teardown, so stopping the pair is docker stop
or docker rm -f, a step it leaves to the reader.
docker rm -f selvaged-solo 2>/dev/null
docker run -d --rm --name selvaged-solo -p 127.0.0.1:8081:8080 \
ghcr.io/selvage-protocol/selvaged:latestThat is re-runnable: the removal clears the name a previous run left, and --rm
takes the container with it when it stops. Stopping it later, and taking it with
its logs, is a command of its own:
docker rm -f selvaged-soloThe name and the host port above are this example's own, so it and the card's pair
can be up at once: the card's server runs as selvaged and its page publishes
8080, so stopping either pair leaves the other's container alone. A client reaches
this container at ws://127.0.0.1:8081 — the host port the mapping above publishes.
Both GHCR packages are public, so a pull needs no account and no docker login.
Deploying has the other addresses a client might be pointed at,
and why they do not answer.
With Nix, cargo and rustc come from the flake, so run cargo through the dev
shell:
nix develop . -c cargo run -p selvaged -- --listen 127.0.0.1:8080Without Nix, install Rust via rustup
(any recent stable works), and the same cargo run needs no other setup. For a
binary to keep, build it release and run that:
nix develop . -c cargo build --release --locked -p selvaged
./target/release/selvaged --listen 127.0.0.1:8080The image is the server alone, on one port:
docker buildx build --load -t selvaged:local .
docker run --rm -p 127.0.0.1:8080:8080 selvaged:localdocker compose up builds the same Dockerfile through compose.yaml, which runs
it beside the published page image, both read-only with every capability dropped.
This is the route for an image you are changing, or one built from your own
checkout.
To serve a page from that container, mount a directory and name it with
--serve-page: the image carries none, and its own command passes no such flag.
docker run --rm -p 127.0.0.1:8080:8080 -v "$PWD/page:/page:ro" \
selvaged:local --listen 0.0.0.0:8080 --serve-page /pageThe flake's default package is selvaged, so nix run builds the binary and
starts it with the same flags:
nix run . -- --listen 0.0.0.0:8080selvaged is one binary with no configuration file, and the flags below are the
whole of its surface:
usage: selvaged [--listen ADDR] [--room-grace-ms MS] [--serve-page DIR]
[--max-connections N] [--max-rooms N] [--max-peers-per-room N]
[--outbound-queue-bytes N] [--max-envelope-bytes N]
[--inbound-bytes-per-sec N] [--inbound-burst-bytes N]
What it prints, and its flags has the startup line, every flag with its default, and which of those bounds are per process and which are per connection.
--help prints the usage line, a short description of the server, and every flag
with its default. --version prints selvaged/<version>.
- What it prints, and its flags: the startup line and the flag defaults.
- What happens at a limit: what a peer sees, and how to size a box.
- The server's shape: rooms in memory, the grace period and
/meta. - The first room: who mints a room, and which clients host or join.
- Deploying: the addresses a client dials, the bind and TLS.
- Publishing: version tags, release gates, and partial-release recovery.
- Serving the page:
--serve-pageand the served headers. - Licence: what each path is under, and what the image carries.
The server is FSL-1.1-MIT, source-available and not open source; the workspace
default is MIT OR Apache-2.0, which covers crates/protocol, crates/client and
crates/harness, and vectors/ is vendored from the specification repository under
CC-BY-4.0. Licence has the terms, the paths and what the
published image carries.