Services — what each one is, what it provides, why it exists
- • The origin of every request, and the only place text is first spoken.
- • Provides: intent, judgement, and the prompt that becomes a task.
- • Why it exists: the platform has no text plane, so humans get exactly one — a glass, not an API.
- •
tartarus-ui — chat → task → result → live site page, plus Advanced (dictionary/frames/counters) and Performance pages.
- • Provides: the only text UI, a HELLO-aware TWP link to the gate, and
/api/metrics pulled from the gate's own numbers.
- • Why it exists: humans need words; everything past this box must be numbers. Cache-first results (
cached:true) keep a repeat prompt cheap.
- • Bound to host loopback with no auth — deliberately, because it is a local developer surface.
- •
tartarus-site — serves task-built sites at GET /site/<task-id>, plus .zip and POST …/push.
- • Provides: the visible artifact of a completed task, read from the sites join volume.
- • Why it exists: the point of the whole loop is that "build me a site" ends in a URL that returns 200.
- •
tartarus-pgwire — a PostgreSQL-wire shim exposing a SQL subset over the engine.
- • Provides: the migration path.
psql and existing ORMs speak to it unchanged.
- • Why it exists: the engine is the system of record, but the world's tools speak SQL — this is the honest adapter between them.
- • Honest SQLSTATEs (
42601, 22P02) instead of pretending to be a full server.
- • Zero-dependency TWP-native clients under
sdk/, wire v1 byte-pinned against the Rust crate.
- • Provides: agent identity in five languages, each with a mock gate and a live smoke test.
- • Why it exists: an agent that cannot speak the wire is an agent outside the platform. The Python live smoke is what found the real 133-word HELLO reply.
- •
tartarus-migrate — CSV / JSON / SQLite / Postgres / MySQL → engine ingestion.
- • Provides: schema → programs, rows → word tuples, foreign keys → parent links, plus watermark sync.
- • Why it exists: adopting Tartarus must not mean re-entering data by hand. Out-of-order rows are repaired, not skipped.
- •
tartarus-gate — the single write steward. Nothing writes to the engine except through it.
- • Provides: agent connections (one connection = one agent), UUID auth at HELLO with auto-kill without it,
MSG_PUT 2 / MSG_GET 3, MSG_COMPILE 5, and MON_STATS 420.
- • Why it exists: one steward means one place where permission, accounting and the vector re-index hook live. It also answers
NO_BUILDER 900 rather than failing vaguely.
- •
tartarus-engine — content-addressed store of AST trees; RAM-first with write-behind and checkpoint providers.
- • Provides:
MSG_PUT 2 / MSG_GET 3 for programs, task state, results and corrections — all addressable by hash.
- • Why it exists: it is the git replacement. Content addressing makes resubmission idempotent, caching exact and replication trivial.
- •
tartarus-hydra — the task table, difficulty-sized agent pools (1–32), plans (pipe / cascade) and telemetry.
- • Provides: messages
300 submit, 301 status, 302 result, 303 cancel, 304 list (cap 1024, restored tasks included).
- • Why it exists: scheduling and persistence, kept honest — it persists through the gate into the engine, so the private store is retired and
store_dir is one 32-byte pointer.
- •
tartarus-control-plane — agent registration and discovery.
- • Provides:
200 register, 201 peers, 202 heartbeat, 203 leave, 204 lookup; the CP address is baked into the HELLO reply.
- • Why it exists: an agent should learn where its neighbours are without a human telling it.
- •
tartarus-agent — the per-task worker binary, spawned by the hydra; the numeric-discipline guard lives in its tests.
- • Provides: one UUID-authed TWP connection per agent, work delivered as numbers, results returned as numbers.
- • Why it exists: agents replace git. They do not write code and do not speak APIs — they send words on a wire.
- • A rustc toolchain worker, configured by
builder_endpoint (172.28.0.8:7300 in the compose topology).
- • Provides:
MSG_BUILDER_COMPILE 600 in, an artifact hash out — or the single word NO_BUILDER 900.
- • Why it exists: numbers must land as something a CPU can execute, and absence must be sayable. A program that did not lower is not "absence" — reporting that as
NO_BUILDER is a lie the gate refuses to tell.
- •
tartarus-vector — vectorize() is a pure function of content: word shingles → FNV histogram.
- • Provides: k-NN over everything stored. The gate's put hook re-indexes before the write is acked, so an ack means indexed.
- • Why it exists: semantic recall without ever storing a vector twice. Boot pull is the one bootstrap exception; watermark catch-up uses the index's own hash set, and drop-and-rebuild returns identical k-NN.
- •
tartarus-graph — node/edge/subtree views over the same ASTs (410–414).
- • Provides: structure queries — who calls this, what does this subtree contain, what would an edit touch.
- • Why it exists: it is a cache, and it is honest about being one. Delete the frames and they rebuild from engine content byte-identically.
- • Foreign edges where text ⇄ numbers happens — and only here. Inside the core everything is
u64.
- • Provides:
translate caches by task_id (a repeat prompt is a cache hit, and the cache survives a container recreate), correct persists fixes as data, inspect reads AST as text for humans, learn touches derived views only.
- • Why it exists: models do not speak numbers well, and pretending otherwise would corrupt the core. Each is a registered edge, not a leak.
- •
tartarus-watchdog, tartarus-heal, tartarus-metrics.
- • Provides:
MSG_WD_HEALTH 500 polling, RSS sampling with ceiling-kill + restart, incident events on UDP 27901, and nine-word telemetry datagrams on UDP 27900 (SRC 1–8).
- • Why it exists: the stack has to survive a bad agent at 3 a.m. Ops observe and restart — they never write content; every write still goes through the gate.
- •
tartarus-mesh + tartarus-net — direct sealed sessions between nodes, not routed through the gate.
- • Provides:
ANNOUNCE 111 → MISSING 112 → FRAME 113 hash-driven delta replication; the announce (PEER_PING 106, six words) is the only unencrypted frame.
- • Why it exists: routing neighbour traffic through the gate would make the gate a bottleneck proportional to mesh traffic and give it the ability to read what it routes. Converged nodes re-sync in 0 bytes.
- • The same engine + gate + TWP on bare metal: no Linux, no kernel. TWP rides virtio-net rings; the store persists to virtio-blk.
- • Provides: a 943-byte session instead of a 4–32 KB kernel socket — the density that models 1–2M agents per node — with 21/21 numeric cases in-guest and hash-verified write → reboot → re-read.
- • Why it exists: u64 streams are what FPGAs and ASICs eat. The wire formats are designed to become the chip spec; the plane is a target, not a rewrite.
- • Pinned IPs so config is static: gate
172.28.0.2, hydra .3, control plane .4, console .5, watchdog .6, site .7, builder .8.
- • Provides: named volumes —
tartarus-store, -hydra, -sites, -journal, -artifacts.
- • Why it exists: a named volume inherits the image dir's ownership on first mount. Get that wrong and persistence fails silently — which is exactly what bit us once.
- • Posture: uid 65532, read-only rootfs,
cap_drop: ALL, no-new-privileges, pids_limit, console on host loopback only.