# jamestrichmond/otter-creek-homelab architecture

> Architecture diagram of the GitHub repository jamestrichmond/otter-creek-homelab, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jamestrichmond/otter-creek-homelab
- Repository: https://github.com/jamestrichmond/otter-creek-homelab

## Overview

Otter Creek Homelab is a self-hosted environment for local-model agents and disposable code execution. The principal workflow starts with a laptop task, runs a builder/review loop on the agent host, tests generated code in a sandbox VM, and returns results to the host; the host opens PRs for human review. Separate operations include a nightly runbook sweep and repository guardrails. All components and relationships below are based on the README; no implementation source was provided.

Main entry points: [`README.md`](https://github.com/jamestrichmond/otter-creek-homelab/blob/main/README.md) (Agent host)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_compute["Lab compute"]
  node_agent_host["Agent host<br/>[README.md]"]
  node_local_models["Local models<br/>[README.md]"]
  node_agent_gateway["Agent gateway<br/>[README.md]"]
  node_network["UniFi network<br/>[README.md]"]
  node_hypervisor["Proxmox hypervisor<br/>[README.md]"]
  node_sandbox["Sandbox VM<br/>[README.md]"]
  node_worker_timeout["Worker timeout<br/>[README.md]"]
end

subgraph group_relay["Relay loop"]
  node_builder["Builder model<br/>[README.md]"]
  node_code_tests["Generated code/tests<br/>[README.md]"]
  node_test_runner["Test execution<br/>[README.md]"]
  node_outcome_log["Round outcome log<br/>[README.md]"]
  node_reviewers["Reviewer models<br/>[README.md]"]
end

subgraph group_operations["Lab operations"]
  node_runbook["Living runbook<br/>[README.md]"]
  node_nightly_agent["Scheduled agent<br/>[README.md]"]
  node_repo_guardrails["Repository guardrails<br/>[README.md]"]
end

node_laptop(("Review laptop"))
node_github["GitHub"]

node_laptop -->|"sends tasks"| node_agent_host
node_agent_host -->|"serves models"| node_local_models
node_agent_host -->|"runs gateway"| node_agent_gateway
node_agent_host -->|"uses network"| node_network
node_hypervisor -->|"holds VM"| node_sandbox
node_agent_host -->|"runs relay loop"| node_builder
node_builder -->|"writes"| node_code_tests
node_agent_host -->|"copies code"| node_sandbox
node_sandbox -->|"runs tests"| node_test_runner
node_worker_timeout -->|"enforces timeout"| node_test_runner
node_sandbox -->|"returns results"| node_agent_host
node_agent_host -->|"classifies outcomes"| node_outcome_log
node_agent_host -->|"requests critiques"| node_reviewers
node_agent_host -->|"opens PRs"| node_github
node_github -->|"enforces rules"| node_repo_guardrails
node_nightly_agent -->|"sweeps nightly"| node_runbook

click node_agent_host "https://github.com/jamestrichmond/otter-creek-homelab/blob/main/README.md"
click node_local_models "https://github.com/jamestrichmond/otter-creek-homelab/blob/main/README.md"
click node_agent_gateway "https://github.com/jamestrichmond/otter-creek-homelab/blob/main/README.md"
click node_network "https://github.com/jamestrichmond/otter-creek-homelab/blob/main/README.md"
click node_hypervisor "https://github.com/jamestrichmond/otter-creek-homelab/blob/main/README.md"
click node_sandbox "https://github.com/jamestrichmond/otter-creek-homelab/blob/main/README.md"
click node_worker_timeout "https://github.com/jamestrichmond/otter-creek-homelab/blob/main/README.md"
click node_builder "https://github.com/jamestrichmond/otter-creek-homelab/blob/main/README.md"
click node_code_tests "https://github.com/jamestrichmond/otter-creek-homelab/blob/main/README.md"
click node_test_runner "https://github.com/jamestrichmond/otter-creek-homelab/blob/main/README.md"
click node_outcome_log "https://github.com/jamestrichmond/otter-creek-homelab/blob/main/README.md"
click node_reviewers "https://github.com/jamestrichmond/otter-creek-homelab/blob/main/README.md"
click node_runbook "https://github.com/jamestrichmond/otter-creek-homelab/blob/main/README.md"
click node_nightly_agent "https://github.com/jamestrichmond/otter-creek-homelab/blob/main/README.md"
click node_repo_guardrails "https://github.com/jamestrichmond/otter-creek-homelab/blob/main/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agent_host,node_local_models,node_agent_gateway,node_network,node_hypervisor,node_sandbox,node_worker_timeout,node_laptop toneBlue
class node_builder,node_code_tests,node_test_runner,node_outcome_log,node_reviewers toneAmber
class node_runbook,node_nightly_agent,node_repo_guardrails toneMint
class node_github toneIndigo
```

## Components

### Lab compute

- [Agent host](https://github.com/jamestrichmond/otter-creek-homelab/blob/main/README.md): `README.md`
- [Local models](https://github.com/jamestrichmond/otter-creek-homelab/blob/main/README.md): `README.md`
- [Agent gateway](https://github.com/jamestrichmond/otter-creek-homelab/blob/main/README.md): `README.md`
- [UniFi network](https://github.com/jamestrichmond/otter-creek-homelab/blob/main/README.md): `README.md`
- [Proxmox hypervisor](https://github.com/jamestrichmond/otter-creek-homelab/blob/main/README.md): `README.md`
- [Sandbox VM](https://github.com/jamestrichmond/otter-creek-homelab/blob/main/README.md): `README.md`
- [Worker timeout](https://github.com/jamestrichmond/otter-creek-homelab/blob/main/README.md): `README.md`

### Relay loop

- [Builder model](https://github.com/jamestrichmond/otter-creek-homelab/blob/main/README.md): `README.md`
- [Generated code/tests](https://github.com/jamestrichmond/otter-creek-homelab/blob/main/README.md): `README.md`
- [Test execution](https://github.com/jamestrichmond/otter-creek-homelab/blob/main/README.md): `README.md`
- [Round outcome log](https://github.com/jamestrichmond/otter-creek-homelab/blob/main/README.md): `README.md`
- [Reviewer models](https://github.com/jamestrichmond/otter-creek-homelab/blob/main/README.md): `README.md`

### Lab operations

- [Living runbook](https://github.com/jamestrichmond/otter-creek-homelab/blob/main/README.md): `README.md`
- [Scheduled agent](https://github.com/jamestrichmond/otter-creek-homelab/blob/main/README.md): `README.md`
- [Repository guardrails](https://github.com/jamestrichmond/otter-creek-homelab/blob/main/README.md): `README.md`

### Other components

- **Review laptop**
- **GitHub**

## Connections

- Review laptop → Agent host: sends tasks (evidence: `README.md`)
- Agent host → Local models: serves models (evidence: `README.md`)
- Agent host → Agent gateway: runs gateway (evidence: `README.md`)
- Agent host → UniFi network: uses network (evidence: `README.md`)
- Proxmox hypervisor → Sandbox VM: holds VM (evidence: `README.md`)
- Agent host → Builder model: runs relay loop (evidence: `README.md`)
- Builder model → Generated code/tests: writes (evidence: `README.md`)
- Agent host → Sandbox VM: copies code (evidence: `README.md`)
- Sandbox VM → Test execution: runs tests (evidence: `README.md`)
- Worker timeout → Test execution: enforces timeout (evidence: `README.md`)
- Sandbox VM → Agent host: returns results (evidence: `README.md`)
- Agent host → Round outcome log: classifies outcomes (evidence: `README.md`)
- Agent host → Reviewer models: requests critiques (evidence: `README.md`)
- Agent host → GitHub: opens PRs (evidence: `README.md`)
- GitHub → Repository guardrails: enforces rules (evidence: `README.md`)
- Scheduled agent → Living runbook: sweeps nightly (evidence: `README.md`)