Feat/vm deploy topology spike

[clintberry]

Validates the container topology for self-hosted deployment, and fixes three defects the validation turned up.

Deuce had no deployment story and the published image couldn't run its core feature: the runtime stage was distroless/static, holding exactly one file, while the server shells out to devpod, docker, and git. It booted, migrated, served the SPA, then failed on the first session create.

Origin: docs/brainstorms/2026-07-30-vm-deploy-and-upgrade-requirements.md · Plan: docs/plans/2026-07-31-001-feat-vm-deploy-topology-spike-plan.md

The decision

Adopt the socket-mounted container with path parity: an unprivileged Deuce container driving the host Docker daemon, with state bound at an identical absolute path on both sides and HOME pointing at it. Workspace containers are siblings rather than children.

This shape needed validating rather than assuming because its failure mode is silent. Deuce reads workspace files off its own filesystem and finds containers via a label in DevPod's on-disk records — both resolve through $HOME. If Deuce and the daemon disagree about what a path string means, DevPod still succeeds and the container still starts, but the bind mount resolves to an empty host directory: the team sees an empty file tree while the agent works normally somewhere nobody is looking.

Verified on an Ubuntu 24.04 VM (Docker 29.1.3):

• Workspace container bind-mounted the exact host path Deuce reads from
• Writes made inside the workspace container appeared in Deuce's listing immediately, with correct git status
• Upgrades left workspaces running untouched — the same container sat at Up 24 minutes across four image rolls
• Stopping a workspace produced stopped, not missing; restart returned ready with content preserved and no re-clone
• SSH proxy authenticated a registered key and landed as the devcontainer's remoteUser, not root

The alternatives each cost something concrete: a nested-daemon container stops every workspace on every upgrade and needs privileged: true; host-native under systemd gives up containerized packaging and needs a raw binary the release pipeline doesn't publish.

Decision recorded in docs/solutions/architecture-patterns/deploy-deuce-as-a-container-sharing-the-host-daemon.md, which leads with the two degradation symptoms rather than the architecture — that's what someone will actually need later.

Fixes

d34d8ad — git status was silently broken in any containerized deployment. DevPod clones as the devcontainer's remoteUser (uid 1000) while the server runs as 65532, and git refuses across that mismatch. It fails quietly: walking a directory needs no ownership match, so the tree still rendered and only the per-file status vanished. Never visible in the devcontainer, where Deuce happens to run as uid 1000.

9794980 — closes an escalation path the above opened. Git executes core.fsmonitor as a command and honors it from a repository's own .git/config. Workspace repos are writable by the agent and anyone with terminal access, so suppressing the ownership check meant a planted value would run in the server process — which on this topology reaches the host Docker daemon. Pinned off at the call site, where the command line takes precedence over repository config.

2b9e444 — client exec commands ran under dash, breaking real clients. Reported from a live client as /bin/sh: 29: Syntax error: "(" unexpected, connection dropped before anything ran. Clients write commands for a login shell because that's what a real sshd gives them, and VS Code Remote-SSH's bootstrap plus the shell-integration payloads terminals inject are multi-line bash scripts. This was on track to break Open-in-VS-Code, the reason the proxy exists.

Testing

• New server/internal/handler/files_test.go plants a malicious core.fsmonitor the way an attacker would and asserts it never runs. Confirmed it fails when the override is removed, rather than passing regardless.
• New TestDockerArgs_ExecUsesBashNotDash guards the dash regression by name.
• Full Go suite, ESLint, and tsc -b all pass.
• Every claim above was verified against the live deployment, not inferred.

Known residuals

Three findings surfaced by the spike that are not fixed here. All are recorded as requirements in the origin brainstorm for the follow-up deploy work.

1. The devcontainer prebuild cache is non-functional against DevPod v0.6.15. devpod build --repository R --skip-push reports success and exits zero, but tags the image :latest with no parseable hash and leaves no image on the daemon. Every session silently falls back to a from-scratch build with an over-SSH tooling install, logging one WARN. Reproduced with and without a devcontainer.json. This inverts the brainstorm's original requirement: the cache-key staleness bug it identified is unreachable, because a cache that never populates cannot go stale.
2. A fresh deployment has no user row and no team membership. Reads return FORBIDDEN, session listing returns empty despite seeded data, new sessions get members: [], and the SSH proxy then rejects every key because it authorizes on session membership. The spike inserted a user and membership by hand to proceed.
3. Configuration cannot express "off". The loader falls back to a field's built-in default when a variable is set-but-empty, so DEUCE_SSH_LISTEN_ADDR= does not disable the SSH proxy — verified across unset, empty, and explicit values. The SSH deployment checklist instructs operators to disable it exactly that way. DEUCE_WS_ALLOWED_ORIGINS= silently becomes the localhost dev default, the same trap on a security-relevant setting.

Also unreviewed: this branch did not go through the persona code-review pass, which is worth running given it touches security-relevant configuration.

Post-Deploy Monitoring & Validation

deploy/ is explicitly marked a spike candidate and is not a supported deployment yet — it ships with dev auth mode and loopback binds, and the follow-up plan hardens it before anyone is pointed at it. The image change, however, affects anyone pulling a released tag.

Watch after any deploy from this image:

• Startup: migrations applied followed by server starting. A container that exits non-zero before binding means migrations failed — expected behavior, not a regression.
• Workspace health: docker provider added successfully at boot. Absence means the devpod binary isn't resolving, which would have been a hard failure on the old image.
• The signal that matters most: create a session and confirm the files tab shows both real content and per-file git status. Content without status means the safe.directory declaration was lost; an empty tree means path parity is broken. Neither logs an error — this has to be checked by looking.
• Failure signal / rollback trigger: any session reporting missing where its workspace should have survived, or prebuild failed; falling back appearing for a deployment that expects the cache to work.
• Rollback: change DEUCE_IMAGE_TAG back and restart. Workspace containers are siblings and keep running through it.
• Window/owner: first session create after deploy, by whoever deploys.

🤖 Generated with Claude Code

[gitguardian]

⚠️ GitGuardian has uncovered 2 secrets following the scan of your pull request.

Please consider investigating the findings and remediating the incidents. Failure to do so may lead to compromising the associated services or software components.

🔎 Detected hardcoded secrets in your pull request

GitGuardian id	GitGuardian status	Secret	Commit	Filename
35683146	Triggered	Generic Password	8b05242	deploy/docker-compose.yml	View secret
35683146	Triggered	Generic Password	8b05242	deploy/docker-compose.yml	View secret

🛠 Guidelines to remediate hardcoded secrets

1. Understand the implications of revoking this secret by investigating where it is used in your code.
2. Replace and store your secrets safely. Learn here the best practices.
3. Revoke and rotate these secrets.
4. If possible, rewrite git history. Rewriting git history is not a trivial act. You might completely break other contributing developers' workflow and you risk accidentally deleting legitimate data.

To avoid such incidents in the future consider

• following these best practices for managing and storing secrets including API keys and other credentials
• install secret detection on pre-commit to catch secret before it leaves your machine and ease remediation.

---

^{🦉 GitGuardian detects secrets in your source code to help developers and security teams secure the modern development process. You are seeing this because you or someone else with access to this repository has authorized GitGuardian to scan your pull request.}