Runbook — UNI Minecraft Colony Live Stream

The Colony & the Method · docs/RUNBOOK_LIVE_STREAM.md @ 44baf03d5041 (gen2-runtime) — opens the published snapshot ac338733bbba

8 values were removed from this page. Each one is marked in place as [redacted: category] — 1 private address, 2 operator path, 5 credential. Nothing else was altered. The document is otherwise exactly as it is written in the repository, and the sha256 below is of the original, so what was ingested stays checkable.

Three ways to read this page. Precise is the document itself, exactly as it is written in the repository. Plain and Clear were written for this website to help you meet that document — they are about it. They are not it, and they are not evidence.

Eighty-four pages about the colony. Each agent is an Elixir process holding a generative model and doing inference, attached to a body that logs into a Minecraft world as an ordinary player. Around that sit the broadcast suite that films them and the runbooks that keep the whole thing running. There are typed specifications for each organ of the model, plus the world and genome specs. There are also the adversarial review personas used to attack a proposed change before it ships.

It is for the reader curious how a running system is put together and how it is held to account. The accountability half is the more distinctive. There is a lab protocol governing evidence and attribution, and a claim fence that restricts the vocabulary a claim is allowed to use. There is a public gate log. And there is a standing invitation to reproduce any verdict from the commit and the seed named in its receipt.

Start with the public read, then the lab protocol, then the falsification invitation. If you want the mathematics rather than the operations, go straight to the typed organ specs.

What it is not: a description of a mind, and not all one kind of document. A large part of this corpus is design and planning — specs marked as proposed rather than applied, organs designed but not built, plans that were later superseded — and each page states which it is. A specification is not a running system, and these pages are careful about the difference; the reader should be too. Eight documents were withheld from publication because they describe private infrastructure.

PlainClearPrecise

Your browser cannot switch reading levels, so the document itself is shown.

This is the document. Rendered from the repository at the commit above, with nothing rewritten for the web. A gate re-renders it on every deploy and fails the build if a single byte differs.

STATUS (2026-07-11): SYSTEM 1 (v1 dev studio) doc — interim/dev only. Read STUDIO_SYSTEMS.md FIRST; it overrides on conflict. Production broadcasting = System 2 (production/).

⚠️ ARCHITECTURE CORRECTION (2026-07-12, owner-set): the COLONY (world + FEP brain + body.js bots) runs on UNI-LAB ([redacted: private-address]), rootless, "on the chip" — ALWAYS, never on THINKER; THINKER is the portable render/studio that CAPTURES it over the LAN; node2 = relay ONLY. Any "colony on THINKER" / local paper.jar bring-up in this runbook is STALE. Canonical: CLAUDE.md, ADR-PROD-013, docs/UNIVERSE.md.

How to bring the live colony + YouTube stream back up, and the gotchas that cost us hours. Machine: Thinker (Windows). Last verified: 2026-05-31.

TL;DR — start sequence

Three things to start, in order. Everything runs in ONE Elixir node (see the critical gotcha below).

# 1) Minecraft server (wait for "Done (Ns)!")
cd [redacted: operator-path]\Documents\Strings\mcserver
java -jar paper.jar nogui

# 2) Colony + Phoenix UI — ONE unified, distributed node (wait for :4000)
cd [redacted: operator-path]\Documents\Strings\ui
iex --sname uni --cookie [redacted: credential] -S mix phx.server

# 3) Start the show — open the stream page (this auto-starts the Producer),
#    or trigger it over RPC:
#    elixir --sname trig --cookie [redacted: credential] runs\trigger.exs
start http://localhost:4000/stream

Then launch OBS (profile UNI, scene collection UNI) and Start Streaming.

⚠️ CRITICAL GOTCHA #1 — ONE node only

Run the whole show in the Phoenix node: iex -S mix phx.server. Loading /stream calls SP.Producer.ensure_started() (see ui/lib/sp_ui_web/live/stream_live.ex), which starts the Producer → the single Director → the colony, all in that node.

DO NOT also run mix producer.run in a second terminal. Two nodes each spawn their own Director; they fight over camera port :3020 and the "Director" Minecraft login ("logged in from another location"), cascading into a crash loop that looks like "only 1 UNI / flapping / white video." This single mistake caused most of the pain.

⚠️ CRITICAL GOTCHA #2 — OBS dual-GPU browser source

This box has two GPUs (NVIDIA T1000 + Intel UHD 630). The OBS browser source that renders the WebGL camera page behaves badly:

BrowserHWAccel=true → browser source crashes STATUS_BREAKPOINT → white screen.
BrowserHWAccel=false (current setting) → no crash, but software WebGL renders the UNI entities yet cannot stream the terrain chunks → broadcast shows blue/empty ground while a real Chrome on :3020 renders the full forest.

BrowserHWAccel lives in %APPDATA%\obs-studio\global.ini under [General]. Robust fix for full terrain on the broadcast: window-capture a real (hardware-accelerated) Chrome window pointed at http://localhost:3020 instead of using OBS's browser source.

Key facts / coordinates

Thing	Value
Elixir node	`uni@Thinker` · cookie `sp` (hostname is capital-T `Thinker`)
Minecraft	`localhost:25565` · survival · `spawn-protection=0`
RCON	`:25575` · password `[redacted: credential]`
Good forest seed	`8675309` (inland; ocean ~1280 blocks away). Set as `level-seed` in `mcserver/server.properties`.
Phoenix `/stream`	`http://localhost:4000/stream`
Director camera (prismarine-viewer)	`http://localhost:3020`
OBS websocket	`127.0.0.1:4455` · no auth
Brains (per UNI)	`runs/colony/UNI-<kin>-<n>.bin` — delete all to start fresh
World backups	`mcserver/uni_world.bak.<timestamp>`

Reset the world (fresh forest)

Stop MC (node viewer/rcon.cjs "stop" or kill java paper.jar).
Remove/rename mcserver/uni_world, uni_world_nether, uni_world_the_end.
Set level-seed=8675309 in mcserver/server.properties (verified-good inland forest).
(Optional fresh brains) delete runs/colony/*.bin.
Start MC; it regenerates. Verify it's inland before trusting it: node viewer/rcon.cjs "locatebiome minecraft:ocean" → want it FAR (>300 blocks). A random seed can land you in a coastal/ocean archipelago (kelp + water = looks "mined out").

Populate / manage the colony

The Producer auto-maintains population in [3, 6].
Manual spawn (RPC): SP.Brain.Colony.spawn_agent(kin, "see_all") where kin ∈ 0..9.
runs/trigger.exs does ensure_started + spawns a few.

Verify it's healthy (and that they can BUILD)

# Per-UNI inventory + senses. GOOD = look=oak_leaves/grass/dirt, tree=1/2/3, wood climbing.
# BAD  = look=bedrock, tree=0, wood=0  (they dug to the bottom — reset/relocate).
elixir --sname diag --cookie [redacted: credential] runs\diag_build.exs

# What OBS is compositing (PNG):
node viewer\obs_shot.cjs "UNI Show" check.png

# Stream health: want outputActive:true, outputBytes climbing, 0 congestion/skipped.
node viewer\obs_ctl.cjs GetStreamStatus

The build chain (body.js doCraft/doPlace): mine wood → planks → crafting table → place → sticks → wooden tool (phase-2 unlock) → place blocks for shelter (phase-4). It only works if they're on a forested surface with reachable trees — that was the whole "can't build" issue (they had dug to bedrock with no wood).

Helper scripts (created this session)

viewer/rcon.cjs "<cmd>" — one RCON command (e.g. locatebiome, tp, save-all, stop).
viewer/obs_ctl.cjs <StartStream|StopStream|GetStreamStatus> — OBS via websocket.
viewer/obs_shot.cjs "<source>" <out.png> — screenshot what OBS composites.
viewer/obs_req.cjs <request.json> [out.png] — arbitrary obs-websocket v5 request.
runs/diag_build.exs, runs/trigger.exs, runs/boot_verify.exs — colony RPC helpers. (Run Elixir helpers as elixir --sname X --cookie [redacted: credential] runs\<file>.exs.)

Graceful shutdown

# 1) End the broadcast
node viewer\obs_ctl.cjs StopStream

# 2) Save + stop Minecraft (preserves the world)
node viewer\rcon.cjs "save-all flush"
node viewer\rcon.cjs "stop"

# 3) Stop the colony node cleanly (saves brains via terminate), then kill leftover body/director
#    In the iex window: Ctrl-C twice.  Or over RPC: :rpc.call(:"uni@Thinker", :init, :stop, [])
#    Then: kill any remaining node.exe whose command line matches Strings\viewer\(body|director).js

# 4) Close OBS (it saves config on a normal close)

Leave alone: the produce-uni-shorts-batch.mjs render (separate project) and unrelated node/MCP processes.

Fixes applied (branch `gen2-runtime`)

015a522 — agent.ex guards Port.command when a body dies mid-tick (no crash loop); director.js closes the prismarine-viewer + clears intervals on reconnect (no EADDRINUSE).
b693d6c — director.js tighter, down-tilted camera shots (less sky, terrain stays loaded).
6d0ba66 — docs (WorldSim build/proof plan).

sha256 14f8e79ef4605106 — of the original file, so what was ingested stays checkable.

Written for this website — not the document. This is a plain-language retelling, written to help you meet the document. It is not the source, and it is not evidence. It has not yet been checked by a person. Read the document itself → (or choose Precise in the reading-level control above)

Bringing a live colony and its stream back up is what this runbook is for, and it carries two banners saying parts of it are stale. One says a newer document overrides it on conflict. The other, set by the owner, corrects which machine the colony runs on, so any instruction here about running it locally is out of date.

What survives is the practical core. A start sequence in three steps, and the settings and addresses in a table. How to reset the world to a known good seed, how to populate the colony, how to check it is healthy, and how to shut down gracefully.

Two gotchas are called critical and are the reason the page exists. Running a second copy of one component makes two cameras fight over the same port and the same login, which cascades into something that looks like an entirely different fault. And a machine with two graphics chips renders the view badly inside the broadcast application, and the software renderer cannot draw the terrain at all, so a real browser window is captured instead. The page closes with a short list of the commits from that session, the last of which adds nothing but a build-and-proof plan.

Plain · written 2026-08-01 by claude-opus-5 · not yet checked by a person · about the document whose sha256 is 14f8e79ef4605106

Written for this website — not the document. This is a clearer retelling, written to help you meet the document. It is not the source, and it is not evidence. It has not yet been checked by a person. Read the document itself → (or choose Precise in the reading-level control above)

Bringing a colony and its stream back up is the job of this runbook, and it is honest about its own age. Two banners sit at the top. The first marks it as an interim document for an older arrangement and names a newer one that overrides it on conflict. The second is an owner-set architecture correction stating which machine the colony runs on and which machine captures it, with the explicit note that any instruction here about bringing it up locally is stale.

What remains useful is the practical core. A short start sequence gives three things to start in order, with a note that everything runs in one node, and then says to launch the broadcast application with the right profile and start streaming.

Two gotchas are marked critical, and they are the reason the page exists. The first is running a second copy of one component. Doing so spawns a second camera, and the two fight over the same port and the same login, cascading into a crash loop whose symptoms look like an entirely different problem: too few agents, flapping, or a white picture. The page says plainly that this single mistake caused most of the pain.

The second concerns a machine with two graphics chips. With hardware acceleration on, the browser source in the broadcast application crashes and the picture goes white. With it off there is no crash, but the software renderer draws the moving entities and cannot draw the terrain, so the broadcast shows empty ground while a real browser on the same address renders the full forest. The robust fix is to capture a real hardware-accelerated browser window instead of using the built-in browser source.

A table of key facts follows. It covers the node and its cookie, the game and console ports, and a known-good world seed with a note about why it is good. It covers the stream and camera addresses, where the saved minds live, and where world backups go.

Further sections cover resetting the world to a fresh forest, including a verification step to confirm the new world is inland before trusting it, because a random seed can land in a coastal area that looks stripped. Then how the population is maintained automatically within a range and how to spawn manually.

A health-check section gives the commands and, more usefully, what a good reading and a bad reading look like, with the bad one describing agents that have dug to the bottom and can no longer reach wood. It explains the build chain step by step and states that it only works on a forested surface with reachable trees, which was the whole of an earlier problem.

The remaining sections list the helper scripts written during that session, and a graceful shutdown sequence that saves the world and the minds before killing anything. Then a note about which unrelated processes to leave alone, and a short list of fixes applied with their commits, the last of them adding only a build-and-proof plan document.

Clear · written 2026-08-01 by claude-opus-5 · not yet checked by a person · about the document whose sha256 is 14f8e79ef4605106

Runbook — UNI Minecraft Colony Live Stream

How to read this page

Precise — the source document