This is the complete specification of llm-runtime-dock, and the source of truth
for what the project does and why. It describes the system as built.
Looking for how to use the tool — install it, write a config, point a coding agent at it? That is the README at the repository root. These documents are the design: the invariants, the contracts, and the reasoning behind the decisions that are easy to get wrong.
| # | document | what it covers |
|---|---|---|
| 1 | Overview | purpose, design principles, terminology, the security model, and what is deliberately out of scope |
| 2 | Architecture | workspace layout, dependency direction, plugin registration, developer workflow |
| 3 | Lifecycle and scheduling | the resident slot, the state machine, switching, draining, readiness, identity verification, observability |
| 4 | Runtime adapters | the adapter contract, then MTPLX, LM Studio, oMLX, Ollama and the declarative custom adapter |
| 5 | Configuration | file resolution, entry shape, reserved arguments, upstream auth, model resolution |
| 6 | Gateway API | the HTTP surface, both protocols, /status and /switch |
| 7 | Runtime discovery | lrd probe, and writing configuration from what backends report |
| 8 | Coding agent integrations | lrd apply and the per-agent configuration formats |
| 9 | Error model | the two error namespaces and every failure they cover |
| 10 | Command-line interface | every lrd command |
| 11 | Testing | the fake-runtime fixture, required scenarios, acceptance criteria |
The three documents that carry the invariants everything else depends on are
Overview, Lifecycle and scheduling and
Runtime adapters. If you read nothing else, read the resident
slot in §8: one model in memory at a time, across
every adapter, is the constraint the rest of the design exists to serve — and
keep_resident is the single, explicit way a configuration steps outside it.
These documents cross-reference each other by section number — §8, §17, §22
— because the numbering is stable and terse enough to use mid-sentence. Every
such reference is a link. The mapping:
| § | document | § | document |
|---|---|---|---|
| 1–3 | Overview | 18–20 | Runtime adapters |
| 4–6 | Architecture | 21 | Architecture |
| 7 | Runtime adapters | 22 | Runtime discovery |
| 8–10 | Lifecycle | 23 | Agent integrations |
| 11 | Runtime adapters | 24 | Lifecycle |
| 12–13 | Configuration | 25 | Error model |
| 14–15 | Gateway API | 26 | Lifecycle |
| 16–17 | Lifecycle | 27 | CLI |
| 28 | Overview | 32 | Architecture |
| 29 | Lifecycle | 33 | Agent integrations |
| 30 | Overview | 34 | Testing |
| 31 | Testing | 35–36 | Overview |
| 37 | Runtime adapters |