boxdown 1.0.0 → 1.2.0

package/docs/features/README.md

@@ -4,10 +4,12 @@ This directory explains Boxdown's user-facing capabilities and the main internal
 flows behind them.
 
 - [Start command](./start-and-shell.md)
+- [Setup command](./setup.md)
 - [Lifecycle commands](./lifecycle.md)
 - [SSH config and proxy workflow](./ssh-config-and-proxy.md)
 - [GitHub auth refresh](./github-auth-refresh.md)
 - [Generated config and state](./generated-config-and-state.md)
+- [Commit signing](./commit-signing.md)
 
 Most features share the same first step: resolve a target workspace, derive
 workspace-specific state paths, generate a devcontainer override config, and

package/docs/features/commit-signing.md

@@ -0,0 +1,23 @@
+# Commit signing
+
+New Boxdown environments attempt SSH commit signing by default. Boxdown forwards
+the host SSH agent, selects a signing identity only when there is one
+unambiguous candidate, and keeps the private key on the host.
+
+If the agent is unavailable, has no identities, or has multiple identities
+that Boxdown cannot distinguish, Boxdown warns and configures unsigned commits.
+It never guesses a key and does not block setup or commits.
+
+The container can request operations from identities exposed by the forwarded
+agent. Use a dedicated signing identity or an agent that confirms sensitive
+operations when that exposure is unacceptable.
+
+GitHub verification is separate from signing. Upload the selected public key as
+a GitHub SSH signing key once to receive the Verified badge:
+
+```bash
+gh ssh-key add /path/to/signing-key.pub --type signing --title "Boxdown commit signing"
+```
+
+The same key may already be registered for GitHub SSH authentication; GitHub
+requires a second registration with type `signing`.

package/docs/features/generated-config-and-state.md

@@ -35,6 +35,21 @@ Boxdown-specific override is not set.
 SSH private keys live in persistent data. A public-key-only runtime directory is
 used for the container mount.
 
+Boxdown-managed lifecycle command output is appended to one per-workspace log
+file:
+
+```text
+~/.local/share/boxdown/workspaces/<workspace-hash>/boxdown.log
+```
+
+The log is append-only across lifecycle runs. Each run starts a timestamped
+section and records Boxdown-managed command output, Docker/devcontainer child
+process output, and command exit codes. Full interactive shell, agent, and
+tunnel session bytes are not tee'd into the log.
+
+The log lives with the workspace's persistent data so `boxdown status` can show
+its path and `boxdown purge` removes it with the rest of the workspace data.
+
 Each touched workspace also records inventory metadata at:
 
 ```text
@@ -44,16 +59,53 @@ Each touched workspace also records inventory metadata at:
 `boxdown list` reads these metadata files as its source of truth, then enriches
 entries with best-effort Docker state.
 
+Metadata may also record the last inspected Docker image ID for the workspace so
+`boxdown purge` can remove that exact image even after the container is gone.
+
+## External App Config
+
+External app integration config is not Boxdown workspace state. Boxdown writes
+it only when an SSH install target is selected from an interactive
+`boxdown setup` or `boxdown ssh install` prompt, or requested explicitly with
+`boxdown setup --target <name>` or `boxdown ssh install --target <name>`.
+Non-interactive runs without `--target` install only the SSH alias and leave
+external app config unchanged.
+
+When requested, Boxdown writes Codex's app config at:
+
+```text
+~/.codex/codex-app/config.json
+```
+
+`BOXDOWN_CODEX_APP_CONFIG` overrides this path for tests and local development.
+The Codex entry refers to the Boxdown-managed SSH alias and the canonical
+container-side workspace path `/workspaces/<repo-name>`. Codex owns later
+global-state records and sidebar entries it creates from that config, but
+`boxdown ssh uninstall` removes the matching Codex sidebar cache entry when
+unregistering the project.
+
+When requested, Boxdown writes Claude's SSH remote config at:
+
+```text
+~/Library/Application Support/Claude/ssh_configs.json
+```
+
+`BOXDOWN_CLAUDE_SSH_CONFIGS` overrides this path for tests and local
+development. The Claude entry refers to the Boxdown-managed SSH alias and adds
+that alias to Claude's trusted host list.
+
 ## Generated Changes
 
 Boxdown starts from `assets/devcontainer/devcontainer.json` and rewrites:
 
 - `name`, to include the workspace basename.
-- `initializeCommand`, to call the host asset script with the target workspace.
+- `initializeCommand`, to call the host asset script with the target workspace
+  and host Git config snapshot paths.
 - `postCreateCommand`, to call mounted container assets.
 - `postStartCommand`, to call mounted container assets.
-- `mounts`, to add the read-only asset mount, public-key mount, and host
-  `~/.agents` mount when that directory exists.
+- `mounts`, to add the read-only asset mount, public-key mount, host Git config
+  snapshot mount, host `~/.agents` mount when that directory exists, and host
+  `~/.codex/auth.json` read-only mount when that file exists.
 - `containerEnv`, to point SSH bootstrap at the mounted public key and actual
   container workspace.
 
@@ -61,4 +113,5 @@ The target repository is still the Dev Container workspace via
 `--workspace-folder`.
 
 Mounts are create-time container settings. Use `boxdown start --recreate` after
-creating or removing host `~/.agents` so Docker receives the updated mount set.
+creating or removing host `~/.agents` or `~/.codex/auth.json` so Docker
+receives the updated mount set.

package/docs/features/github-auth-refresh.md

@@ -5,6 +5,7 @@
 ```sh
 boxdown refresh-gh-token
 boxdown refresh-gh-token-running
+boxdown refresh-gh-token --verbose
 ```
 
 Both commands copy host GitHub CLI auth into the container using the host token
@@ -16,6 +17,9 @@ gh auth token
 
 They do not start a browser login or device-code flow.
 
+The startup and refresh work uses concise progress output by default. Pass
+`--verbose` to stream raw devcontainer and auth command output while debugging.
+
 These commands are explicit on purpose. Normal `boxdown start`, coding-agent
 launches, and SSH proxy connections do not copy GitHub credentials into the
 container.
@@ -48,6 +52,8 @@ container's authenticated `gh` for `git fetch`, `git pull`, and `git push`.
 For GitHub remotes, Boxdown:
 
 - rewrites fetch and push URLs to `https://github.com/<owner>/<repo>.git`
+- configures container-global GitHub HTTPS credentials through the container's
+  `gh` auth store
 - resets inherited `credential.https://github.com.helper` entries locally
 - adds `!gh auth git-credential` as the local GitHub credential helper
 - adds a repository-specific HTTPS self-rewrite so broader host rewrites like
@@ -57,6 +63,12 @@ For GitHub remotes, Boxdown:
 The local Git config changes are written to the workspace repository because the
 host checkout is mounted into the devcontainer.
 
+Separately, Boxdown snapshots the host `.gitconfig` into workspace state and
+copies it to a writable `/home/node/.gitconfig` during container creation. That
+container copy is sanitized so tools cloning from directories such as `/tmp` use
+HTTPS GitHub auth and do not inherit host-only helpers, GitHub SSH rewrites, or
+signing programs that are unavailable inside Linux.
+
 If host `gh` is missing, logged out, or cannot return a token, the refresh is a
 no-op.
 

package/docs/features/lifecycle.md

@@ -4,33 +4,48 @@
 
 ```sh
 boxdown list
+boxdown list --details
 boxdown list --json
+boxdown list --format json
 boxdown status
 boxdown status --json
+boxdown status --format json
 boxdown stop
 boxdown down
+boxdown purge
 boxdown doctor
 ```
 
-Workspace-targeting commands accept `--workspace <path>`. `status` also accepts
-`--alias <name>` so its output can match a custom SSH host alias.
+Workspace-targeting commands accept `--workspace <path>`. `down` also accepts
+repeated `--workspace` flags to remove multiple workspace containers in order.
+`purge --workspace` also accepts the `PATH`, `SSH ALIAS`, or unambiguous `REPO`
+value shown by `boxdown list`. `purge` does not accept repeated `--workspace`
+flags. `status` accepts `--alias <name>` so its output can match a custom SSH
+host alias.
 
 ## List
 
 `list` shows every workspace with Boxdown metadata under the data root,
 regardless of the directory where the command is run. Human output includes
-`STATE`, `REPO`, `PATH`, `SSH ALIAS`, and `CONTAINER` columns.
+`STATE`, `REPO`, `PATH`, and `CONTAINER` columns.
 
-`list --json` prints the same inventory as structured JSON. Docker state is
-best-effort: if Docker is unavailable, entries still print and their container
-state is `unknown`. If a recorded repository path no longer exists, the entry is
-shown as `missing`.
+`list --details` prints one workspace per block with full copyable `path`,
+`ssh alias`, and `container` values.
+
+`list --json` and `list --format json` print the same inventory as structured
+JSON. Docker state is best-effort and includes recorded SSH aliases: if Docker
+is unavailable, entries still print and their container state is `unknown`. If a
+recorded repository path no longer exists, the entry is shown as `missing`.
+Container states come from Docker, so active containers usually show `running`,
+stopped containers can show `exited`, and workspaces with no matching container
+show `absent`.
 
 ## Status
 
 `status` is read-only. It reports the resolved workspace, intended cache/data
-paths, generated config path, SSH key paths, SSH alias, and the matching Docker
-container state without recording the workspace in Boxdown metadata.
+paths, generated config path, command log path, SSH key paths, SSH alias, and
+the matching Docker container state without recording the workspace in Boxdown
+metadata.
 
 Human output distinguishes intended values from detected state. For example, an
 SSH alias can be shown as a computed default even when the matching Boxdown SSH
@@ -46,7 +61,7 @@ workspace container is running. Missing setup or a stopped/absent container is
 reported in the output and exits nonzero. Installing an SSH alias is optional
 and is not required for a healthy status exit.
 
-## Stop and Down
+## Stop, Down, and Purge
 
 `stop` stops the workspace devcontainer when it is running. If the container is
 already stopped or absent, it prints a short message and exits 0.
@@ -54,11 +69,82 @@ already stopped or absent, it prints a short message and exits 0.
 `down` removes the workspace devcontainer with Docker. It does not remove
 Boxdown cache, generated config, data directories, or SSH keys.
 
+Lifecycle commands append managed output to the workspace command log under the
+workspace data directory. `--verbose` only controls terminal streaming; it does
+not disable or enable log persistence. Foreground interactive shell, agent, and
+tunnel session bytes are not tee'd into the log.
+
+`purge` removes the workspace devcontainer with Docker, force-removes the exact
+Docker image ID Boxdown can inspect or has recorded for the workspace, removes
+Boxdown-managed SSH/Codex/Claude entries for the computed, recorded, and
+provided aliases, and deletes the workspace's Boxdown cache/data directories,
+including the per-workspace command log. It does not delete the target
+repository directory or files inside it.
+
+`purge --workspace <value>` first treats `<value>` as a filesystem path. If that
+path does not exist, it looks for an exact `PATH`, then `SSH ALIAS`, then `REPO`
+match in Boxdown metadata. `PATH` and `REPO` are shown by `boxdown list`; use
+`boxdown status`, `boxdown list --details`, or JSON list output for SSH aliases.
+`REPO` must match exactly one workspace; if multiple known workspaces share the
+same repo basename, use `PATH` or `SSH ALIAS`.
+
+```sh
+boxdown purge
+boxdown purge --workspace my-repo-devcontainer
+boxdown purge --workspace my-repo
+boxdown purge --workspace /path/to/my-repo
+```
+
+To remove multiple workspace containers, repeat `--workspace`:
+
+```sh
+boxdown down --workspace /path/to/repo-a --workspace /path/to/repo-b
+```
+
+When `down` runs without `--workspace` from a directory that is not a known
+Boxdown workspace, interactive terminals show a multi-select list of known
+workspaces with existing repository paths. Non-interactive runs keep the
+current-directory behavior.
+
+Batch `down` continues after individual workspace failures, but exits nonzero if
+any requested workspace cannot be resolved or removed.
+
+When `purge` runs without `--workspace` from a tracked Boxdown workspace, it
+purges that workspace after confirmation. When it runs without `--workspace`
+from an untracked directory, interactive terminals show a multi-select list of
+all tracked workspaces from `boxdown list`, including `running`, `exited`,
+`absent`, `missing`, and `unknown` states. After selection, `purge` asks for one
+destructive confirmation for the selected batch, then purges each selected
+workspace in order. Batch purge continues after individual workspace failures,
+but exits nonzero if any selected workspace fails.
+
+In the interactive purge selector, the focused row color-codes only the state
+token: `running` is green, `exited` is yellow, and `absent`, `missing`, or
+`unknown` are red. These colors are terminal UI affordances only; scripts should
+rely on text or JSON state values.
+
+Interactive `purge` runs ask for confirmation before removing devcontainer,
+image, SSH/Codex integration, cache, and data state. Non-interactive purge runs
+do not prompt so existing targeted scripts keep working. Non-interactive
+`purge` from an untracked directory fails safely instead of treating the current
+directory as a workspace.
+
 ## Doctor
 
 `doctor` validates required host prerequisites: Node, Docker CLI, Docker
 daemon access, SSH tools, packaged devcontainer assets, and Boxdown's packaged
-`@devcontainers/cli` dependency.
+`@devcontainers/cli` dependency. It also uses a local Docker image, when one is
+available, to create and immediately remove disposable containers that verify
+Docker can bind-mount the workspace, Boxdown assets, and Boxdown runtime-state
+paths. The probe never pulls an image or starts container code.
+
+Known bind-mount/share failures are errors with the affected host path and
+Docker Desktop remediation guidance. If Docker has no local image or the probe
+cannot complete for another reason, doctor reports a warning instead.
+
+`boxdown setup` runs the required doctor checks before it prompts, writes
+workspace metadata, creates SSH keys, generates devcontainer configuration, or
+starts Docker. Required failures stop setup; warnings remain non-blocking.
 
 GitHub CLI auth is optional. Missing or unauthenticated `gh` is reported as a
 warning rather than a failure.

package/docs/features/setup.md

@@ -0,0 +1,66 @@
+# Setup Command
+
+## Command
+
+```sh
+boxdown setup
+boxdown setup --target codex
+boxdown setup --target claude
+boxdown setup --recreate
+```
+
+`setup` prepares the current workspace for remote tools without opening an
+interactive shell. It accepts:
+
+```sh
+--workspace <path>
+--alias <name>
+--recreate
+--target <name>
+--verbose
+```
+
+## Flow
+
+1. Resolve the workspace to a real absolute path.
+2. Ensure per-workspace SSH key material exists.
+3. Generate a Boxdown-owned devcontainer config.
+4. Run `devcontainer up --workspace-folder <repo> --override-config <config>`.
+5. Install or update the Boxdown-managed SSH alias.
+6. Optionally install selected SSH targets such as Codex or Claude.
+
+`setup` prints plain progress sections by default. Docker, Dev Containers CLI,
+and lifecycle hook output is captured and only summarized if a command fails.
+Pass `--verbose` to stream the raw build and hook logs to the terminal.
+
+Boxdown also appends the managed setup output to the workspace command log at:
+
+```text
+~/.local/share/boxdown/workspaces/<workspace-hash>/boxdown.log
+```
+
+The log is written regardless of `--verbose`; the flag only changes terminal
+streaming.
+
+When `--target codex` is provided, Boxdown writes the Codex app config entry for
+the same alias and container-side project path used by:
+
+```sh
+boxdown ssh install --target codex
+```
+
+When `--target claude` is provided, Boxdown writes the Claude app SSH remote
+entry for the same alias used by:
+
+```sh
+boxdown ssh install --target claude
+```
+
+When no target is provided, Boxdown uses the same optional target prompt as
+`boxdown ssh install`. In non-interactive shells, setup skips target
+registration unless `--target` is provided.
+
+`setup` does not open a shell, launch a coding-agent CLI, or keep a tunnel in the
+foreground. Use `boxdown start`, `boxdown codex`, or `boxdown tunnel` for those
+foreground workflows. Those commands log Boxdown-managed startup steps, but do
+not tee full interactive shell, agent, or tunnel session bytes into the log.

package/docs/features/ssh-config-and-proxy.md

@@ -3,12 +3,20 @@
 ## Commands
 
 ```sh
-boxdown ssh-config install
+boxdown setup --target codex
+boxdown setup --target claude
+boxdown ssh install
+boxdown ssh install --target codex
+boxdown ssh install --target claude
+boxdown ssh uninstall
 boxdown ssh-proxy
+boxdown tunnel --port 3030
 ```
 
-`boxdown ssh-config` is accepted as a convenience shortcut for
-`boxdown ssh-config install`, but docs use the explicit install form.
+`boxdown ssh` is accepted as a convenience shortcut for
+`boxdown ssh install`, but docs use the explicit install form.
+`boxdown setup` is the higher-level workflow when you also want to start or
+recreate the devcontainer before installing the SSH alias.
 
 `ssh-proxy` is primarily an internal command launched by OpenSSH as a
 `ProxyCommand`.
@@ -31,11 +39,103 @@ The generated SSH config block includes:
 The block is wrapped in Boxdown markers so repeated installs replace the managed
 block instead of duplicating it.
 
+When `boxdown ssh install` runs without `--target` in an interactive terminal,
+Boxdown asks which optional install targets to update in addition to the SSH
+alias. The menu supports selecting multiple targets or skipping all optional
+targets. In non-interactive contexts, Boxdown skips optional targets instead of
+blocking and prints the explicit `--target` form for scripts.
+
+`boxdown ssh uninstall` removes the Boxdown-managed marker block for the
+selected alias, the matching Codex app remote project entry, and the matching
+Codex persisted sidebar state for the workspace. It leaves unrelated OpenSSH
+config entries, unrelated Codex remote projects, generated state, and SSH key
+files in place.
+
 `boxdown status` reports whether that Boxdown-managed block is `installed`,
 `missing`, or `outdated`. It only recognizes blocks wrapped in Boxdown's marker
 comments; an unrelated OpenSSH `Host` entry with the same alias is not treated
 as an installed Boxdown alias.
 
+## Codex App Target
+
+Selecting Codex from the interactive prompt or running
+`boxdown ssh install --target codex` keeps the normal SSH install flow and also
+writes a Codex app remote project entry for the same alias. `--target` is
+repeatable so future optional SSH install targets can be combined in one
+install command.
+
+The Codex app config is written to:
+
+```text
+~/.codex/codex-app/config.json
+```
+
+`BOXDOWN_CODEX_APP_CONFIG` overrides this path for tests and local development.
+
+The generated Codex entry points at the canonical container workspace path:
+
+```json
+{
+  "sshAlias": "<repo-name>-devcontainer",
+  "projects": [
+    {
+      "remotePath": "/workspaces/<repo-name>",
+      "label": "<repo-name>"
+    }
+  ]
+}
+```
+
+Boxdown merges by SSH alias and normalized remote path, so repeated installs
+update the existing Codex project instead of duplicating it. If an older
+Boxdown install registered `/home/node/<repo-name>`, the next Codex target
+install migrates that entry to `/workspaces/<repo-name>`. Existing known Codex
+config keys are preserved, but unknown keys are not written back because
+Codex's app config parser is strict.
+
+Boxdown normalizes matching Codex sidebar state for the same SSH alias when it
+installs the Codex target. Restart Codex after installing the target so Codex
+applies the app config, discovers the SSH alias from normal OpenSSH config, and
+creates or updates its sidebar project entry.
+
+## Claude App Target
+
+Selecting Claude from the interactive prompt or running
+`boxdown ssh install --target claude` keeps the normal SSH install flow and also
+writes a Claude app SSH remote entry for the same alias. `--target` is
+repeatable, so `codex` and `claude` can be installed in one command.
+
+The Claude SSH config is written to:
+
+```text
+~/Library/Application Support/Claude/ssh_configs.json
+```
+
+`BOXDOWN_CLAUDE_SSH_CONFIGS` overrides this path for tests and local
+development.
+
+The generated Claude entry mirrors the desktop app's SSH remote shape:
+
+```json
+{
+  "configs": [
+    {
+      "name": "<repo-name>",
+      "sshHost": "<repo-name>-devcontainer",
+      "id": "<uuid>",
+      "source": "desktop"
+    }
+  ],
+  "trustedHosts": [
+    "<repo-name>-devcontainer"
+  ]
+}
+```
+
+Boxdown merges by `sshHost`, preserves an existing Claude remote ID, and adds
+the alias to `trustedHosts`. Restart Claude after installing the target so the
+app applies the SSH remote entry.
+
 ## Proxy Flow
 
 When OpenSSH launches `boxdown ssh-proxy`, Boxdown:
@@ -44,15 +144,136 @@ When OpenSSH launches `boxdown ssh-proxy`, Boxdown:
 2. Ensures the per-workspace host key exists.
 3. Reuses a running devcontainer when possible.
 4. Starts the devcontainer when needed.
-5. Runs a throttled coding-agent CLI update preflight inside the container.
+5. Runs a throttled default coding-agent CLI update preflight inside the
+   container.
 6. Runs the container SSH bootstrap runtime.
 7. Bridges OpenSSH to `/usr/sbin/sshd -i` through `docker exec -i`.
 
 This does not publish an SSH port. The SSH stream travels through Docker exec.
 
-The coding-agent CLI update preflight covers already-running containers, where
-`postStartCommand` does not necessarily run before a new SSH session. Its output
-is routed to stderr so stdout remains reserved for SSH traffic.
+Boxdown augments child-process `PATH` with common macOS GUI-missing tool
+locations, including `/usr/local/bin`, Homebrew paths, `~/.docker/bin`, and
+Docker Desktop's bundled CLI directory. This lets GUI apps such as Claude launch
+the SSH proxy through OpenSSH even when their launchd environment cannot
+resolve `docker` by default.
+
+The default coding-agent CLI update preflight covers Codex and Claude Code in
+already-running containers, where `postStartCommand` does not necessarily run
+before a new SSH session. OpenCode and Antigravity remain lazy installs through
+their direct `boxdown` commands. The preflight output is routed to stderr so
+stdout remains reserved for SSH traffic.
+
+SSH proxy startup uses the same concise progress protocol as `setup` and
+`start`, but routes progress and failure summaries to stderr because stdout is
+reserved for the SSH stream. Use `boxdown ssh-proxy --verbose` only for manual
+debugging.
+
+## Local Web Tunnels
+
+The SSH proxy supports TCP forwarding, so Boxdown can expose a web server that is
+listening only inside the devcontainer.
+
+From the target project directory:
+
+```sh
+boxdown tunnel --port 3030
+```
+
+When `--port` is omitted in an interactive terminal, Boxdown prompts for one or
+more port mappings. Pressing Enter accepts the generated devcontainer published
+port when Boxdown can read one from the config, currently `3000`. Non-TTY and
+CI runs keep requiring an explicit `--port`.
+
+From another directory:
+
+```sh
+boxdown tunnel --workspace /path/to/project --port 3030
+```
+
+This starts or reuses the devcontainer, ensures the SSH alias exists, and then
+keeps a foreground SSH tunnel open:
+
+```text
+127.0.0.1:3030 -> localhost:3030
+```
+
+While the tunnel is running, host browsers and the Codex in-app browser can open
+`http://localhost:3030/`.
+
+Tunnel setup also hides raw devcontainer startup logs by default; pass
+`--verbose` before the foreground tunnel opens when debugging startup.
+
+Repeat `--port` for multiple forwards. Use `<local:remote>` when the host port
+should differ from the container port:
+
+```sh
+boxdown tunnel --port 3030 --port 8080:3031
+```
+
+The tunnel targets remote `localhost` rather than `127.0.0.1` so servers that
+bind to the container's IPv6 loopback, such as some Slidev dev sessions, still
+work.
+
+Devcontainer `forwardPorts` is an editor hint, not a host listener in the Codex
+desktop app. Docker `runArgs` / `appPort` publishing can also expose services,
+but it requires the server to bind to an externally reachable container address
+such as `0.0.0.0` and may require recreating the container.
+
+Codex's own detected-port forwarding may create a random host URL such as
+`http://localhost:52548/`. That is expected, but the generated SSH forward may
+target remote `127.0.0.1:<port>`. If the dev server is only listening on remote
+IPv6 loopback (`[::1]:<port>`), the random forwarded URL can reset even though a
+listener exists. In that case, either use `boxdown tunnel --port <port>`, or
+start the dev server with a host flag such as `--host 0.0.0.0`.
+
+## IPv4 and IPv6 Loopback Options
+
+The Codex detected-port issue is not an `/etc/hosts` problem. `/etc/hosts` maps
+names such as `localhost` to addresses, but a generated SSH forward that targets
+remote `127.0.0.1:<port>` uses a numeric IP literal. No name lookup happens, so
+changing the container's `localhost` entry would not make `127.0.0.1` reach a
+server that is listening only on `[::1]`.
+
+Potential Boxdown-side approaches:
+
+1. Inject a Node.js IPv4 preference.
+
+   Boxdown could add this to the generated devcontainer environment:
+
+   ```sh
+   NODE_OPTIONS=--dns-result-order=ipv4first
+   ```
+
+   This would likely make Node-based dev servers such as Vite and Slidev resolve
+   `localhost` to `127.0.0.1` first, causing Codex's generated
+   `127.0.0.1:<port>` forward to work without app-specific flags.
+
+   This is the smallest built-in fix to evaluate, but it mainly helps Node.js
+   tools. It would not normalize loopback behavior for dev servers written in
+   other runtimes.
+
+2. Run a Boxdown-managed loopback bridge inside the container.
+
+   A background helper could detect a listener on `[::1]:<port>` where
+   `127.0.0.1:<port>` is not listening, then bind `127.0.0.1:<port>` and proxy
+   traffic to `[::1]:<port>`.
+
+   This would be runtime-agnostic and would let Codex's generated
+   `127.0.0.1:<port>` forwards work for more tools. The tradeoff is a more
+   complex container-side service: it would need port discovery, race handling,
+   conflict handling, lifecycle cleanup, and clear diagnostics.
+
+3. Keep `boxdown tunnel` as the explicit escape hatch.
+
+   The current `boxdown tunnel --port <port>` command creates Boxdown's own SSH
+   local forward and targets remote `localhost:<port>` rather than remote
+   `127.0.0.1:<port>`. That covers dev servers bound to IPv6 loopback,
+   IPv4 loopback, or all interfaces, as long as the remote `localhost` name
+   resolves to a reachable address for that server.
+
+   This is reliable and fully under Boxdown's control, but it requires an extra
+   foreground command. It is useful as a debugging and fallback path, not a
+   fully automatic browser-forwarding experience.
 
 ## Key Boundary