Devcontainer Dev

Containerized Dev Environment

An isolated, cross-platform test environment for ToolHive Studio. The whole Electron app — including its backend thv binary and the MCP-server containers it spawns — runs inside a single devcontainer. You interact with the UI via a noVNC browser tab.

The entire stack (Node, Electron, display server, window manager, VNC server, Docker-in-Docker, DBus, keyring) lives in the container. Nothing is installed on the host. That's the whole point: every worktree can have its own container and its own experiments, with zero risk of contaminating the user's global installs.

Entry point

pnpm devContainer:dev

runs scripts/devcontainer-dev.sh on the host. The script is "smart":

• If executed on the host: runs devcontainer up to build/start the container, then devcontainer exec to run the entrypoint inside it.
• If executed inside a container (detected via /.dockerenv): skips the build step and just runs the entrypoint directly. This path is used by GitHub Codespaces.

The three scripts

What the container runs

• Node 24 (matches .nvmrc)
• Electron + runtime deps — GTK, NSS, X11, etc. (see .devcontainer/Dockerfile)
• Display stack — Xvfb (virtual framebuffer at 1920×1200), fluxbox (window manager, auto-fullscreens windows with WM_CLASS=ToolHive), x11vnc (VNC server), noVNC + websockify (browser client on port 6080)
• Secret provider stack — dbus + gnome-keyring. Required by ToolHive's secret API; without them the backend returns 500 on secrets endpoints. Mirrors the setup in .github/workflows/_e2e.yml.
• Docker-in-Docker via the docker-in-docker:2 devcontainer feature. Supplies /var/run/docker.sock inside the container so the bundled thv CLI can spawn MCP-server containers.

Finding the URL (the logs are very long)

pnpm start + electron-forge + Vite + Electron + HMR produce a lot of output. The terminal scrollback often exhausts. Three recovery mechanisms are built in:

1. Written to a file by the launcher: ~/.cache/toolhive-studio-url. Survives any amount of output.

   cat ~/.cache/toolhive-studio-url

2. Set as the terminal tab title via OSC escape. Visible in the tab bar of most terminals regardless of scrollback state.
3. Prominent banners in the output — a green initial block right after devcontainer up, plus an inverse-video ✓ ToolHive ready — <URL> banner that fires only once the app is actually usable.

If you're piping the output:

pnpm devContainer:dev 2>&1 | tee /tmp/dev.log
# later:
grep -E 'ToolHive ready|vnc\.html' /tmp/dev.log

The readiness banner is what you care about. It gates on three signals simultaneously:

• noVNC's HTTP endpoint answers (the browser tab will actually load)
• The Electron binary is running (matched via pgrep -f 'electron/dist/electron')
• thv serve is running (matched via pgrep -f 'thv serve' — not pgrep -x thv, because the short-lived version-check invocation also matches on bare name)

Only once all three are true does the banner fire and the host's browser auto-open.

Per-worktree isolation

Each git worktree gets its own independent devcontainer:

• Container identity — labelled with devcontainer.local_folder=<absolute-worktree-path>. The devcontainer CLI uses this to decide which container to reuse vs create fresh.
• Node modules — volume named toolhive-node-modules-<basename>, scoped to the worktree's basename. No cross-worktree install pollution.
• Host port — the primary clone uses :6080; additional worktrees try :6080 first and fall back to a Docker-assigned random port if it's taken. So multiple worktrees can run simultaneously. The actual bound port is queried with docker port "$CONTAINER_ID" 6080/tcp and the URL is generated from that.
• DinD, display state, keyring, etc. — all container-local. Tearing down a worktree's container removes all of it.

The host is never touched — no host-side pnpm install, no host-side /tmp/.X11-unix mount, no host-side Docker socket passthrough, no host GPU. Everything the app needs is inside the container. Even the NVIDIA driver on the host is unreachable from inside — the container uses CPU software rendering.

Interacting with a running container

Find the container ID for a given worktree:

WORKDIR="$(pwd)"   # or a specific worktree path
CONTAINER=$(docker ps --filter "label=devcontainer.local_folder=$WORKDIR" --format '{{.ID}}' | head -1)

Common operations:

# Shell in
docker exec -it "$CONTAINER" bash

# Run as the devcontainer user (usually correct for pnpm / thv commands)
docker exec -u node "$CONTAINER" pnpm test

# One-off inspection
docker exec "$CONTAINER" ps auxf

# DinD health
docker exec "$CONTAINER" docker info
docker exec "$CONTAINER" docker ps

Log files (written by the entrypoint)

Killing stale state

If the app gets wedged, the entrypoint's first action on every run is to pkill all the usual suspects. To do it manually:

docker exec "$CONTAINER" bash -c '
  pkill -f "electron/dist/electron"; pkill -f "thv serve"
  pkill -f Xvfb; pkill -f fluxbox; pkill -f x11vnc; pkill -f websockify
  rm -f /tmp/.X99-lock /tmp/.X11-unix/X99
'

Driving the app as an agent

The container has enough tools for an AI agent to both see and interact with the running Electron window without going through the browser / noVNC. Useful for headless testing, reproducing user-reported UI bugs, or validating a feature end-to-end.

All commands run via docker exec against the container with DISPLAY=:99 set (matches Xvfb's display).

See the screen (screenshots)

# Take a PNG of the whole virtual framebuffer
docker exec "$CONTAINER" bash -c 'DISPLAY=:99 import -window root /tmp/shot.png'
# Copy it to the host for viewing / feeding to a vision model
docker cp "$CONTAINER:/tmp/shot.png" /tmp/shot.png

import is from ImageMagick. For a specific window only, use xwininfo to get the WID then import -window <WID>.

See the window tree (what's there, where, which is focused)

docker exec "$CONTAINER" bash -c 'DISPLAY=:99 xwininfo -root -tree'
docker exec "$CONTAINER" bash -c 'DISPLAY=:99 xdotool getactivewindow getwindowname'
docker exec "$CONTAINER" bash -c 'DISPLAY=:99 xdotool search --name ToolHive'

The main app window has WM_CLASS=ToolHive (see gotcha below). Its geometry is usually 1920x1200+0+0 once fluxbox has auto-fullscreened it.

Interact with the UI (mouse, keyboard)

# Move the mouse and click
docker exec "$CONTAINER" bash -c 'DISPLAY=:99 xdotool mousemove 400 300 click 1'

# Type into whatever has focus
docker exec "$CONTAINER" bash -c "DISPLAY=:99 xdotool type --delay 20 'hello world'"

# Send a keystroke
docker exec "$CONTAINER" bash -c 'DISPLAY=:99 xdotool key ctrl+shift+i'   # DevTools

# Focus the main window by name
docker exec "$CONTAINER" bash -c 'DISPLAY=:99 xdotool search --name ToolHive windowactivate'

Typical agent loop

Screenshot → feed to vision model → decide next action → xdotool → screenshot again. The usual caveats apply: pixel-coordinate automation is fragile, and CSS changes or modal dialogs can throw it off. For robust long-term automation, prefer a DOM-level approach (e.g. Chrome DevTools Protocol against Electron's remote debugging port — not currently wired in, see Future: CDP access).