Run your agent in a Minimal box, and work in it from Cursor.

Getting started · Cursor guide · Commands · How it works

Minimal runs each box in its own microVM on your Mac. min-cursor makes those boxes Cursor's: a Minimal view in Cursor creates a box from a folder (or an empty one), opens a window inside it, and tidies up afterwards. Cursor's own Remote-SSH does the rest, so terminals, extensions, port forwarding and Cursor's agent all run in the box.

• Nothing listens on a port. An OpenSSH sshd runs inside the box on demand, behind a ProxyCommand that 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. The one exception is opt-in: min-cursor worker keeps your Cursor login in that box.
• 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 (min 0.7.0 or newer).
• Cursor. Its Remote-SSH extension (anysphere.remote-ssh) ships with it.
• jq and python3 on the host; just and Node.js to build the extension.

brew install jq just node

Build the extension and install it into Cursor:

git clone https://github.com/gominimal/min-cursor.git min-cursor && cd min-cursor
just vsix
cursor --install-extension min-cursor.vsix

No cursor command? Install it from Cursor (Command Palette → Shell Command: Install 'cursor' command in PATH), or install the file from the Extensions view: … → Install from VSIX… → min-cursor.vsix. If the command is installed but your shell still cannot find it, link it:

mkdir -p ~/.local/bin
ln -s /Applications/Cursor.app/Contents/Resources/app/bin/cursor ~/.local/bin/cursor

~/.local/bin must be on your PATH for the shell to find the link; if it is not, add it to your shell profile or link into a directory that already is.

Installing may print a DEP0169 deprecation warning. You can ignore it; the extension is installed.

Launch Minimal from Cursor's IDE mode, not the Agents window.

1. In Cursor, open the Minimal view in the activity bar (the Minimal mark).
2. Click Set up Minimal boxes.

Set up adds one Include line to the top of ~/.ssh/config and a marked block to Cursor's settings.json, backing up both first. It copies Minimal's skills (minimal-setup, -config, -loadouts, -networking, -diag) into ~/.cursor/skills, so Cursor's agent on your Mac knows how to use Minimal, and never replaces a skill of yours. It also links the cursor loadout into ~/.config/minimal/loadouts (your default_loadouts are left alone). Minimal: Remove Setup puts everything back.

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).

Cursor's agent knows where it is. On your Mac it has Minimal's host skills; in a box window it has minimal-sandbox instead, so it 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-cursor CLI, which also works on its own:

just install                         # setup from this checkout (CLI link, loadout, ssh, settings)
min-cursor open ~/code/myproject     # box for the folder + a Cursor window on /workbench
min-cursor status                    # boxes, in use, idle age
min-cursor destroy myproject-3f9c    # asks first

ssh min-cursor.NAME works from any terminal too, and so do scp and rsync. Every command is in docs/commands.md.

• Cursor guide: how Cursor's Remote-SSH reaches a box, and the settings min-cursor 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 Cursor'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.

Cursor is a trademark of Anysphere, Inc.; min-cursor is not affiliated with or endorsed by Anysphere.

Apache-2.0.