hack-house/docs/spec-sandbox-distros-gui.md

hack-house → Sandbox distro defaults, /sbx grammar, container GUI — Spec

Status: Implemented v1 · Date: 2026-06-07 Scope: (1) per-backend default distro images, (2) a uniform /sbx <type> <option> command grammar, (3) an opt-in noVNC desktop GUI for container sandboxes. Baseline: hh/src/sbx.rs, hh/src/app.rs, hh/scripts/sandbox-bootstrap.sh. Builds on: spec-collaborative-sandbox.md, spec-goose-harness.md.

---

0. Decisions locked (from product owner)

#	Decision	Choice
A	Podman default distro	Kali (kalilinux/kali-rolling). Debian/apt-based ⇒ the apt-only sandbox-bootstrap.sh works unchanged. Minimal base (no pentest metapackages by default — fast first launch).
B	Docker default distro	Parrot OS (parrotsec/core). Also Debian/apt-based. core = minimal base; parrotsec/security per-launch for the full toolset.
C	Multipass / Local	Unchanged: Multipass = Ubuntu 24.04; Local = host shell.
D	Grammar	/sbx <type> <option> across the board for clarity. vbox is the exception that takes extra options (/sbx vbox gui <vm>, /sbx vbox new [name]). launch kept as a transitional alias.
E	GUI	Opt-in, container-only. /sbx <docker|podman> gui provisions an XFCE desktop served over noVNC, published on host loopback only. Headless backends/local: gui is a flagged no-op.

Why apt-only distros for the defaults: sandbox-bootstrap.sh and sandbox-tools.json are apt-based. Kali and Parrot are both Debian derivatives, so they are drop-in. Non-apt distros (Arch/Fedora/Alpine) would each need a package-manager branch in the bootstrap and are therefore selectable images, not defaults.

---

1. Distro defaults

Backend::default_image() (hh/src/sbx.rs):

Backend	Default image	Notes
Docker	parrotsec/core	swap parrotsec/security per-launch for full tools
Podman	kalilinux/kali-rolling	minimal; add kali-linux-headless for the toolset
Multipass	24.04	Ubuntu cloud release
Local	""	host shell

Any image is overridable positionally: /sbx podman parrotsec/security, /sbx docker ubuntu:24.04, etc.

---

2. /sbx <type> <option> grammar

The leading token after /sbx selects the backend; the rest are options.

/sbx docker [gui] [image] [install] [--start]
/sbx podman [gui] [image] [install]
/sbx multipass [image] [install]
/sbx local
/sbx vbox [gui] <vm> [yes]     # exception: extra option (VM name / confirm)
/sbx vbox new [name]           # exception: build a fresh VM
/sbx launch <backend> …        # transitional alias (still accepted)

Action subcommands are unchanged and remain non-backend-led: /sbx stop | save | load | snaps | vms | vmsave | vmload | vmsnaps.

Implementation: the /sbx match arm accepts the backend tokens (docker|podman|multipass|local|vbox|virtualbox) and launch. For the backend-led form the matched token is pushed to the front of the positional args so the existing first = pos.next() backend-selection logic is reused verbatim. gui and install are keyword options filtered out of the positionals (so they are never mistaken for the image), exactly like the pre-existing install.

---

3. Container GUI (noVNC)

3.1 Why a special path

Containers are headless — unlike VirtualBox (spec-virtualbox-sandbox.md), there is no display to open. A GUI therefore means running a desktop + a remote framebuffer inside the container and exposing it to the owner's browser.

3.2 Flow

1. /sbx podman gui → want_gui keyword detected → gui = true (only for Docker/Podman; flagged no-op otherwise).
2. prepare() publishes the noVNC port on host loopback: -p 127.0.0.1:6080:6080 (GUI_PORT = 6080). Never 0.0.0.0 — reachable from this machine's browser, never the LAN.
3. dk_bootstrap() passes HH_SBX_GUI=1 into the in-container bootstrap.
4. sandbox-bootstrap.sh (when HH_SBX_GUI=1) apt-installs a lightweight stack — xfce4, xfce4-terminal, dbus-x11, tigervnc-standalone-server, novnc, websockify — sets a non-interactive VNC password, starts a VNC server on :1 (5901, -localhost no so the in-netns bridge can reach it), and daemonizes websockify --web=/usr/share/novnc 6080 localhost:5901.
5. The owner opens http://127.0.0.1:6080 (noVNC). Default password hackhouse (override HH_SBX_GUI_PASS).

3.3 Security posture

• Loopback-only publish. The desktop is never bound to a routable address.
• The VNC password is obfuscation, not strong auth; the real gates are the loopback bind + the room password + the container's network namespace.
• No host bind mounts — consistent with the Goose containment invariant (spec-goose-harness.md §2.1). The GUI adds one published loopback port, nothing else crosses the boundary.

3.4 Limitations / non-goals

• Heavy first pull (a full desktop) — strictly opt-in, never default.
• The desktop+VNC processes are started during provisioning. The bootstrap is sentinel-guarded, so after a container restart the GUI services are not auto-restarted (fresh launches are the supported demo path). A future phase could move service-start out from under the sentinel.
• Fixed port 6080 ⇒ one GUI sandbox at a time on a host (matches the one-sandbox-at-a-time model).

---

4. Touch points

File	Change
hh/src/sbx.rs	default_image() → Parrot (docker) / Kali (podman); GUI_PORT const; prepare(gui) publishes loopback -p; provision(gui)/dk_bootstrap(gui) thread HH_SBX_GUI.
hh/src/app.rs	/sbx match arm accepts backend-led tokens; gui/install keyword filtering; gui guarded to docker/podman; threaded through PendingSudoLaunch + spawn_launch; noVNC URL surfaced; help/usage strings → new grammar; "did you mean" suggestions (KNOWN_COMMANDS, SBX_SUBCOMMANDS, levenshtein/closest).
hh/src/ui.rs	help_clusters() VIRTUAL MACHINES → new grammar + podman/gui entries.
hh/scripts/sandbox-bootstrap.sh	HH_SBX_GUI=1 section: apt desktop+VNC+noVNC, start server + websockify bridge.
docs/command-reference.md	Canonical categorized command list (mirrors /help), grammar + GUI + "did you mean" reference.

---

5. Command reference

The full categorized command list (the /help popup, the /sbx <type> <option> grammar, the container gui option, and the "did you mean" typo-suggestion behaviour) lives in docs/command-reference.md. That file is the canonical text mirror of hh/src/ui.rs::help_clusters. GUI/grammar quick form:

/sbx docker [gui] [image] [install]      # Parrot OS default; gui = noVNC desktop
/sbx podman [gui] [image] [install]      # Kali default;      gui = noVNC desktop

gui is honoured for Docker/Podman only (flagged no-op on headless/local); noVNC is published on host loopback 127.0.0.1:6080 (open http://127.0.0.1:6080, default password hackhouse).