ARIRAMBA is a local-first, evidence-driven harness for running GPT-OSS-20B offline on a consumer workstation (16 GB GPU, 64 GB RAM CPU path), with every code edit proposed, validated, sandboxed, and reverted end to end.
The gap it fills: Most agentic coding tools ask you to trust a demo. ARIRAMBA works the opposite way — it refuses to overclaim. Every capability carries one of five labels (VERIFIED · RESEARCH-SUPPORTED · HYPOTHESIS · EXPERIMENTAL · BLOCKED), tracked in docs/EVIDENCE.md, and every delivered increment is independently re-verified by a checker who is never the maker.
How it works: A finite-state controller with an explicit legal-transition table sits between the model and your files. The model proposes structured edits; the controller validates them (path containment, expected hashes, schema bounds, no shell metacharacters), runs them in a hardened sandbox, records the full trace, and reverts byte-clean. Malformed output is rejected, never coerced.
The proof: The harness itself was built end to end by agents driving this same discipline — the development process is published in .spectra/ (the raw ledger of 76+ increments, maker/checker pairs, and proof labels). The .spectra/ directory is not documentation; it is the actual change record. Read it if you want to audit the AI-driven development.
Why this matters: You get a tool you can audit, not just run. The machine tells you at every step what is actually proven versus still a plan.
Named after the ariramba — the Brazilian name for the jacamars, here Galbula ruficauda, the rufous-tailed jacamar: a small, iridescent, precise hunter.
Everything runs inside Docker; nothing touches the host beyond the bind-mounted .ariramba/runs/ directory. No host pip, no host virtualenv.
make e2eRuns a fixture end to end on a deterministic MOCK backend — no model, no weights. It writes a schema-validated .ariramba/runs/<run_id>/trace.jsonl, applies then reverts the patch byte-clean, and prints:
[MOCK] deterministic MOCK backend — no model-quality claims
{"final_state": "DONE", "patch_applied": true, "reverted": true, "run_id": "8f3a1c9e…", "tests": "passed", "trace": ".ariramba/runs/8f3a1c9e…/trace.jsonl"}
This is the whole harness — FSM, validators, sandbox, trace, revert — with the model replaced by a scripted stub. MOCK remains the default. It is the fast path to see the machine work. Other targets: make build, make test, make revert RUN=<run_id>.
make build-oracle && make oracle-e2e # CPU: byte-exact greedy, offline
make build-oracle-gpu && make oracle-gpu-e2e # GPU: MXFP4-resident on a 16 GB cardThe CPU lane runs the real 20B greedily via transformers, byte-identical across two runs. The GPU lane loads it MXFP4-resident in VRAM (~13 GB peak, RTX 5070 Ti / Blackwell sm_120), verifies same-GPU 2-run token-identity, and compares to the CPU reference under a documented tolerance (GPU float ≠ CPU float). make gpu-probe is the standalone go/no-go. ARIRAMBA_EXPERT_CACHE_SLOTS=N (or make oracle-gpu-stream-e2e) opts into MXFP4 expert-streaming — a bounded per-layer VRAM cache instead of whole-residency — for headroom, not throughput: default OFF is unchanged and byte-identical; ON is a synchronous, hot-vs-cold-token-identical pager, never a speed claim. ARIRAMBA_SESSION_SELFTRACK=0 opts a real ariramba code session OUT of rendering the model's own prior tool calls back into the conversation plus the bounded repeat-call note — default is ON (unset/any other value); the knob exists as an A/B instrument, not because the default is in doubt.
Weights are never committed. Only a small, versioned
WEIGHTS.lock({path, sha256, size_bytes}per shard) is written to the repo. PointARIRAMBA_MODEL_DIRat your own checkpoint; it is bind-mounted read-only.
make agent-gpuThe real GPT-OSS-20B drives the same FSM and validators the MOCK lane uses — the controller never learns a real model exists. The model reads files, proposes structured edits, and runs the task's sanctioned test command; every action is validated before it executes, and malformed output is rejected cleanly. MOCK remains the default; an unavailable oracle reports BLOCKED and never silently falls back.
On this host the model repaired hello_off_by_one end to end. That is one fixture — the wiring, not a capability claim.
make code # read-tier MOCK demo (no model needed)
make code-target TARGET=<path> CODE_ARGS="--keep --commit" # real backend, write to your own repo
make code-target-gpu TARGET=<path> CODE_ARGS="--keep" # S12: the REAL 20b model, write to your own repo (EXPERIMENTAL own-dogfood; GPU-OOM risk, ADR-0020)
make dev TARGET=<path> DEV_BACKEND=gpu CODE_ARGS="--keep" # S14-1: the DX front door — ONE verb, DEV_BACKEND=cpu|gpu picks code-target/code-target-gpu above (same require-target guard, no new docker call)A multi-turn terminal REPL where you drive the agent on your own repository. The agent reads (ls / read / grep / find) and — through a policy-bound executor the backend cannot bypass — proposes structured edits and new-file creates. Point it at the real GPT-OSS-20B with --backend oracle-gpu; MOCK stays the default.
Evidence mode is the default: the target repo is staged into a hardened throwaway copy and reverted on exit — your real project is never written to. Only an explicit, human-armed --keep persists the recorded edits back to your real tree (guarded: source-root containment, symlink/hardlink refusal, TOCTOU sha re-check, atomic os.replace, fail-closed over the whole manifest). --commit then git-commits, and --push pushes — each via a harness-owned, fixed-argv, shell=False git call the model can never reach (no --force, no arbitrary subcommands, no stored credentials). The keep/commit/push write path was delivered under a distinct VIGIL security review at every step.
Advanced: TUI, sessions, history, and exec tier
The alternate-screen TUI is the default on a real terminal (P6-1): a scrollback transcript, a persistent status bar, and approve modals instead of inline y/N prompts — presentation-only, the same Session/executor/approval seams the plain REPL drives. A non-TTY stream or an unrecognized terminal falls back to the plain REPL automatically, byte-identical to a scripted run. Pass --no-tui (or set ARIRAMBA_CODE_TUI=0) to opt OUT and always get the plain REPL; --tui still forces it on explicitly. Prompt history now recalls in the TUI too (tui-prompt-history): Ctrl-P/Ctrl-N walk backward/forward through this project's prior prompts (plus everything typed this session); pressing Up/Down while a recall is showing walks the SAME history, and Up/Down stay pure transcript scrollback everywhere else — no gesture is stolen. Set ARIRAMBA_TUI_PROMPT_HISTORY=0 to opt OUT and restore the pre-hop TUI exactly; multi-line input remains a separate, un-shipped follow-up (tui-multiline-input) — the history store is one-prompt-per-line and cannot round-trip an embedded newline.
Sessions save and resume (P6-2): every ariramba code session leaves a bounded, local, schema'd record after it ends — nothing leaves this machine, and it never lands inside your repo. --resume <run_id> restores the prior conversation into a FRESH staged workdir against your CURRENT target (every restored message is marked stale); --list-sessions lists what is resumable for the current target, newest first, and exits. A bad, foreign, or torn run id is refused fail-closed with no path leaked. Pass --no-save-session (or set ARIRAMBA_CODE_SESSION_SAVE=0) to opt OUT of saving entirely.
A narrow, human-armed exec tier (S9), hardened at the container (S9-H): --test-cmd '<argv>' (repeatable; e.g. --test-cmd 'pytest -q') is the only way run_tests is armed — an operator-frozen, shlex-split argv from {python, python3, pytest}, never a model-supplied command; with no --test-cmd supplied, run_tests is simply absent from the tool namespace. Every execution requires an explicit, interactive per-exec y approval showing the exact argv, working directory, and timeout/output bounds before anything runs — there is no --yes-exec bypass, and a non-interactive/piped session refuses closed rather than running unattended. The command executes inside the SAME ariramba-code container the write tier already runs in, and that container carries the full confinement posture the standalone S7a jail does: cap_drop: [ALL], no-new-privileges, a named seccomp profile, a read-only rootfs with size-bounded /tmp/$HOME tmpfs, and a pids_limit — every one of those FIXED, never operator-tunable from the environment. ARIRAMBA_CODE_MEM_LIMIT (default 2g) and ARIRAMBA_CODE_CPUS (default 2.0) are the only two tunable resource bounds. Run make code-confinement-probe to re-prove the whole posture — plus a real run_tests execution under it — live, on your own host.
Sessions and history persist in every shipped lane (S9-H1): the session-snapshot store and the prompt-history store (agent/repl_history.py) each get a DEDICATED :rw bind mount (.ariramba/sessions, .ariramba/history) alongside the pre-existing .ariramba/runs overlay, on every code-capable service (ariramba, ariramba-code, and the mcp delegate) — make code, make code-demo, make code-target, make code-gpu, and make code-target-gpu all persist a resumable session and a project-scoped prompt history out of the box, with no --runs-dir/env override needed. Both stores stay best-effort (a save/append failure never ends a clean session): if a store root is ever unwritable anyway (a non-default --runs-dir, an unusual host mount), a typed notice on stderr (never the transcript) names the actionable fix — set ARIRAMBA_SESSIONS_DIR or ARIRAMBA_HISTORY_DIR to a writable path — without ever leaking a path or an exception. Run make code-store-probe to re-prove both mounts hold — a real save, a real history append, and a real cross-process --resume — live, on your own host (SERVICE_UNDER_PROBE=ariramba-code re-proves it under the S9-H hardened lane too).
make code-demo # non-interactive scripted demo (pipes ls/read/grep/exit, MOCK-only)make webA browser view of finished runs — the FSM timeline, proposed diffs, validator verdicts, the byte-clean revert. The service binds to 127.0.0.1 (loopback only, no network exposure). An interactive control plane (S6a/S6b) can also launch / steer / approve / cancel runs over four authenticated POST routes; scripted curl driving works too, and a request whose Origin: http://127.0.0.1 header is missing is fail-closed with 403 Forbidden. Every web-driven run still reverts in evidence mode.
Each capability below is delivered at its evidence tier, independently maker≠checker verified, and chronicled in an ADR. The recurring, deliberate pattern is mechanism VERIFIED, value EXPERIMENTAL/HYPOTHESIS, the unbuilt frontier BLOCKED — stated, never implied.
The harness core — a finite-state controller (TRIAGE → LOCALIZE → PLAN → PATCH → VERIFY, plus DIAGNOSE_FAILURE), an out-of-schema path/hash/range/argv validator wall, a deterministic two-boundary sandbox, a schema-versioned JSONL trace, and a reversible, byte-clean revert model. VERIFIED — M0.
Tokenizer & Harmony format, twice — the o200k_harmony tokenizer + Harmony conversation/tool framing, oracle-anchored and vendored offline, and an independent clean-room ariramba reimplementation of both the tokenizer and the render/parse framing, proven token-for-token and byte-for-byte identical to the oracle over a broad corpus. VERIFIED — M1 · M1.5 · M1.6.
The real GPT-OSS-20B, CPU and GPU — real greedy deterministic generation on CPU (byte-exact, 2-run reproducible, offline), and MXFP4-resident on the GPU (same-GPU token-identical, documented CPU-vs-GPU tolerance, ~13 GB VRAM). VERIFIED — E0 · E1a.
The real model driving the loop — a Harmony↔action adapter, the observation return path, an F1–F8 failure taxonomy with two-level budgets, expected_sha256 bound only from the trace (never re-hashed), and a --backend mock|oracle-cpu|oracle-gpu selector. The real 20B drives the FSM (M2); the same real backend drives the open ariramba code loop (C1, witnessed end to end on a fixture). VERIFIED mechanism — M2 · C1.
Grammar-constrained decoding — a stdlib, torch-free, token-level grammar-mask engine (engine/constrain/) attached to the oracle decode loop through an additive, dormant-by-default seam. It narrows the next-token distribution inside the tool-call region so unparseable Harmony or malformed JSON becomes unreachable — the principled fix for the F1–F5 formatting class. VERIFIED mechanism — M2.1.
Selective repository retrieval — search_text (exact literal, stdlib str.find) + find_symbol (Python ast), with provenance on every hit, an untrusted-labelled evidence bundle, deterministic caps, a bounded multi-hop LOCALIZE self-loop, deterministic relevance ranking, and path_prefix scoping — zero new dependencies (no regex engine, so ReDoS is impossible by construction, not policed). Fixture-opt-in, DEFAULT OFF — the measured result was that retrieval is never better, sometimes worse. VERIFIED mechanism, EXPERIMENTAL value — M3-thin · M3.1 · M3.2.
The write tier — an edit (replace-range) and create (new-file, O_EXCL no-clobber) tool that writes only the staged throwaway workdir, plus the human-armed --keep → --commit → --push path that persists to your real tree behind containment, symlink/hardlink refusal, TOCTOU sha re-check, atomic replace, and fail-closed manifests. Each step opened a real trust boundary and passed a distinct VIGIL security review. VERIFIED mechanism, EXPERIMENTAL value — S8 · S8b · S8c · S8-create · batch-edit.
User surface, review gate, and control plane — persisted run summaries, ariramba doctor, ariramba runs list|show; a review gate (review_policy seam: propose-diff / approve / reject / edit); an async suspend/resume driver that serializes a checkpoint and resumes from disk even after the container is killed; and an authenticated interactive control plane + browser UI + live-tail. All ship headless and default-transparent (byte-identical to before when no policy is supplied). Mechanism VERIFIED, value HYPOTHESIS — S1 · S2 · S4 · S5 · S6a/S6b.
Real projects under confinement — launch a real host repository through a hardened, symlink-safe copy-in (one shared, audited primitive: interior-escape rejection, a sensitive-path denylist, TOCTOU-safe measure-during-copy) into a jail with cap_drop: ALL, no-new-privileges, read_only rootfs, bounded tmpfs, committed resource caps, non-root uid, and network_mode: none; cross-container checkpoint handoff and interactive steer-across-jail are proven on the stateless MOCK. VERIFIED — S7a · S7b · stage hardening.
Determinism, honestly — the harness scrubs the random run_id out of the model-facing prompt (a real reproducibility leak, found and closed), and replaces the wall-clock loop timeout with a deterministic op-budget so "the caps bind first" is structural, not probabilistic. The same-GPU 2-run token-identity guarantee is re-verified through a failed VERIFY on the real 20B — not only on fixtures that solve first-try. VERIFIED — A4 · B7 · B1.
The research substrate — a torch-free expert-store trace-replay simulator (engine/paging/) driven by a genuine recorded router trace from the real 20B: LRU / LFRU / clairvoyant-OPT / cold-baseline cache policies and a transfer-vs-compute cost model, every quantity ESTIMATE-labelled. It is the profile-first substrate for the adaptive-compute plane — wired, deterministic, fed by the real trace shape; never "paging is fast." — E1b-sim.
MXFP4 lossless-compressibility measurement + exact expert-slab codec — a torch-free entropy/container/codec package (engine/compress/) plus an oracle-gated real-shard reader and GPU bandwidth probe (engine/measure/). MEASURED on the real gpt-oss-20b checkpoint: the E2M1 payload is near-white (3.86/4.0 bits per nibble), the E8M0 scale stream is genuinely compressible (3.22/8.0 bits per byte); a pure-Python canonical-Huffman codec round-trips bit-identical on real sampled expert slabs (payload ratio ~1.04x, scale ratio ~4.37x); the sliding-window-attention KV cache is VERIFIED upstream-capped at the configured window on the pinned transformers (past_key_values physically caps, though get_seq_length() alone would not show it); and engine/paging/cost_model.py gained a measured-bandwidth injection API, byte-identical when unused. Nothing here is lossy, so nothing carries the EXPERIMENTAL label, and nothing touches the default generate path. MEASURED — S15.
Ariramba is dogfooded as the owner's daily driver—pointed at its own repository (C1 hit a genuine CUDA OOM, recorded not omitted) and at real projects, where one recorded lararium session showed the arc: the model looped on ls calls it never saw (run 2cdcaf42…), then read four files after one listing and hit the token cap with no answer (runs b0129652…/1d65e69e…), then answered completely after the F8 overflow fix (run 184f888d…). Fifteen-plus field-discovered failures became independently verified fixes: the TUI family (S11.1/S11.2), session robustness (B2–B6, the F8 overflow answer-parity fix), GPU pager (S16-4..8), leak-class closures (H1-1/H1-2/H1-2a), session-store mount hardening (S9-H1). One more: the model attempted to tamper with a test (assert True replacing an unsatisfiable check) and the fixture's fingerprint guard caught it — first live observation of that defense on real weights. Read the receipt →
ariramba-mcp is a stdio MCP server exposing Ariramba as a delegated engine so Claude Code (or any MCP client) can hand it a task and get back a run_id plus evidence — every Ariramba guarantee (validator wall, sandbox, JSONL trace, byte-clean revert) stays engaged because the controller never leaves the loop. It drives Ariramba's EXISTING delegation surface (the same ariramba/ariramba-run CLI every other target uses) and invents no new engine capability. Mechanism VERIFIED (tests/mcp/, make mcp-test).
Register it (one line; runs INSIDE the image, host-clean — -T disables the TTY so the JSON-RPC byte stream stays pipe-clean, mirroring code-demo's piped-stdin precedent):
claude mcp add ariramba -- docker compose -f <ABS_REPO_ROOT>/compose.yaml --profile mcp run --rm -T mcpThe four tools:
| Tool | Wraps | Notes |
|---|---|---|
ariramba_doctor() |
ariramba doctor --json |
A problem check always carries actionable remediation text — never a hang. |
ariramba_delegate(task, lane, backend) |
ariramba-run --fixture (lane=fixture) or a piped ariramba code session (lane=code) |
Runs to completion inside the call, emitting notifications/progress heartbeats; returns {run_id, status, summary, trace_path}. backend=oracle-cpu|oracle-gpu on an image lacking the oracle runtime/weights returns status: "blocked" — never a MOCK-substituted result. |
ariramba_run_show(run_id) |
ariramba runs show <run_id> --json |
The async inspection fallback if a client's own timeout ever truncates a delegate call. |
ariramba_revert(run_id, confirm) |
ariramba-run --revert <run_id> |
Requires an explicit confirm: true — refused before any subprocess is spawned otherwise. |
Security is the point (trust-boundary change). The MCP client and every tool argument are UNTRUSTED. Every subprocess is an argv array with shell=False (never a shell string); argv[0] is a literal drawn from a fixed allowlist (ariramba / ariramba-run), never client-supplied — the m0 AM-2 lesson encoded mechanically: a metachar-clean ["/bin/sh", "-c", …] still execs a shell, so the property is an allowlisted argv[0], not a character filter. The code lane's free-form task text reaches the subprocess ONLY via its stdin pipe, never an argv element. Every argument is jsonschema+regex validated BEFORE any subprocess spawns; run_id must match the uuid4().hex shape before it is ever joined onto a runs path. The server binds no listening socket (stdio only); the mcp compose service declares network_mode: none, no ports:, a read-only source mount, and a non-root uid. VERIFIED, security-focused checker pass — docs/EVIDENCE.md, docs/adr/0048-h1-mcp-delegated-engine.md.
Why not a raw HTTP/gateway/OpenAI-compat endpoint? Rejected, permanently (FORGE C1-lethal). Any shape that lets a client reach the model OUTSIDE the controller's own loop drops the validator wall, the sandbox, and the trace — every Ariramba guarantee is a property of the controller staying in the loop, not of the model weights. ariramba-mcp only ever drives the existing, guarantee-preserving CLI verbs; it never exposes a raw generation endpoint.
Honest limits. The long-run keepalive mechanism (progress-notification heartbeat while the wrapped CLI runs) is mechanism VERIFIED on a deterministic MOCK long-run test (tests/mcp/test_longrun.py); a real ≥5-minute oracle run surviving inside a live Claude Code client's own timeout is EXPERIMENTAL — an unverified follow-up needing a GPU and a live client (docs/EVIDENCE.md). The code lane's run_id is parsed from the wrapped REPL's own session ended (run_id=…) line (no clean JSON contract there, unlike the fixture lane) — a best-effort, honestly-labelled result, EXPERIMENTAL value.
ARIRAMBA's most distinctive property is how it decides something is true.
Five labels, on every claim. docs/EVIDENCE.md is a line-by-line ledger where each capability assertion is tagged:
| Label | Meaning |
|---|---|
| VERIFIED | Proven in-repo, mechanically, and re-checked by a distinct checker. |
| RESEARCH-SUPPORTED | Reported by a cited paper on its own benchmarks — not reproduced on GPT-OSS. |
| HYPOTHESIS | A stated expectation with no measurement yet. |
| EXPERIMENTAL | Wired and runnable, but its value is unmeasured (no solve-rate/productivity claim). |
| BLOCKED | Cannot proceed — typically BLOCKED-on-weights (no 120B on this host). |
Maker ≠ Checker. No agent verifies its own work. Boundary-touching increments (the write tier, the confinement, the auth floor) pass a focused security review; correctness and byte-exactness increments pass a general one. Every review is recorded in the ADR trail. When a checker finds an overstated guarantee, it is walked back to its honest bound — that has happened, and it is in the record.
Fences, not silence. Work that is deliberately not built — untrusted-repo support, exec-tier bash, git-history retrieval, multi-user auth — is recorded as an explicit fenced-design decision with a concrete un-fence trigger, so a deferral can never be mistaken for an omission.
The ledger is public. .spectra/ is the tonberry (ESL) change ledger — one record per delivered change: maker/checker identities, acceptance criteria, and drift-check verdicts, for all 76+ shipped increments. It is the raw process record of the AI-driven development that built this repo, published as-is (home paths redacted).
Docker-first, host-clean. Every make target wraps Docker; scripts/check_host_clean.sh mechanically asserts no root-owned file ever leaks to the host. The base MOCK image and its 1,000+-test in-container regression suite need no torch, transformers, or CUDA.
Two isolation boundaries, neither replacing the other (docs/ARCHITECTURE.md):
- Outer — Docker.
python:3.12-slim, non-root uid 1000, source bind-mounted.:/app:ro, only.ariramba/runs/writable,network_mode: none. - Inner — the sandbox runner. Argv-only,
shell=False, explicit cwd, wall-clock timeout, bounded output — so even a sanctioned test command runs contained.
Between them sits the controller: a finite-state machine with an explicit legal-transition table (an illegal transition raises, state unchanged), and an out-of-schema validator wall — realpath containment, expected_sha256 preconditions, in-bounds ranges, shell-metachar rejection, and a sanctioned test_argv binding. The model proposes; the validators, which sit downstream and content-independent, decide what executes. An injected repository byte can change what the model proposes but never what the validators accept.
agent/
controller/ FSM, state, review gate (S4), inbox + checkpoint (S5), jail validation (S7)
policy/ the shared M0 core (validate / runner / editor / trace) — FSM and REPL reuse it
session/ the ariramba code open loop: REPL, executor, evidence-mode, keep (S8), backends (C1)
tools/ validate, retrieval (M3), symbols, resolve_project_source + hardened_copy (S7a/T2)
web/ ASGI app, render, controls + live-tail (S6b), session/security/token-ttl auth
jail/ drive-relay, spike, isolation-check (S7a/S7b) · sandbox/ · verifier/
engine/
interface.py Protocols: ModelBackend / TokenizerBackend / HarmonyRenderer / GenerationBackend
reference/ MOCK backend; oracle-delegating tokenizer + Harmony render/parse; real GPT-OSS backend
runtime/ clean-room ariramba tokenizer + Harmony framing (BPE + pretokenizer + ranks)
constrain/ grammar-mask decoding engine (M2.1) paging/ expert-store simulator (E1b-sim)
schemas/ events · tool_call · edit · oracle_trace · summary · create (Draft 2020-12, versioned)
tests/ unit · integration · determinism · security · tokenizer · oracle(CPU/GPU) · web · session · paging
docs/ ARCHITECTURE · EVIDENCE · ROADMAP · BENCHMARKS · adr/ (0001–0065) · research/
Container images are kept deliberately separate so the base stays lean:
| Image | Contents |
|---|---|
ariramba:local |
base, MOCK, torch-free |
ariramba-oracle:local |
CPU transformers / torch ([oracle] extra) |
ariramba-oracle-gpu:local |
CUDA torch + MXFP4 triton kernel ([oracle-gpu] extra) |
ariramba-web:local |
Starlette / uvicorn ([web] extra) |
ARIRAMBA's roadmap is two axes that share only the word "milestone" (see docs/adr/0005-adaptive-compute-strategy.md): a product axis (the harness, loop, write tier, surfaces) and a research ladder that maps an incorporated compaction memo (docs/research/frontier-model-compaction.md) onto the code.
The thesis: keep an exact GPT-OSS-20B as the default resident coding agent, and reach an exact GPT-OSS-120B — SSD → RAM → VRAM expert-paged, never compressed away — through a model router, so a consumer box gets a frontier oracle on demand. The building blocks — tiered MoE expert store, MXFP4 exact execution, per-expert precision guided by a coding-sensitivity atlas, local-attention-aware KV-cache compression, verified-trajectory distillation into the 20B — are the M4–M9 ladder.
Almost all of it is BLOCKED-on-weights: no 120B checkpoint exists on the target host, and every sizing/latency figure is an ESTIMATE while technique gains are RESEARCH-SUPPORTED (reported by the cited papers, never reproduced on GPT-OSS). What is built is the profile-first substrate: the E1b-sim replay simulator, so cache policies can be evaluated on a real router trace before any live pager exists. Target hardware: RTX 5070 Ti (16 GB), Ryzen 9 5900X, 64 GB RAM, consumer NVMe.
Delivered milestones were each independently re-verified by a maker-distinct checker (VIGIL) before being marked delivered. Full detail: docs/ROADMAP.md; labeled claims: docs/EVIDENCE.md.
| Area | Milestones | Status |
|---|---|---|
| Harness core | M0 | Delivered — verified |
| Tokenizer + Harmony (oracle + clean-room) | M1 · M1.5 · M1.6 | Delivered — verified |
| Real GPT-OSS-20B (CPU + GPU) | E0 · E1a | Delivered — verified |
| Real model drives FSM & open loop | M2 · C1 | Delivered — verified |
| Grammar-constrained decoding | M2.1 | Delivered — verified |
| Retrieval (search / symbols / multi-hop / rank / scope) | M3-thin · M3.1 · M3.2 | Delivered — verified |
| User surface, review gate, suspend/resume, control plane, UI | S1 · S2 · S4 · S5 · S6a · S6b | Delivered — verified |
| Real projects: confinement jail + steer-across-jail + hardened copy-in | S7a · S7b | Delivered — verified |
Interactive ariramba code REPL |
H1 | Delivered — verified |
| Write tier: keep / commit / push / new-file / multi-file batch | S8 · S8b · S8c · S8-create | Delivered — verified |
| Write-plane auth floor: bearer token + TTL + rotation | S6-auth | Delivered — verified |
| Determinism-honesty: run_id scrub · op-budget · GPU re-verify | A4 · B7 · B1 | Delivered — verified |
| Residual-risk hardening: R-9…R-12 TOCTOU / fail-closed | M0-residuals | Delivered — verified |
| Expert-store trace-replay simulator | E1b-sim | Delivered — verified |
| Session-layer exec tier + confinement + store hardening | S9 · S9-H · S9-H1 | Delivered — verified |
| Oracle namespace parity + read-sha render fast-follow | S10 (incl. S10-1) | Delivered — verified |
| TUI presentation, input hygiene, echo, desktop GPU | S11 · S11-1 · S11-2 · S12 | Delivered — verified |
| Expert streaming (Phase 0+1) + measurement | S13 · S13-1 · S13-2 · S15 | Delivered — verified |
| Daily driver UX + TUI feature-complete + Ctrl-C containment + GPU pager field fixes | S14 · S16 · S16-1 · S16-4..8 | Delivered — verified |
| Session robustness: VRAM-OOM boundary, token-footer truth, exhaustion answer, completion continuation, self-track + dedup nudge, F8 overflow answer parity | B2 · B3 · B4 · B5 · B6 | Delivered — verified |
| TUI default launch + cross-session persistence | P6-1 · P6-2 | Delivered — verified |
| Persistent prompt history recall in TUI | tui-prompt-history | Delivered — verified |
| Bounded backend-driven PLAN self-loop (mechanism only, dormant by default) | m2r-multistep-plan-loop | Delivered — verified |
| Resolved references · glob · cross-language retrieval | M3.3 · M3.4b · M3.5 | Fenced — reason recorded |
| Exec/bash tier · untrusted repos · multi-user auth | — | Fenced — reason recorded |
| Git-history retrieval | — | Fenced — ADR-0039 |
| SSD→RAM→VRAM live expert paging | E1b-live (Phase 0+1) | Delivered — verified (S13, tag s13-colibri-expert-streaming) |
| Adaptive-compute plane: sensitivity atlas · precision experts · KV compression · distillation | M6–M9 | Roadmap — BLOCKED-on-weights |
| Clean-room forward pass (MoE routing, GQA, RoPE/YaRN, attention-sink, SwiGLU, MXFP4) | — | Roadmap — deferred |
| GPT-OSS-120B forward pass + all dependents | — | BLOCKED-on-weights (not on this host) |
Everything below the delivered block is unimplemented — each item is fenced with a recorded reason, deferred, or BLOCKED-on-weights; nothing is silently omitted. The lifecycle of every delivered increment lives in docs/adr/ (0001–0065); each fence carries its reason and the conditions that would reopen it.
Anti-marketing, on purpose — the honesty discipline applies here too.
- You want a hosted, cloud, multi-provider agent. ARIRAMBA is local-first by design; that contradicts cloud infrastructure. A separate choice, not a gap.
- You need throughput benchmarks or a solve-rate leaderboard. None are published — quality over speed, and no metric is claimed until earned. See
docs/BENCHMARKS.md. - You want edits written immediately to your real tree. Evidence mode (copy-in / revert) is the default; the jail and staged loop never write your real project. Persisting is a separate, explicit, human-armed
--keep/--commit/--push— each behind a distinct security review. If you never want a keep option, this is not the tool. - You need GPT-OSS-120B today. Its weights are not on this host — BLOCKED-on-weights. The 20B is the default; the 120B paging strategy is roadmap.
- You want to bash/exec arbitrary commands, or work with untrusted repos. The open loop is read-tier, a guarded write tier, and a narrow, human-armed exec tier —
run_testsonly, armed by an operator's own--test-cmd, approved per-exec, confined by the hardenedariramba-codecontainer (S9-H) — on own-trusted repos only. A general-purpose bash/ shell tool (gated on the S7 jail + human approval) and untrusted-repo hardening does not ship — both are fenced with a documented reason, not silently omitted.
ARIRAMBA targets a single consumer workstation. Today, GPT-OSS-20B runs CPU-first (bf16-dequantized, tight-but-fitting on 64 GB) or GPU-resident (MXFP4, ~13 GB VRAM peak, fitting a 16 GB card). The unbuilt strategy is to keep the 20B as the resident agent and reach a paged, exact 120B oracle via a model router — the adaptive-compute plane, which is roadmap, not delivered. Full memo: docs/research/frontier-model-compaction.md.
ARIRAMBA is developed through Eidolons, an agent-driven, evidence-led process — every change is routed through the same discipline the harness enforces on itself.
- Docker-first, host-clean. Every
maketarget wrapsdocker/docker compose; nothing touches the host beyond.ariramba/runs/. No hostpip, no host virtualenv. - Evidence-label every claim. New capability assertions carry one of the five labels. Unlabeled claims are overclaims — see
docs/EVIDENCE.md. - Maker ≠ Checker. Every delivered slice is built by one identity and re-verified by a distinct one, recorded in an ADR under
docs/adr/. - Issues and PRs welcome — open an issue to discuss, or a PR with a fix.
Working with Eidolons (optional). ariramba is built through Eidolons; the committed eidolons.yaml + eidolons.lock pin the exact agent roster. To work the same way, follow Eidolons' getting started in your clone — it wires the cortex files (.eidolons/, CLAUDE.md, AGENTS.md, EIDOLONS.md) which stay gitignored by design. This is entirely optional — plain issues/PRs are equally welcome — and the resulting change records land in .spectra/.
colibrì. ARIRAMBA is independent, inspired by colibrì's expert-paged systems engineering — a from-scratch mixture-of-experts inference engine that streams experts through a VRAM → RAM → disk hierarchy. ARIRAMBA adapts those ideas (tiered expert store, quality-and-semantics preservation, an always-available exact oracle) into its own adaptive-compute plane. It targets GPT-OSS, is a clean-room reimplementation, and claims no affiliation with, endorsement by, or sponsorship from colibrì or its authors. No colibrì code is vendored; any future adapted code will carry explicit sign-off in licenses/THIRD_PARTY.md.
GPT-OSS / OpenAI. Real inference runs through the official open-weight GPT-OSS model via a trusted transformers reference/oracle backend — never through ARIRAMBA's own forward-pass code, which stays deferred and clean-room. Weights are Apache-2.0, distributed by OpenAI, host-mounted read-only via ARIRAMBA_MODEL_DIR, and never redistributed or committed. Model card: OpenAI GPT-OSS (arXiv:2508.10925).
Third-party dependencies are installed in-container only — the base MOCK image stays lean; oracle and web runtimes are optional extras. licenses/THIRD_PARTY.md is the authoritative record.
| Dependency | License | Role |
|---|---|---|
openai-harmony |
Apache-2.0 | o200k_harmony + Harmony format oracle |
regex |
Apache-2.0 | clean-room pretokenizer unicode patterns |
jsonschema · pytest |
MIT-family | schema validation · test runner |
transformers |
Apache-2.0 | GPT-OSS-20B CPU/GPU oracle |
torch (CPU + cu128) |
BSD-3-Clause | tensor / compute backend |
safetensors · accelerate |
Apache-2.0 | MXFP4 shard reads · low-memory loading |
triton · gpt-oss-triton-kernels |
MIT / Apache-2.0 | JIT MXFP4 MoE kernel |
starlette · uvicorn ([web]) |
BSD-3-Clause | ASGI routing · server |
@hotwired/turbo (vendored, [web]) |
MIT | browser stream/frame navigation |
ARIRAMBA is MIT-licensed. See LICENSE — Copyright © 2026 Henrique Aparecido Lavezzo. The MIT license grants the right to use, modify, and distribute this software, provided the original license and copyright notice are included. Third-party dependencies carry their own licenses, recorded in licenses/THIRD_PARTY.md.