# SmolVM ships under the name Celesto in every file except its own URL

> This repository is SmolVM and the product is Celesto, a sandbox that gives an AI agent a lightweight virtual machine with persistent state. Every badge, project URL, package name and install script inside it says Celesto, the badges point at a repository that is not this one, and the release feed mixes semver tags with dated image builds. Underneath is a wider surface than an alpha version suggests: a Python SDK, a Rust core, a guest agent, a kernel and a TypeScript UI.

**CelestoAI/SmolVM** — Secure and persistent computer for AI agents -- built for long-running agents, build your own Grokbot, and Muse.

- Repository: https://github.com/CelestoAI/SmolVM
- Website: https://docs.celesto.ai/smolvm
- Stars: 1,005 · Forks: 82
- Language: Python
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/celestoai-smolvm

## The repository is SmolVM and every link inside it points at Celesto

Nothing in the file matches the repository it sits in.

The badges at the top link to the code scanning and test workflows of a different repository, `CelestoAI/celesto`, not of this one. The project manifest is named `celesto`, and its repository, issues and changelog URLs all point at `CelestoAI/celesto`. The Rust workspace says the same thing with a third spelling, `CelestoAI/Celesto`, capital C. The install script lives on a company domain, the docs do too, and the PyPI package is `celesto`.

Meanwhile the repository slug is SmolVM, the homepage recorded for the repository is a path under the docs domain with smolvm in it, and the description on the repository talks about building a computer, building your own Grokbot, and Muse.

Only part of that description reaches the page. OpenMuse has its own section, a banner and a directory in the tree. Grokbot appears nowhere in the README, which is worth knowing if you arrived looking for it.

None of this breaks the software, and an experienced reader will work out within a minute that SmolVM is the repository and Celesto is the product. It does mean that a search for this project, a link check, or an automated dependency scanner will have to reconcile three spellings of one organisation path, and that the badge telling you whether tests pass is reporting on a different repository.

## The release feed mixes 0.1.3.post1 with images-2026.10.03.0

Two release schemes share one tag list, and they answer different questions.

The semantic versions are 0.1.3, published 2026-09-28, and 0.1.3.post1 the same morning, and the manifest version is 0.1.3.post1, so the package and the newest code tag agree. The project classifies itself as Development Status 3, Alpha, and the version number says the same thing.

Then there are the image releases, named with a date and a build counter, the newest `images-2026.10.03.0` published 2026-10-02. Those are the sandbox images, and they carry the guarantee that matters for reproducibility: a dated image you can pin, which a semver tag on a Python package does not give you.

The last push to the default branch was 2026-10-01, and the newest image release was published the day after. So the images are being built from commits that are one day ahead of the branch head, which is the ordinary relationship between a build pipeline and a branch, and is also the reason an image tag is the more useful pin of the two.

The manifest points its changelog link at the releases page of the other repository, so the versions on this page are not where the changelog is.

## Five runtimes, and the macOS one has no Python API

The runtime table is the most informative part of the page, and it has two gaps worth reading closely.

A minimal computer covers commands, code and files, through `Computer()` and `celesto computer`. A browser runtime adds Chromium, the DevTools protocol, screenshots and a live viewer, through `Celesto.browser()` and `celesto browser`. A Linux desktop gives a full desktop and multiple GUI applications, through `Celesto.computer()` and a `--desktop` flag. A Windows computer is for PowerShell and Windows software, through `Celesto(os="windows", ...)` and a `--os windows` flag that also needs a local image path. And a macOS desktop is for app and installer tests on Apple silicon, with a CLI flag and, in the Python API column, nothing at all.

So desktop testing on Apple silicon is a command-line only path in this release, and Windows support means you supply the image yourself rather than getting a curated one.

The two similarly named entry points are also worth internalising: the default `Computer` class is the minimal sandbox, while `Celesto.computer()` is the full Linux desktop. The page tells you to use `Computer` for the common command path, the `Celesto` factories for focused runtimes, and the `Celesto(...)` constructor directly when you need the low-level virtual machine options, naming the backend, the communication channel, the guest operating system, mounts and network policy.

Underneath all five sit three backends, Firecracker, QEMU and libkrun, behind that one interface.

## The automation contract is five JSON fields and one hedge

Commands print readable output by default, and a `--json` flag switches them to something a script or an agent can rely on. The contract is stated exactly: every JSON response contains `ok`, `command`, `exit_code`, `data` and `error`.

That is a small, explicit envelope, and the pre-flight check is the part an agent should call first. `celesto doctor --strict` turns warnings into a failing check, so a machine that is half configured fails rather than proceeding. Commands return a nonzero exit code on failure, which is the other half of the contract.

The hedge is in the error path: JSON errors include a recovery command when Celesto can provide one. So an agent that parses `error` has to cope with a recovery command that is sometimes absent, and a script that assumes it is always there will break on the errors that matter most.

The commands themselves are short enough to take in one block, which is the shape an automation job takes:

```bash
celesto doctor --strict --json
celesto computer create --name agent-job --json
celesto computer exec agent-job --json -- python -m pytest
celesto computer delete agent-job --json
```

Use `celesto config telemetry off` or set `CELESTO_NO_TELEMETRY=1` to switch local usage telemetry off.

The operational advice around the contract is about leaks rather than parsing. Use unique names for concurrent jobs, because sandboxes are looked up by name. Prefer `exec` for automation and reserve `shell`, `ssh` and `desktop` for interactive work. And always delete the sandbox by its exact name when the job ends, with `stop` and `start` for the case where you want to keep the files.

There is a preset for the common case: `celesto codex start` launches a coding agent that already has its CLI installed.

## Telemetry is disclosed carefully, for the local path

The local telemetry disclosure is the best-written paragraph on the page, and it is worth saying so before criticising it.

It states that local CLI and Python SDK usage telemetry displays a notice before sending limited installation and feature counts. It names the processor, noting that PostHog may infer approximate location from the request IP address. It gives two ways to turn it off, a command and an environment variable, and links both the CLI reference section and the privacy policy.

Notice before sending, a named processor, a stated inference about IP geolocation, and two opt-out mechanisms is more than most tools of this size manage, and the scope is stated rather than implied: limited counts, for the local path.

The gap is what the sentence does not cover. Cloud sandboxes run on someone else's machines and the same SDK talks to them, and nothing here describes what the cloud provider path sends. If you are using the cloud provider with a real API key, that is the question to ask before you point a production agent at it.

## A Python SDK over a Rust core, a guest agent, a kernel and a TypeScript UI

The tree is wide for a 0.1.3 alpha, and the shape of it explains most of the design decisions.

The Rust workspace has two members, `celesto-core` and `guest-agent`, on edition 2024 with a minimum toolchain of 1.85. The release profile is tuned hard: optimisation level 3, fat link-time optimisation, a single codegen unit, and symbols stripped. That profile is what you would choose if the guest binary ships inside a sandbox image and start-up time is measured in hundreds of milliseconds, which is the figure the page quotes.

Around the Rust core the repository carries a `kernel/` directory, which is where a microVM guest kernel lives, a `guest-agent/` crate, a `src/` Python package, a `ts/` and `ui/` pair for a TypeScript interface, an `openapi/` directory, and an `open-muse/` directory for the computer coworker that has its own README.

The Python manifest explains the shape too. It depends on a calendar-versioned Rust extension, `celesto-core~=2026.9.22`, so the SDK and its core use two different version schemes, the SDK being 0.1.3.post1. It pulls in `paramiko` for SSH, `pycdlib` for manipulating disk images, and `zstandard`, with a comment in the manifest explaining that it decompresses the zstd-compressed published images and is a pure C extension of roughly 200 KB with no system dependencies.

So the Python package carries a small virtual machine image toolchain with it, which is a defensible choice for a tool whose job is unpacking and booting images, and a real weight for anything that only wanted the client.

## Six agent presets, one of which is a computer that browses the web

The agent side of the product is a set of presets, and the list is longer than the example command suggests.

`celesto codex start` is the documented path for a coding agent whose CLI is already installed. Beyond that, the page names presets for Claude Code, Pi, Hermes, OpenCode and OpenClaw, and points at a guide covering credentials, naming and unattended usage for them. Six named presets, with credential handling documented somewhere other than here, which is the part to read before running any of them unattended.

The example directory backs the claim up in a way the page does not: alongside the quickstart and browser sandbox scripts there are directories for agent tools, a computer-use agent, community work and open-source research, a script for the OpenClaw path, and one for a pull-request review job.

The one preset with its own section is OpenMuse, described as an open-source computer coworker built end to end on the platform. It browses public websites in its own disposable Linux desktop while you watch, approve clicks and form changes, or take control. That approval model is the interesting part, since it is a browser automation product that puts a human in the loop by construction rather than by configuration, and it is a preview, so the repository has to be cloned to run it locally.

## Conclusion

Take SmolVM if you need an agent's code to run in a real virtual machine rather than a subprocess, and you want the same API locally and in a hosted provider, since the provider argument is the only difference between the two paths. Leave it if you need a stable API, because the version is 0.1.3 with an Alpha status, or if you need the release feed to be one scheme, because semver tags and dated image builds share it. Three things to check first: which repository the badges and the docs actually point at, since none of them is this one, whether the runtime you need has a Python API at all, since the macOS desktop row does not, and what the dated image release you pin contains, since the manifest and the image build use two different version schemes.

## FAQ

### What is SmolVM, the repository for Celesto?

A sandbox that gives an AI agent its own computer. Each sandbox is a lightweight virtual machine that starts in about 500 ms and keeps files and state between sessions, and it runs locally through the CLI and Python SDK or in Celesto Cloud. The repository is SmolVM while the package, CLI and docs are all named celesto.

### How do I install the Celesto sandbox?

On Linux or macOS, `curl -fsSL https://celesto.ai/install.sh | bash` installs the CLI and SDK, prepares the machine and checks it. Manually, install with Python 3.11 or newer using `pip install celesto`, then run `celesto setup` and `celesto doctor`. On macOS setup installs QEMU through Homebrew, and on Linux it may ask for sudo.

### Which hypervisors does the Celesto sandbox support?

Firecracker, QEMU and libkrun, behind one API. The local provider needs a virtualization setup on your machine, while the cloud provider needs only the Python package and a CELESTO_API_KEY, since cloud sandboxes do not require virtualization software locally.

### Can the sandbox run Windows or a macOS desktop?

Both are listed as runtimes. A Windows computer is created with `Celesto(os="windows", ...)` and a `--os windows` flag that also takes a local image path. A macOS desktop, for app and installer tests on Apple silicon, is CLI only: `celesto computer create --os macos`, with no Python API entry in the runtime table.

### Does the Celesto CLI send telemetry?

Local CLI and Python SDK usage does, after a notice is displayed, and it sends limited installation and feature counts, with PostHog potentially inferring approximate location from the request IP. Turn it off with `celesto config telemetry off` or by setting CELESTO_NO_TELEMETRY=1.

### What does the JSON output from a Celesto command contain?

Every JSON response includes ok, command, exit_code, data and error. Commands return a nonzero exit code on failure, and JSON errors include a recovery command when Celesto can provide one, so a script cannot assume that field is always present.

## Sources

- [CelestoAI/SmolVM on GitHub](https://github.com/CelestoAI/SmolVM)
- [License: Apache-2.0](https://github.com/CelestoAI/SmolVM/blob/main/LICENSE)
- [Project website](https://docs.celesto.ai/smolvm)
- [README](https://github.com/CelestoAI/SmolVM/blob/main/README.md)
- [Releases](https://github.com/CelestoAI/SmolVM/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/celestoai-smolvm