docs: design for Guix-container runtime in wraptool up #5

Merged

pti merged 1 commit from design-guix-container-runtime into main

2026-07-07 12:40:30 +02:00

pti commented

2026-07-07 12:17:52 +02:00

Owner

Design doc for a Guix-native wraptool up backend (design/guix-container-runtime.md). No code yet — proposal, spike-verified.

Summary

Second container backend using guix shell --container instead of the devcontainer CLI. Guix-first, devcontainer fallback (auto = guix when guix on PATH + manifest.scm present). No Docker daemon, no image build; the harness container is realized from a container.scm (node/bash/coreutils/nss-certs, no git — creds stay host-side).

Key decisions (grounded in the spike)

Internet is mandatory (npm/pip/cargo/… pull at dev time). guix shell --container network is binary — isolated netns (no internet) or -N (shares host netns). So v1 must use -N.
Under -N the harness reaches wraptool directly at 127.0.0.1:8717/sse — the unix-socket+socat trick buys nothing, so v1 = plain SSE on loopback. (socat/unix retained for the deferred pasta strict-net mode.)
Credential isolation holds regardless of net mode — it's a filesystem/env property (host $HOME/creds not mounted), not a network one. Weak net-iso under -N is a documented residual, not a compromise of the goal.

Runtime selection, bringUpGuixContainer, writeMCPConfig (host-side, twins connect.sh), inContainer marker (WRAPTOOL_CONTAINER), the harness container.scm, risks, effort, 4-phase plan, tests, and a verified spike appendix (isolated vs -N internet, host-loopback connect probe REFUSED/CONNECTED, unix-SSE handshake). Open gate: Node/Claude Code under Guix may need -F (FHS).

🤖 Generated with Claude Code

Design doc for a Guix-native `wraptool up` backend (`design/guix-container-runtime.md`). No code yet — proposal, spike-verified. ## Summary Second container backend using `guix shell --container` instead of the `devcontainer` CLI. **Guix-first, devcontainer fallback** (`auto` = guix when `guix` on PATH + `manifest.scm` present). No Docker daemon, no image build; the harness container is realized from a `container.scm` (node/bash/coreutils/nss-certs, **no git** — creds stay host-side). ## Key decisions (grounded in the spike) - **Internet is mandatory** (npm/pip/cargo/… pull at dev time). `guix shell --container` network is binary — isolated netns (no internet) or `-N` (shares host netns). So v1 **must** use `-N`. - Under `-N` the harness reaches wraptool directly at `127.0.0.1:8717/sse` — the unix-socket+socat trick buys nothing, so v1 = plain SSE on loopback. (socat/unix retained for the deferred pasta strict-net mode.) - **Credential isolation holds regardless of net mode** — it's a filesystem/env property (host `$HOME`/creds not mounted), not a network one. Weak net-iso under `-N` is a documented residual, not a compromise of the goal. ## Contents Runtime selection, `bringUpGuixContainer`, `writeMCPConfig` (host-side, twins `connect.sh`), `inContainer` marker (`WRAPTOOL_CONTAINER`), the harness `container.scm`, risks, effort, 4-phase plan, tests, and a **verified spike appendix** (isolated vs `-N` internet, host-loopback connect probe REFUSED/CONNECTED, unix-SSE handshake). Open gate: Node/Claude Code under Guix may need `-F` (FHS). 🤖 Generated with [Claude Code](https://claude.com/claude-code)

pti added 1 commit

2026-07-07 12:17:53 +02:00

docs: design for Guix-container runtime in wraptool up

Lint / lint (pull_request) Failing after 24s

Details

Lint / lint (push) Successful in 44s

Details

103d9374e2

Add design/guix-container-runtime.md: a second `wraptool up` backend using
`guix shell --container` (Guix-first, devcontainer fallback). Spike-verified —
unix-transport SSE over a shared socket works in an isolated container, but the
mandatory-internet requirement forces `-N` (shared host netns), so v1 uses SSE
on loopback; credential (fs/env) isolation holds regardless of net mode. Covers
runtime selection, bring-up, the harness container.scm, writeMCPConfig, the
inContainer marker, risks, effort, a phased plan, and a deferred pasta-based
strict-net mode. Includes the verified spike commands/outputs.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

pti merged commit b905b574dd into main

2026-07-07 12:40:30 +02:00

pti referenced this pull request from a commit

2026-07-07 12:40:32 +02:00

Merge pull request 'docs: design for Guix-container runtime in wraptool up' (#5) from design-guix-container-runtime into main

pti referenced this pull request

2026-07-07 12:49:33 +02:00

feat(up): Guix-native container runtime (phase 1) #6