Run your agent in a Minimal box, and work in it from VS Code.
Getting started · VS Code guide · Commands · How it works
Minimal runs each box in its own microVM on your Mac. min-vscode makes those boxes VS Code's: a Minimal view in VS Code creates a box from a folder (or an empty one), opens a window inside it, and tidies up afterwards. Microsoft's Remote-SSH extension does the rest, so terminals, extensions and port forwarding all run in the box.
- Nothing listens on a port. An OpenSSH
sshdruns inside the box on demand, behind aProxyCommandthat rides Minimal's own exec channel. - Only a public key enters the box. Each box gets its own key; the box's host key is pinned; agent and X11 forwarding are off.
- Nothing is destroyed without your click. Destroy and clean-up always ask, and ask again before discarding changes Minimal has not saved.
- macOS with Minimal (
min0.7.0 or newer). - VS Code with Microsoft's Remote-SSH
extension (
ms-vscode-remote.remote-ssh), which does not ship with it:code --install-extension ms-vscode-remote.remote-ssh. jqandpython3on the host;justand Node.js to build the extension.
brew install jq just nodeBuild the extension and install it into VS Code:
git clone https://github.com/gominimal/min-vscode.git min-vscode && cd min-vscode
just vsix
code --install-extension min-vscode.vsixNo code command? Install it from VS Code (Command Palette → Shell
Command: Install 'code' command in PATH), or install the file from the
Extensions view: … → Install from VSIX… → min-vscode.vsix.
- In VS Code, open the Minimal view in the activity bar (the Minimal mark).
- Click Set up Minimal boxes.
Set up adds one Include line to the top of ~/.ssh/config and a marked
block to VS Code's settings.json, backing up both first. It copies
Minimal's skills (minimal-setup, -config, -loadouts, -networking, -diag) into ~/.copilot/skills and ~/.claude/skills, so
Copilot and Claude Code on your Mac know how to use Minimal, and never
replaces a skill of yours. It also links the
vscode loadout into ~/.config/minimal/loadouts (your default_loadouts
are left alone). Minimal: Remove Setup puts everything back.
| To | Do |
|---|---|
| Start on a project | New Box from Folder… (the view's title bar, the Command Palette, or right-click a folder in the Explorer). The folder is copied to /workbench in a new box and a window opens on it. |
| Start from scratch | New Empty Box: an empty /workbench. |
| Come back to a box | Click it in the Minimal view, or pick it from File → Open Recent. Open Box in New Window… keeps the current window. |
| See what is running | The Minimal view: each box with in use, idle 2h or stopped. A box window shows its name in the status bar. |
| Finish with a box | Right-click → Destroy Box… |
| Tidy up | Clean Up Idle Boxes… asks about each box nothing is connected to, oldest first. |
| Diagnose | Minimal: Run Doctor; output in Output → Minimal. |
A box is a copy. Edits inside it do not change the folder on your Mac.
Get work out with git: commit and push from the box's terminal (git is in
every box).
Agents know where they are. On your Mac, Copilot and Claude Code have
Minimal's host skills; in a box they have minimal-sandbox instead (in
~/.copilot/skills and ~/.claude/skills), so an agent can add a missing
tool or package from inside the box rather than reach for host commands
that do not exist there. The skills come from
gominimal/minimal-skills
(MIT), pinned; just skills refreshes them.
The extension runs the min-vscode CLI, which also works on its own:
just install # setup from this checkout (CLI link, loadout, ssh, settings)
min-vscode open ~/code/myproject # box for the folder + a VS Code window on /workbench
min-vscode status # boxes, in use, idle age
min-vscode destroy myproject-3f9c # asks firstssh min-vscode.NAME works from any terminal too, and so do scp and
rsync. Every command is in docs/commands.md.
- VS Code guide: how VS Code's Remote-SSH reaches a box, and the settings min-vscode keeps.
- Commands: every CLI command and the naming rules.
- Configuration: environment, loadout, rolling back.
- What never leaves the host: keys, pinning, prompts.
- How it works: transport, sshd flags, stanzas,
_proxy. - Troubleshooting, starting with Run Doctor.
- CHANGELOG.
Minimal: Remove Setup (or just uninstall), then uninstall Minimal
Boxes from VS Code's Extensions view. Your boxes keep running; destroy them
first if you are done with them.
just check runs shellcheck, a python3 compile check, the test suite (twice:
once with a long host prefix) and a type-check of the extension (just ext-deps once). The tests never touch a real box, editor or ~/.ssh.
Working rules are in CLAUDE.md.
Visual Studio Code is a trademark of Microsoft Corporation; min-vscode is not affiliated with or endorsed by Microsoft.