# Agentic coding workstation — runbook

Purpose: the template you fill in for your own workstation, so that a machine rebuilt in
six months comes back the same and so that somebody else, including you, can tell what was
decided and why.
Platform: all (spark, strix, mac, nvidia).
Minimum memory: 16 GB for the agent role.
Assumes: created by `setup-workstation.sh` and verified by `check-workstation.sh`. Replace
every angle-bracketed placeholder and every empty table cell. A cell left empty is a
decision nobody made.

---

## 1. The machine

| Field | Value |
| --- | --- |
| Track | S / X / M / N |
| Chip and memory | |
| Operating system and version | |
| Accelerator memory available to engines | |
| Date this runbook was last verified | |

## 2. Models per role

Three roles, three aliases, three deliberate choices. The agent role drives the loop, the
completion role fires as you type, and the judge role scores agent output in the evaluation
suite. The judge must not be the same weights as the agent.

| Role | Alias | Model and quantisation | Context configured | Why this one |
| --- | --- | --- | --- | --- |
| Agent | `local/agent` | | | |
| Completion | `local/completion` | | | |
| Judge | `local/judge` | | | |

Tool-call reliability, measured with Part 24's reliability test against the agent alias at
the context length above:

| Model | Date measured | Pass rate | Notes |
| --- | --- | --- | --- |
| | | | |

## 3. The gateway

| Field | Value |
| --- | --- |
| Address (loopback only, or the Part 23 fronted address) | |
| Engine or engines behind the aliases | |
| Prompt-cache reuse enabled | yes / no |
| Where the role aliases are defined | |
| Usage records available per key | yes / no |

Virtual keys, one per agent so that usage is attributable:

| Agent | Key name or metadata label | Aliases it may use | Created | Revoked |
| --- | --- | --- | --- | --- |
| | | | | |

## 4. Agents configured

At least two, each tested against the agent alias on a real task.

| Agent | Version | Configuration file | Permission mode set | Last tested | Result |
| --- | --- | --- | --- | --- | --- |
| | | | | | |
| | | | | | |

Notes on anything that did not work as documented, with the date:

- 

## 5. MCP servers

Every server here is tool schemas in the prompt on every turn, and a capability the agent
can invoke. Keep the list short and justify each entry.

| Server | What it does | Which agents it is wired into | Why it earns its tokens |
| --- | --- | --- | --- |
| | | | |

## 6. The sandbox

| Field | Value |
| --- | --- |
| Route | container / dedicated user |
| Engine and version | |
| Image tag | |
| Mounts, exactly | |
| Network | internal / none / other |
| Environment variables passed in | |
| Runs as | |
| Read-only root filesystem | yes / no |
| Resource limits | |

Boundary test, most recent run:

| Check | Result | Date |
| --- | --- | --- |
| host-home-not-mounted | | |
| container-socket-absent | | |
| runs-as-non-root | | |
| root-filesystem-read-only | | |
| project-is-writable | | |
| planted-secret-unreadable | | |
| environment-is-clean | | |
| internet-unreachable | | |
| gateway-reachable | | |

## 7. Residual risk

What is still true that you have decided to accept, and why. Every real workstation has
entries here. A blank section means the risks were not examined rather than that there are
none.

| Accepted risk | Why it is acceptable here | What would change the decision |
| --- | --- | --- |
| | | |

## 8. Rebuilding this from nothing

1. Start the Part 9 gateway and confirm the three role aliases are published.
2. Run `setup-workstation.sh` from the directory holding the configuration templates.
3. Fill in `sandbox/.env` and generate one gateway key per agent.
4. Run `check-workstation.sh` and fix everything it reports.
5. Run `boundary-test.sh` inside the sandbox and store the sheet in `evidence/`.
6. Run one real task through two agents and record the result.
7. Update this runbook with anything that changed.

Expected wall-clock for a rebuild on a machine that already has the models: _____ minutes.

## 9. Change log

| Date | What changed | Who | Re-verified |
| --- | --- | --- | --- |
| | | | |