Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions .claude/skills/dev-onboard/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,9 @@ finish by printing the punchlist of whatever remains for the human.
- Node.js 20+ (`node --version`);
- VS Code 1.90+;
- Docker Sandboxes - required for real sandbox runs, optional for build-only work. Windows
install lands `sbx` at `%LOCALAPPDATA%\DockerSandboxes\bin\sbx.exe` (not on PATH); probe
with `sbx version` at that path, and note that sign-in is a manual browser step.
install lands `sbx` at `%LOCALAPPDATA%\DockerSandboxes\bin\sbx.exe`; probe it there
rather than through PATH, which may or may not carry it. `sbx diagnose` reports every
precondition at once (binary, daemon, authentication); sign-in is a manual browser step.
2. **Git identity**: commits carry no agent identity in messages (see `git-commit-push`);
nothing to configure beyond a normal user.
3. `npm install`.
Expand Down
9 changes: 6 additions & 3 deletions .claude/skills/ext-run-local/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,12 @@ running the extension and checking the FR's behaviour by hand.

## Prerequisites check

- Docker Sandboxes installed and signed in. `sbx` is not on PATH on Windows - probe it at
`%LOCALAPPDATA%\DockerSandboxes\bin\sbx.exe` (`sbx version`). Without it the extension loads
but every lifecycle action fails; layer-only changes can still be smoke-tested.
- Docker Sandboxes installed and signed in. Do not rely on PATH on Windows - probe it at
`%LOCALAPPDATA%\DockerSandboxes\bin\sbx.exe` (`sbx diagnose` reports binary, daemon and
sign-in in one go). Without it the extension loads and now says so - `⚠ Sandbox not
available` in the status bar, a readiness node in the Sandboxes view, a modal on New
Sandbox (FR-059) - while every lifecycle action stays blocked; layer-only changes can
still be smoke-tested.

## Steps

Expand Down
3 changes: 2 additions & 1 deletion .claude/skills/spec-implement/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,8 @@ CLAUDE.md is the rule surface - this skill sequences it, it does not replace it.
4. **Respect the traps** (they are documented in CLAUDE.md, they bite anyway): esbuild does not
typecheck - only `npm run verify` proves the code; there is no `sbx start` - resume is
`sbx run`; `/home/agent/workspace` is a decoy - the real mount is the translated host path;
`sbx` is not on PATH on Windows.
never rely on `sbx` being on PATH on Windows (`sbxPath()` checks the install location
first, on every call - do not reintroduce a memo).
5. **Protect the invariants**: attach ("Connect") stays the primary action when a sandbox
exists; no implicit default sandbox; terminal-first (no chat panels); secrets only over
stdin, never argv/env/image; argv allowlist and path containment stay intact.
Expand Down
9 changes: 6 additions & 3 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,9 +50,12 @@ There is no test runner yet; verification is `npm run verify` + manual run + dir
one carve-out: the bash template in `src/script.ts` *renders* sbx calls into the
generated `.sandbox/scripts/sbx.sh` (FR-052) for external shells; the extension
never executes them, but keep the template in sync when CLI shapes change.
- **`sbx` is not on PATH** (Windows): it lives at
`%LOCALAPPDATA%\DockerSandboxes\bin\sbx.exe`. `sbxPath()` resolves it; that same path
is used as the terminal `shellPath`.
- **Never rely on `sbx` being on PATH** (Windows): it lives at
`%LOCALAPPDATA%\DockerSandboxes\bin\sbx.exe`, and `sbxPath()` checks that location
*before* PATH, on every call. A PATH entry may or may not exist (some installs have one),
and it never rescues a VS Code window that was already open when sbx was installed — that
process captured its environment beforehand. The resolved path doubles as the terminal
`shellPath`.
- **There is no `sbx start`** — resume a stopped sandbox with `sbx run <name>` (or
`sbx exec`, which auto-starts).
- Lifecycle: Create/Attach → `sbx run`; Stop → `sbx stop`; destroy → `sbx rm --force`;
Expand Down
8 changes: 5 additions & 3 deletions docs/Architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -409,9 +409,11 @@ executable and `shellArgs` = the `run`/`exec` invocation. The native terminal ow
real PTY (ConPTY on Windows), so ANSI, cursor control, resize, and interactive agents
work with no native dependency (no `node-pty`). This satisfies FR-010/FR-011.

The `sbx` executable is resolved at runtime: the Windows installer places it at
`%LOCALAPPDATA%\DockerSandboxes\bin\sbx.exe` and does **not** add it to `PATH`, so
`sbx.ts` checks that location first and falls back to the bare command name.
The `sbx` executable is resolved at runtime, on every call (§4): the Windows installer places
it at `%LOCALAPPDATA%\DockerSandboxes\bin\sbx.exe`, so `sbx.ts` checks that location first and
falls back to the bare command name. Whether a `PATH` entry for that directory also exists
varies by install and is **not** relied upon — and it would not help the case that matters
anyway, a window already open when sbx was installed, whose environment block predates it.

**Agent terminals are pooled per sandbox and reused** — a second `sbx run <name>` is not
a separate instance, it's another attach session into the same microVM (shared
Expand Down