The first executable form of our host requirements. Until now a machine was
qualified by a human reading a table of hard requirements, and a requirement
nothing can check is one that is silently optional.
It also replaces a form. Every field we wanted from a prospective host --
upstream, latency under load, spare disk, hours powered, library size, play
hours -- is measurable, and most of them cannot be answered honestly by a
human anyway: almost nobody knows their real upstream and essentially nobody
has seen their own bufferbloat figure. What is left for the questions is only
what a machine cannot know: intent, and what someone already pays.
What it does
- Checks every hard requirement: /dev/kvm, an AMD or Intel GPU with a DRM
render node, VK_KHR_video_encode_queue plus a codec, virglrenderer, the
two stores, the io cgroup controller, virtiofsd. Pass/fail/unknown, and
unknown is never collapsed into fail -- a machine we could not ask is not
a machine that failed.
- Measures upstream and, the point of the whole thing, added latency under
load. Grade bands come from the frame budget rather than convention: the
network allowance is ~40 ms because render, encode, decode, display and
jitter buffer have already spent ~58 ms.
- Reads Steam, only with an explicit yes, for library size and shape and an
hour-of-day histogram of launches -- one sample per title, which is a real
distribution obtained without asking.
- Asks at most five questions, branched, all skippable.
No server
Nothing is uploaded and no telemetry endpoint exists. The network test talks
to Cloudflare's public sink and to 1.1.1.1, neither of which is ours. Output
is a line on the terminal that the person may choose to paste. The line
carries no hostname, IP, username, game title or path -- a size band rather
than a size, hours rather than dates. The long version stays in a local
JSON file.
Three bugs found by running it, all of which would have produced wrong data
- vulkaninfo --summary lists ZERO VK_KHR_video entries where full vulkaninfo
lists five on the same machine. Preferring the summary reported "not
advertised" on a card that advertises it -- a false negative on the check
most likely to disqualify a host.
- btrfs subvolumes were counted as separate disks: /, /home and /srv each
reported 91 GiB of one 91 GiB device. Deduped by backing device, which the
two-stores check needs anyway since it wants separate devices.
- Proton and the Steam Linux Runtimes are installed like games and are not
games. Five of eight entries on the test machine, so the title count was
5x too high and the library-shape question was corrupted.
And one finding about the development connection, now encoded as a verdict:
178 ms idle RTT, served from Johannesburg. That machine passes every other
check and cannot host for a European player, because it is distance and no
upgrade shortens it. HOST-READY-LOCAL exists for exactly that case -- and it
is the coverage argument from the other end: somewhere with no nearby edge is
somewhere a local host is the only option anyone has.
Dependencies are four, three of them serde/clap/anyhow. The VDF parser, every
platform probe and the text wrapping are in-tree: a binary handed to strangers
has a dependency tree that is part of its interface.
`apps/nescapture/Cargo.toml` carried `[profile.release]` with `opt-level = 3`
and `lto = "thin"`. Cargo only reads `[profile.*]` from the workspace root and
warns about a member that writes one, so `cargo build --release --workspace`
— which is what build/Dockerfile runs — ignored it. The Vulkan capture layer
that ends up in the guest image was built at the default release profile, and
the warning saying so scrolled past on every build.
`opt-level = 3` is already the release default, so `lto = "thin"` is the only
part that was actually lost. It moves to the workspace root, where Cargo
reads it, and now applies to all five members — the same rule as
`[workspace.dependencies]` right above it: what must not differ between
members is stated once.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Three places where build/ said something the tree does not do.
- fstab mounted `/` as `rw`. A box is started with `ro` on the kernel
command line and `is_read_only: true` on the root device (every config in
nesbox's tree agrees: examples/vm.json, test.json, run.local.json), so the
virtio-blk device rejects writes whatever fstab asks for. `rw` here only
made OpenRC's `root` service attempt a remount that has to fail. The
Dockerfile already depended on the truth — it pre-creates /nestri/* at
build time precisely because a runtime mkdir gets EROFS — so this makes
fstab agree with the comment that was already right.
- build/README.md said nesbox's jail image "extracts Mesa and virglrenderer"
from this base. It extracts only Mesa. virglrenderer is the host half of
the native-context protocol and nesbox builds its own, patched, from
nesbox/patches/; nothing in this image carries it at all.
- conf.d/nestri-user-env called the zink driver-forcing block "load-bearing"
directly above three exports that are commented out, here and in the
profile.d copy. Whether they should come back is a separate question; a
comment insisting disabled lines are load-bearing tells the next reader
the opposite of what the file does. The reasoning is kept, because it is
still the reason to re-enable them, along with why both copies have to
move together.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
All three came across with their standalone repos and none had been
touched since the transport changed.
nescapture claimed to packetize with Reed-Solomon FEC and stream RTP/UDP
to a Moonlight client. It sends encoded frames to neshub over a Unix
socket. packetizer.rs, control.rs and shard_batch.rs do not exist, and
neither does ARCHITECTURE.md. Nine documented environment variables are
not read by anything -- NESCAPTURE_RTP_HOST was listed as *required* --
and five that are read were undocumented, including the one that says
where frames go. Someone following that quick start would have set a
required variable that does nothing and got no output.
Documented the three sockets, since nescapture binds one and connects to
two and that was written down nowhere.
neswire documented --rtp-addr and --channels against a gstreamer pipeline.
It has --ipc-path, --channels, --packet-duration-ms and
--bitrate-per-channel, and hub-stub exists precisely so it can be tested
without a hub. Kept the reason hub-stub decodes rather than counts bytes:
Opus codes silence at ~3 kbps, so a dead sink looks alive on a meter.
nescope was mostly right. It called the capture layer "vkcapture", listed
seven of fifteen modules and five of nine flags, and its TODO list was
three items that neshub and nescapture now do. Added compositor mode,
which is the shape a real session uses and was undocumented.
All three licence lines were "TBD" or "See project repository".
The payload-independence rule is the one thing about this repo that is
easy to violate by being helpful. Stating it where it will be read before
the first edit is cheaper than catching it in review.
Six comments across nescope, neswire and nescapture still named
nestri-guest-hub, plus one still naming nestri-protocol. Deferred from the
import commits so the rename would read as one change rather than six
unexplained edits inside otherwise-verbatim trees.
Comments only. Realigned an ASCII box in encode.rs that the shorter name
knocked crooked.
The component nescapture, neswire and nescope all talk to, and the only
thing in the guest that speaks to the client. It muxes their frames into
one iroh QUIC endpoint and fans input back.
Renamed from nestri-guest-hub, which named a location rather than a job.
Four files came across unchanged -- session.rs, ipc_listener.rs,
ticket.rs, screenshot.rs. Between them they mention Steam zero times, and
they import only nesprotocol's open modules; the control feature carrying
LaunchIntent and SteamIdentity is used exclusively by the three files that
are staying closed. The two clusters shared a main.rs and nothing else, so
there was no untangling to do -- only a cut.
main.rs loses --proton, --steamclient-so, --root and the game uid/gid,
and no longer ends by handing the process to a controller. It runs until
it is stopped. Deciding when the box is finished belongs to nesinit.
The ticket used to leave via that controller, so it needed a new way out:
neshub now serves it on a socket and nesinit dials for it. Listening
rather than dialling matches every other socket here and means no startup
ordering to get wrong.
Three tests, where there were none -- the ticket crosses a process
boundary as text now, so a round trip that drops a field would otherwise
be found by whoever cannot connect.
CLAUDE.md was 1,324 lines and all of it was about the TypeScript half, written
before there was another half. Every line of it loaded on every turn regardless
of what was being worked on, which is a real cost paid constantly for context
that is usually irrelevant.
Split by where it applies, so each guide loads when you are in the directory it
describes:
packages/core/CLAUDE.md 694 domain modules, fn(), actor, errors, auth
apps/api/CLAUDE.md 284 routes, registration, error flow
docs/alchemy.md 345 stages, bindings, secrets, the CLI
CLAUDE.md 72 the repo, both toolchains, two hard rules
Nothing was rewritten or dropped — the three files are the original text,
verified identical after the split. What the root file now carries is only what
is true repo-wide: the layout, the commands, where the detail lives, and the two
rules that are not style preferences. One of those is that nothing closed may
enter this repo, which is here because it has already been caught once.
The README described a streaming platform in four bullets and did not mention
that half the repository is Rust that runs inside a virtual machine. It now says
what each component does, why a micro-VM rather than a container, what is
deliberately absent, and what decides whether a thing is open — data is, capacity
is not.
It also says plainly that this is mid-rewrite and the docs are behind. Someone
arriving at a repo whose documentation does not match its tree should be told
that by the README rather than discover it.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A Vulkan implicit layer that captures frames from inside the workload's own
process and encodes them on the GPU they were drawn on. Fourth and last of this
batch, imported as a tree from `nestrilabs/nescapture` on the same terms.
Filed under `apps/` rather than `crates/` despite building a cdylib. The rule
here is what a thing *is*, not what it compiles to: this is a finished artefact
that gets installed into an image beside its layer manifest, not a library
another crate in this tree depends on. `crates/` is for the latter, and putting
this there would make the distinction useless the first time someone looked.
Wired to the workspace, `nesprotocol` by path. Its description named the
transport component; that reads better as what it actually is — where the frames
go — so it says that instead.
Whole workspace builds and tests: 21 across four members.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Captures a session's audio and hands it to the transport over a local socket.
Third component in, imported as a tree from `nestrilabs/neswire` on the same
terms as the previous two.
Wired to the workspace, `nesprotocol` by path. 4 tests pass.
`bin/hub-stub.rs` is a stand-in for the transport's listener, which is what lets
this be developed and tested without the rest of a box existing. It names the
transport by its old name, and is left for the rename commit along with the two
in the compositor.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A headless Wayland compositor for a single fullscreen client, and the second
component into this repo. Imported as a tree from `nestrilabs/nescope` for the
same reason as the last one: the upstream repo is private, its history has never
been reviewed for publication, and a squash is what keeps that history from
becoming permanent here.
Wired to the workspace — versions from the root, `nesprotocol` by path instead
of a sibling directory. 8 tests pass.
It knows a lot about Steam, and all of it stays. `steam_app_*` window classes,
a launcher that exits before the game it started, a client that shows a login
screen with no Vulkan frames in it: that is third-party behaviour a compositor
for games has to handle, and describing it reveals nothing about how we are put
together. The rule is about topology, not vocabulary.
Two comments still name the transport by its old name and are left for the
commit that renames it, so that rename reads as one change rather than as
noise spread across four imports.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
First component into this repo. Renamed from `nestri-protocol` — everything
else in the family carries the `nes` prefix and this was the odd one out.
**Imported as a tree, not as history.** The upstream repo is private, so its
commits and commit messages have never been reviewed for what may be published,
and squashing avoids the failure this project has already documented once: a
repo published wholesale carries private history with it, permanently. Origin is
`nestrilabs/nestri-protocol`, and this is its state today rather than its past.
The `control` module is deliberately left behind. It carries the host↔guest
control channel, and its types are shaped by a payload that has no business
being described in a public repo — a box is supposed to be able to run anything.
It was already an optional feature that nothing here enables, so leaving it out
costs nothing today and stops a boundary from being crossed by accident.
What lands is the media protocol: frames, audio, cursor, input and stats. One
definition shared by both ends, so no two can drift silently. 9 tests pass.
One pre-existing clippy warning (`input.rs`, too many arguments) is left alone
on purpose — an import commit should be a faithful copy, and mixing a cleanup
into one makes both harder to read.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This repository has been public without one, which grants nobody any rights —
the opposite of what a public repo is for, and a blocker on opening anything
else into it. Apache 2.0 was decided for this tier; this is that decision
applied, not a new one.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This repo holds both languages, so it needs both workspaces. Layout is the same
rule on each side — apps/ for what runs, crates/ and packages/ for what is
shared, split by what a thing is rather than what it is written in.
Members are empty because nothing has moved in yet. Versions are pinned once at
the root so two crates cannot disagree about a dependency.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Squashes the current state of the internal working tree onto this history.
The two trees had grown apart with no common ancestor, so this is a content
sync rather than a merge, and the published history is preserved rather than
rewritten — a force-push here would break every existing fork and clone to no
benefit.
What lands:
- Waitlist: API route, core module, and migration 0006 alongside game aliases.
- User verification.
- CI, oxfmt config, editor settings.
- Assorted fixes across the API routes and core modules.
The repository's own README, the wordmark and the per-package READMEs are kept
from this side; the internal tree had dropped them and they are what a stranger
arriving here reads first.
The marketing site in the internal tree is deliberately not here. It is a
separate product with its own repo and its own licence, and this repo is the
open one — a closed component does not belong in it regardless of how convenient
the directory looked.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Wanjohi
