{"id":44675889,"url":"https://github.com/celestoai/smolvm","last_synced_at":"2026-06-07T00:01:42.295Z","repository":{"id":338531985,"uuid":"1158200188","full_name":"CelestoAI/SmolVM","owner":"CelestoAI","description":"Open-source AI sandbox infrastructure for code execution, browser use, and AI agents.","archived":false,"fork":false,"pushed_at":"2026-04-22T03:06:56.000Z","size":1144,"stargazers_count":368,"open_issues_count":6,"forks_count":27,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-22T05:13:33.277Z","etag":null,"topics":["agent-runtime","browser-agent","browser-use","computer-use","openclaw","sandbox"],"latest_commit_sha":null,"homepage":"https://docs.celesto.ai/smolvm","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CelestoAI.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-15T00:31:08.000Z","updated_at":"2026-04-22T03:07:00.000Z","dependencies_parsed_at":null,"dependency_job_id":"6691b87f-19c4-4650-bc4f-ccd94599ce9e","html_url":"https://github.com/CelestoAI/SmolVM","commit_stats":null,"previous_names":["celestoai/smolvm"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/CelestoAI/SmolVM","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CelestoAI%2FSmolVM","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CelestoAI%2FSmolVM/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CelestoAI%2FSmolVM/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CelestoAI%2FSmolVM/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CelestoAI","download_url":"https://codeload.github.com/CelestoAI/SmolVM/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CelestoAI%2FSmolVM/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32317168,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T23:26:28.701Z","status":"ssl_error","status_checked_at":"2026-04-26T23:26:25.802Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-runtime","browser-agent","browser-use","computer-use","openclaw","sandbox"],"created_at":"2026-02-15T03:06:24.542Z","updated_at":"2026-06-07T00:01:42.238Z","avatar_url":"https://github.com/CelestoAI.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# SmolVM\n\n#### Secure, isolated computers that AI agents can use to browse, run code, and get real work done. \n\n\n\u003cimg src=\"https://ik.imagekit.io/gradsflow/celestoai/logo/celesto%20cover%20low_vFigbRaJI.png\"\u003e\n\n[![CodeQL](https://github.com/CelestoAI/SmolVM/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/CelestoAI/SmolVM/actions/workflows/github-code-scanning/codeql)\n[![Run Tests](https://github.com/CelestoAI/SmolVM/actions/workflows/pytest.yml/badge.svg)](https://github.com/CelestoAI/SmolVM/actions/workflows/pytest.yml)\n[![License](https://img.shields.io/badge/License-Apache_2.0-orange.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-orange.svg)](https://www.python.org/downloads/)\n\n[Quick start](#quickstart) • [Examples](#examples) • [Features](https://docs.celesto.ai/smolvm/features) • [Performance](#performance) • [Docs](https://docs.celesto.ai) • [Community Slack](https://join.slack.com/t/celestoai/shared_invite/zt-3qc7h8gno-Nb5_PElEWHDNnGqdVzC~4Q) \n\n\u003c/div\u003e\n\n---\n\nSmolVM gives AI agents their own disposable computer. \nEach microVM boots in milliseconds, runs any code or software you throw at it, persists files and state across sessions, and disappears when you're done — ready to handle thousands of sandboxes in production.\n\n\u003cbr\u003e\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003cp\u003e\u003cimg src=\"https://api.iconify.design/lucide/zap.svg?color=%236e7681\" width=\"24\" height=\"24\" align=\"absmiddle\" alt=\"\"\u003e \u003cstrong\u003eSub-second boot\u003c/strong\u003e\u003c/p\u003e\n\u003cp\u003eYour agent has a running VM before the API call returns (~500\u0026nbsp;ms). No waiting for provisioning or image pulls.\u003c/p\u003e\n\u003cp\u003e\u003ca href=\"#performance\"\u003eRead more →\u003c/a\u003e\u003c/p\u003e\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003cp\u003e\u003cimg src=\"https://api.iconify.design/lucide/shield.svg?color=%236e7681\" width=\"24\" height=\"24\" align=\"absmiddle\" alt=\"\"\u003e \u003cstrong\u003eHardware isolation\u003c/strong\u003e\u003c/p\u003e\n\u003cp\u003eEach sandbox runs in its own virtual machine with hardware-level separation. Untrusted code can't escape or access your host.\u003c/p\u003e\n\u003cp\u003e\u003ca href=\"#security\"\u003eRead more →\u003c/a\u003e\u003c/p\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003cp\u003e\u003cimg src=\"https://api.iconify.design/lucide/network.svg?color=%236e7681\" width=\"24\" height=\"24\" align=\"absmiddle\" alt=\"\"\u003e \u003cstrong\u003eNetwork controls\u003c/strong\u003e\u003c/p\u003e\n\u003cp\u003eLock down egress to specific domains so agents can't call home or exfiltrate data.\u003c/p\u003e\n\u003cp\u003e\u003ca href=\"#network-controls\"\u003eRead more →\u003c/a\u003e\u003c/p\u003e\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003cp\u003e\u003cimg src=\"https://api.iconify.design/lucide/monitor.svg?color=%236e7681\" width=\"24\" height=\"24\" align=\"absmiddle\" alt=\"\"\u003e \u003cstrong\u003eBrowser sandbox\u003c/strong\u003e\u003c/p\u003e\n\u003cp\u003eGive agents a full browser inside the sandbox. Navigate, click, fill forms, and watch it live in your own browser.\u003c/p\u003e\n\u003cp\u003e\u003ca href=\"#browser-sandbox\"\u003eRead more →\u003c/a\u003e\u003c/p\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003cp\u003e\u003cimg src=\"https://api.iconify.design/lucide/folder.svg?color=%236e7681\" width=\"24\" height=\"24\" align=\"absmiddle\" alt=\"\"\u003e \u003cstrong\u003eFile sharing\u003c/strong\u003e\u003c/p\u003e\n\u003cp\u003eShare local directories with the sandbox, read-only or writable. Agents work on your real codebase without copying files around.\u003c/p\u003e\n\u003cp\u003e\u003ca href=\"#mount-host-directories\"\u003eRead more →\u003c/a\u003e\u003c/p\u003e\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003cp\u003e\u003cimg src=\"https://api.iconify.design/lucide/camera.svg?color=%236e7681\" width=\"24\" height=\"24\" align=\"absmiddle\" alt=\"\"\u003e \u003cstrong\u003eSnapshots\u003c/strong\u003e\u003c/p\u003e\n\u003cp\u003ePause a sandbox and resume it later with everything intact — memory, disk, and running processes.\u003c/p\u003e\n\u003cp\u003e\u003ca href=\"https://docs.celesto.ai/smolvm/features/snapshots\"\u003eRead more →\u003c/a\u003e\u003c/p\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003cp\u003e\u003cimg src=\"https://api.iconify.design/lucide/bot.svg?color=%236e7681\" width=\"24\" height=\"24\" align=\"absmiddle\" alt=\"\"\u003e \u003cstrong\u003eCoding agents\u003c/strong\u003e\u003c/p\u003e\n\u003cp\u003eOne command to launch a sandbox with Claude Code, Codex, or Pi pre-installed and git credentials forwarded.\u003c/p\u003e\n\u003cp\u003e\u003ca href=\"#coding-agents\"\u003eRead more →\u003c/a\u003e\u003c/p\u003e\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003cp\u003e\u003cimg src=\"docs/assets/icons/windows.svg\" width=\"24\" height=\"24\" align=\"absmiddle\" alt=\"\"\u003e \u003cstrong\u003eWindows sandbox\u003c/strong\u003e\u003c/p\u003e\n\u003cp\u003eBoot a Windows 11 guest and drive it from Python — PowerShell, file upload, env vars. Linux host only for now.\u003c/p\u003e\n\u003cp\u003e\u003ca href=\"#windows-sandbox\"\u003eRead more →\u003c/a\u003e\u003c/p\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n\n## Use cases\n\n- **Run untrusted code safely.** Execute AI-generated code in an isolated sandbox instead of on your machine.\n- **Give agents a browser.** Spin up a full browser session that agents can see and control in real time.\n- **Let agents read your project.** Mount a local directory so agents can explore your codebase inside a sandbox.\n- **Keep state across turns.** Reuse the same sandbox throughout a multi-step workflow.\n\n\n## Quickstart\n\nInstall SmolVM with a single command:\n\n```bash\ncurl -sSL https://celesto.ai/install.sh | bash\n```\n\nThis installs everything you need (including Python), configures your machine, and verifies the setup.\n\n\u003cdetails\u003e\n\u003csummary\u003eManual installation\u003c/summary\u003e\n\n```bash\npip install smolvm\nsmolvm setup\nsmolvm doctor\n```\n\nOn supported Linux and macOS systems, `pip install smolvm` also pulls in the matching `smolvm-core` wheel automatically. Most users do not need Rust installed.\n\nLinux may prompt for `sudo` during setup so it can install host dependencies and configure runtime permissions.\n\nFor golden-AMI builds, two-stage deploys, pinning the Firecracker version, and other non-default install paths, see [docs/installation.md](docs/installation.md).\n\n\u003c/details\u003e\n\n### Start a sandbox in Python\n\n```python\nfrom smolvm import SmolVM\n\nvm = SmolVM()\nresult = vm.run(\"echo 'Hello from the sandbox!'\")\nprint(result)\nvm.stop()\n```\n\n### Start a sandbox from the CLI\n\nCreate a sandbox, check that it's running, then stop it:\n\n```bash\nsmolvm create --name my-sandbox\n# my-sandbox  running  172.16.0.2\n\nsmolvm list\n# NAME         STATUS   IP\n# my-sandbox   running  172.16.0.2\n\nsmolvm stop my-sandbox\n```\n\nOpen a shell inside a running sandbox:\n\n```bash\nsmolvm ssh my-sandbox\n```\n\n## Windows sandbox\n\nSmolVM can boot a Windows 11 guest as well as Linux. Hand it a Windows image and you get the same Python and CLI you use for Linux — run PowerShell, upload files, set environment variables, and run many sandboxes in parallel from one baseline image.\n\n```python\nfrom smolvm import SmolVM\n\nwith SmolVM(\n    os=\"windows\",\n    image=\"~/.smolvm/images/win11.qcow2\",\n    ssh_user=\"smolvm\",\n    ssh_password=\"smolvm\",\n) as vm:\n    print(vm.run(\"Write-Output 'hello from windows'\").stdout)\n```\n\nBuild your own image from a Windows ISO:\n\n```bash\nsmolvm windows build-image --iso ./Win11.iso \\\n    --virtio-win-iso ./virtio-win.iso \\\n    --output ~/.smolvm/images/win11.qcow2\n```\n\nWindows guests need a Linux host with KVM. Host mounts, network controls, and snapshots are Linux-only today. See the full [Windows guide](https://docs.celesto.ai/smolvm/guides/windows-guests) for details.\n\n\n## Coding agents\n\nIt sucks to “press enter and accept changes” every few seconds while using coding agents. SmolVM makes it easy to isolate the agent coding environment from the host (laptops).\n\nWith a single command you get a claude/codex pre-installed sandbox ready with git credential to make you build a billion dollar business without making any mistake ;)\n\nVideo tutorial:\n\n\u003ca href=\"https://youtu.be/j1qyrTsI0Jw\"\u003e\u003cimg src=\"https://img.youtube.com/vi/j1qyrTsI0Jw/maxresdefault.jpg\" alt=\"Coding agents in a sandbox\" width=\"480\"\u003e\u003c/a\u003e\n\n```bash\nsmolvm codex start  # start a new environment with codex preinstalled\n\nsmolvm claude start  # start a new environment with claude preinstalled\n\nsmolvm pi start  # start a new environment with the Pi coding agent preinstalled\n```\n\n\n## Browser sandbox\n\nSmolVM can also start a full browser inside a sandbox. This is useful when agents need to navigate websites, fill out forms, or take screenshots.\n\nStart a browser session with a live view you can watch in your own browser:\n\n```bash\nsmolvm browser start --live\n# Session:   sess_a1b2c3\n# Live view: http://localhost:6080\n```\n\nOpen the URL to watch the browser in real time. When you're done, list and stop sessions:\n\n```bash\nsmolvm browser list\nsmolvm browser stop sess_a1b2c3\n```\n\nSee [examples/browser_session.py](examples/browser_session.py) for the Python equivalent.\n\n\n## Network controls\n\nBy default, sandboxes have full internet access. You can restrict which domains a sandbox can reach by passing `internet_settings`:\n\n```python\nfrom smolvm import SmolVM\n\nvm = SmolVM(internet_settings={\n    \"allowed_domains\": [\"https://api.openai.com\"],\n})\n\nvm.run(\"curl https://api.openai.com/v1/models\")    # allowed\nvm.run(\"curl https://evil.com/exfiltrate\")         # blocked\n```\n\nSee [docs/concepts/network-egress-controls.md](docs/concepts/network-egress-controls.md) for how it works under the hood.\n\n\n## Mount host directories\n\nYou can give a sandbox access to a folder on your machine. This is useful when an agent needs to work with an existing project without copying files back and forth.\n\n```bash\nsmolvm create --mount ~/Projects/my-app\nsmolvm ssh my-sandbox\nls /workspace   # your host files appear here\n```\n\nBy default the host folder is read-only — the sandbox can read every file, but changes stay inside the sandbox and never touch the originals. If the agent creates or edits files under `/workspace`, those changes live only in the VM's overlay layer.\n\nMount at a custom path, or mount multiple directories:\n\n```bash\nsmolvm create --mount ~/Projects/my-app:/code --mount ~/data:/mnt/data\n```\n\nWhen you do want the sandbox to edit your host files, add `--writable-mounts`:\n\n```bash\nsmolvm create --mount ~/Projects/my-app --writable-mounts\n```\n\nEvery directory passed with `--mount` becomes writable; writes from the guest are visible on the host immediately. The flag applies to all mounts on that command, so don't pair a folder you want the sandbox to modify with one you want kept untouched.\n\nThe same works from Python:\n\n```python\nfrom smolvm import SmolVM\n\nwith SmolVM(mounts=[\"~/Projects/my-app\"], writable_mounts=True) as vm:\n    vm.run(\"echo hello \u003e /workspace/from-sandbox.txt\")\n```\n\n## Upload a file\n\nYou can copy one file into a running sandbox without mounting a whole folder.\nThis is useful when an agent needs a config file, script, or small input file.\n\n```bash\n# Copy a file from your machine into the sandbox.\nsmolvm file upload my-sandbox ./prompt.txt /tmp/prompt.txt\n\n# Open a shell in the sandbox to confirm the file is there.\nsmolvm ssh my-sandbox\n# Then, inside the sandbox shell:\ncat /tmp/prompt.txt\n```\n\nThe same works from Python:\n\n```python\nfrom smolvm import SmolVM\n\nvm = SmolVM.from_id(\"my-sandbox\")\nvm.upload_file(\"./prompt.txt\", \"/tmp/prompt.txt\")\nvm.close()\n```\n\nThe destination must be an absolute path inside the sandbox (starting\nwith `/`), and any existing file at that path is overwritten.\n\n\n## Examples\n\n### Getting started\n\n| What you'll learn | Example |\n| --- | --- |\n| Run code in a sandbox | [quickstart_sandbox.py](examples/quickstart_sandbox.py) |\n| Start a browser session | [browser_session.py](examples/browser_session.py) |\n| Pass environment variables into a sandbox | [env_injection.py](examples/env_injection.py) |\n\n### Agent framework integrations\n\nThese examples show how to wrap SmolVM as a tool for popular agent frameworks, so an AI model can run shell commands or drive a browser through your sandbox.\n\n| Framework | Example |\n| --- | --- |\n| OpenAI Agents | [openai_agents_tool.py](examples/agent_tools/openai_agents_tool.py) |\n| LangChain | [langchain_tool.py](examples/agent_tools/langchain_tool.py) |\n| PydanticAI — shell tool | [pydanticai_tool.py](examples/agent_tools/pydanticai_tool.py) |\n| PydanticAI — reusable sandbox across turns | [pydanticai_reusable_tool.py](examples/agent_tools/pydanticai_reusable_tool.py) |\n| PydanticAI — browser automation | [pydanticai_agent_browser.py](examples/agent_tools/pydanticai_agent_browser.py) |\n| Computer use (click and type) | [computer_use_browser.py](examples/agent_tools/computer_use_browser.py) |\n\n### Advanced\n\n| What it does | Example |\n| --- | --- |\n| Install and run OpenClaw inside a Debian sandbox with a 4 GB root filesystem | [openclaw.py](examples/openclaw.py) |\n\nEach script shows its own `pip install ...` line when it needs extra packages.\n\n\n## Security\n\nSmolVM automatically trusts new sandboxes on first connection to keep setup simple. This is safe for local development, but you should not expose sandbox network ports publicly without extra controls. See [SECURITY.md](SECURITY.md) for the full policy and scope.\n\n\n## Performance\n\nSmolVM ships a benchmark suite that measures the timings AI agents actually feel: cold start, time-to-interactive, pause/resume, and snapshot create/restore. It drives the public Python SDK on whichever backend is native to your host — Firecracker on Linux, QEMU on macOS.\n\nRun it locally:\n\n```bash\nuv run python scripts/benchmarks/bench.py\n```\n\nSee [scripts/benchmarks/README.md](scripts/benchmarks/README.md) for flags, output format, and what each metric means.\n\n\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) to get started.\n\n\n## License\n\nApache 2.0 — see [LICENSE](LICENSE) for details.\n\n---\n\u003cdiv align=\"center\"\u003e\nBuilt with 🧡 in London by \u003ca href=\"https://celesto.ai\"\u003eCelesto AI\u003c/a\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcelestoai%2Fsmolvm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcelestoai%2Fsmolvm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcelestoai%2Fsmolvm/lists"}