Home > Wiki > Decisions > Q-01 Decisions — Pi 4 Runtime Shape

Q-01 Decisions — Pi 4 Runtime Shape

Status: DECIDED (pinned — revisit after Q-02) Agent: opencode/ext-agent (sandshrew) Timestamp UTC: 2026-05-12T02:00:00Z Session: Consolidated decisions on host-level approach, shared arsenal, Docker conventions

Decided

1. Game Backend Runs on Host, Not Docker

Sources game-surface-venv at /home/mehdifarah/game-surface-venv/
LangGraph + FastAPI + uvicorn already installed (75MB, zero new disk)
Persisted via systemd service or tmux session (decision pending)
No new Docker image for the game backend

2. Shared Arsenal at Host Level

/opt/pearl/
  ├── venv/           ← Python venv (langgraph, fastapi, uvicorn, requests)
  ├── bin/            ← Bun, Node symlinks (single source of truth for runtimes)
  └── config/         ← secrets, env files, game-surface configs (bind-mounted, never baked)

Rule: Dependencies installed once at arsenal level. Containers mount it or processes source it. Never duplicate what the arsenal provides.

3. What Stays in Docker

Container	Purpose	Why Docker
from-forgejo	Git forge	Complex Go binary, needs isolation
d3-tui-pi-teams-proto	LLM wiki depot + pi-teams	Existing, working, wiki lives here

4. What Runs on Host

Process	Runtime	Persistence
LangGraph game backend	game-surface-venv (Python)	systemd or tmux
FastAPI HTTP bridge	game-surface-venv (Python)	Same process as LangGraph
Bun/Pi agents (if chosen)	Bun on host	Installed once to /opt/pearl/bin/

Pending (Depends on Q-02)

Bun Installation

If Pi agents are chosen (Q-02): install Bun on host to /opt/pearl/bin/
If Hermes or OpenCode chosen: Bun may not be needed
Decision deferred until Q-02 resolves

Arsenal Location

/opt/pearl/ (standard, needs root) vs /home/mehdifarah/pearl/ (user-owned, no root)
Deferred until we know what needs root access (Bun install, systemd service)

Systemd vs Tmux

systemd: auto-restart on boot, standard Linux service management
tmux: simpler, visible, matches d3-tui's existing tmux pattern
Deferred until we know the startup sequence

Docker Image Conventions (Moving Forward)

No image duplicates arsenal dependencies. If Python/Bun/Node are in /opt/pearl/, no Docker image contains its own copy.
Images are slim. They carry only what the platform doesn't provide. Application code, not runtimes.
Bind mounts over baking. Configs, secrets, wiki files, repos — mounted from host, not baked into images.
Prune regularly. Existing ~2.5GB in dangling images will be cleaned. docker image prune -a before next build cycle.
One image, one purpose. d3-tui for pi-teams. Forgejo for git. No multi-purpose monoliths.

Bind Mount Convention

Container mounts:
  /opt/pearl/venv     →  shared Python (if container needs Python)
  /opt/pearl/bin      →  shared runtimes (if container needs Bun/Node)
  /opt/pearl/config   →  secrets, API keys (read-only)
  /home/mehdifarah/git →  Forgejo repos (forgejo container)
  /workcell/llm-wiki   →  LLM wiki files (d3-tui container — read/write)

Archiving Protocol (Before Cleanup)

# 1. Wiki depot (critical)
docker cp d3-tui-pi-teams-proto:/workcell/llm-wiki /home/mehdifarah/archive/llm-wiki-$(date +%Y%m%d)

# 2. Agent configs
docker cp d3-tui-pi-teams-proto:/home/agent/.pi /home/mehdifarah/archive/pi-agent-config-$(date +%Y%m%d)

# 3. Prune
docker image prune -a

Revisit After Q-02

Once the agent harness decision is made, revisit: - Bun install path (host or skip) - Arsenal location (root or user) - Systemd vs tmux - Final container shape (which containers, what they mount, what's on host)