SmolVM AGENTS.md

SmolVM Context

SmolVM gives AI agents their own disposable computer. Each sandbox is a lightweight virtual machine that boots in seconds, runs any code or command you throw at it, and disappears when you're done — nothing touches the host.

🚀 Project Overview

SmolVM is specifically designed to provide a secure "sandbox" for AI agents to execute code, browse the web, or perform system-level tasks safely.

🧪 Development

Key Commands

• Testing: pytest (runs the suite in tests/)
• Linting & Formatting: uv run ruff check . or uv run ruff format .

Release checklist

• For guest-agent or published-image changes, build and smoke the new image release before tagging the SmolVM package release.
• Update src/smolvm/images/published.py with the new IMAGES_RELEASE_TAG and rootfs SHA pins before the PyPI tag is pushed.
• Also update src/smolvm/images/builder.py::_GUEST_AGENT_RELEASE_SHA256 from the smolvm-guest-agent-linux-<arch>.sha256 release assets. This is a separate pin from the rootfs manifest.
• Verify both paths: uv run smolvm ... from a source checkout may build or use the local guest-agent binary, while smolvm ... from uv tool uses the installed wheel and downloads the standalone guest-agent release binary.
• Only tag the SmolVM package release after the image manifest, guest-agent binary SHA pins, image smoke, and focused tests are complete.

CLI design

• New CLI commands follow a NOUN-VERB structure: smolvm <noun> <verb>, e.g. smolvm codex start, not smolvm start codex.
• The noun names the resource (a sandbox, a harness, a browser session); the verb names the action on it (start, stop, ssh).
• This scales naturally as actions grow: smolvm codex start, then later smolvm codex logs, smolvm codex status, etc.
• When adding a new harness or resource, register it as a top-level subcommand and put its actions underneath, instead of overloading a global verb.
• Documented exceptions: the top-level smolvm prune and smolvm images aliases exist for muscle memory (images mirrors docker images); both delegate to their NOUN-VERB homes (image prune, image list). Do not add further top-level aliases without discussion.
• smolvm completion <shell> is an accepted top-level meta-command (like git/gh completion): it acts on the CLI itself rather than a sandbox resource, so it sits outside the NOUN-VERB rule by design.