For agents and programs
Read this when an agent or a script should run commands in a machine. There are two ways in:
- From the command line: a native instance takes jobs on the guest's root shell,
whatever its app is, through
shandcp, forks or MCP. A run can be bounded, stopped from outside and recorded (limits and logs). - In a browser tab: the agent page puts several machines in one page, for an agent to drive over WebMCP or a script.
For many machines at once, read Orchestration and fleets.
Commands and files: sh and cp
Pass the command to snowglobe sh as one quoted argument. Otherwise its flags would be read
as snowglobe's own.
snowglobe run dist/python --name box --detach --runtime native snowglobe sh box 'python3 -c "print(6*7)"' # its output, and its exit status as ours snowglobe sh box --json 'ls /nope' snowglobe cp ./project box:/root/project # files and directories, either way snowglobe cp box:/root/project/out ./out
- Each command runs with the app's environment, starting in the home directory as it would in the machine's terminal, so relative paths work.
- Files persist for the instance's life.
$EXCLAVE_WORKSPACEnames a fresh scratch directory of the command's own. - Out of time (300 s, or
--timeout S), the command and everything it started are killed (exit 124). - What the guest sends back through
cpcan't write outside the destination.
A fresh machine per command: --fork
--fork makes a detached native instance a template. It restores once. Every
snowglobe sh on it runs in a copy of that machine, forked in milliseconds and sharing its
memory.
Nothing one command does is seen by the next, so sh is all a fork instance takes.
cp, exec, attach and mcp need a machine that lasts.
snowglobe run dist/python --name tpl --detach --runtime native --fork
snowglobe sh tpl 'python3 untrusted.py' # many at once, each on its own copy
snowglobe stop tpl
MCP
snowglobe mcp <site> serves a site to an agent as an MCP server over stdio: an isolated
Linux machine with run_command, write_file and read_file tools. It
starts a native instance and stops it when the agent goes (--keep leaves it).
claude mcp add sandbox -- snowglobe mcp https://filipecabaco.github.io/snowglobe/python/
snowglobe mcp --daemon serves the daemon instead.
Through it an agent can:
- list, build and add templates;
- run commands on fresh forks or on machines it brings up, and write and read their files;
- submit fire-and-forget runs and read their results;
- save snapshots, put services behind ports, and list and check ports;
- diff and apply fleet files;
- read the daemon's status and events.
SNOWGLOBE_DAEMON points it at a daemon on another host.
claude mcp add snowglobe -- snowglobe mcp --daemon
Limits, stopping and logs
| Flag | What it does | Exit |
|---|---|---|
--max-runtime 30m | ends the run after this long, whatever it is doing | 124 |
--stop-file PATH | ends the run once PATH exists: create it from anywhere | 143 |
--log-dir DIR | durable console.log, serial.log and events.jsonl |
Either way the job running in the guest is killed first, and a stop event saying why goes to
the log.
Logs are appended as things happen, so they survive a crash of the run. They rotate at 8 MiB. A named
native instance logs to snowglobe/logs/<name> in your cache directory unless
--log-dir says otherwise.
console.log: the app's terminal, byte for byte.serial.log: the guest's serial line, with the kernel's own messages (an OOM kill, a panic) and the job shell.events.jsonl: one JSON object a line, each synced to disk:startandrestored;job_start: the command, its environment variables' names but never their values, and the timeout;job_end: status,timed_out,killed, milliseconds, and the first 64 KiB of output;stop: itsreason(stop-file,max-runtime,guest-stoppedorend) and the exit status.
Kills reach everything a job started. A job runs in a session of its own in the guest.
When it runs out of time or the instance stops, it gets TERM, then KILL after 3 s, including whatever it
put in the background. A process that makes a session of its own (a daemon that setsids) is
out of reach, as it would be anywhere.
A job's result is its own word. A job's exit status comes back on a line marked with a one-time value. The host types that value only to the job's launcher, so a job that merely prints a fake result isn't believed.
A job runs as root in the guest, though. One determined to can still read that value from the
launcher's memory and forge its own status, output and out/ files. That reaches only its own
result. The host still enforces the time limit. If a job leaves the guest's shell busy, later jobs fail
with "the guest's shell is not answering" rather than run inside it.
In the page: --agent, /agent/ and WebMCP
The agent page is one page with several machines in it, each a site built with --agent. An
agent runs commands in any of them and copies files between them, in the visitor's own tab. Nothing runs
on a server, and the page is static files. This site's agent page is /agent/.
Agents can run commands in the page's machines straight away: nobody is asked first. Only two of the person's own buttons confirm: Start fresh…, which deletes a machine's saved state, and Revert to starter….
Build a machine for it with --agent (or the label snowglobe.agent="true"). It is
off unless asked for. A site on several CPUs is a machine there too: the page's service worker makes it
cross-origin isolated, as such a site's own page is. These labels describe the machine on the page:
| Label | What it does |
|---|---|
snowglobe.agent-purpose | what the machine is good for, in a line |
snowglobe.agent-sample | a command to try |
snowglobe.agent-watch | a project directory, such as /root/app: the page shows which files in it each command changed, with their diffs |
snowglobe.agent-name | the machine's name on the page, when its directory has another name. The page's Python is built from examples/python-agent (a network, for pip install) and is still python; examples/python is the page for people, with no network |
Then put the agent sites on the page:
snowglobe build examples/duckdb --agent --out dist/duckdb
snowglobe pool dist; snowglobe pwa dist/duckdb
snowglobe agent-pages dist # dist/agent/runtimes.json, the page's scripts and service worker
snowglobe agent-pages lists the agent sites under a directory in
agent/runtimes.json (from each site's run.json, read when the site is
assembled) and writes the page's scripts beside it.
Each site's own page links to the agent page: For agents, in its title strip, with
?runtime=<site>, which only preselects. An address ending #agent goes there
too. ChatGPT's agent uses the page today; its WebMCP (site tools) works only in the ChatGPT desktop app's
built-in browser. A prompt to give an agent:
Open https://filipecabaco.github.io/snowglobe/agent/, choose python under Runtime, type python3 -c 'print(6*7)' into Shell command, press Run, and tell me the exit status and output.
The page is for agents that build and compute:
- Supabase (on two CPUs) and a React app on it, built with Vite and rebuilt as it changes (see the app studio);
- Python with numpy and pandas, and
pip install, which fetches wheels from PyPI through your browser; - DuckDB for analytics, and PostgreSQL for databases;
- Bun on 160 MB: JavaScript and TypeScript run as they are, a web server (
Bun.serve), fetch and WebSocket, no build step. The fleet page's example runs its viewer there.
The other runs are on the landing page, for people.
Each machine runs in a Web Worker of its own, so several run on several cores and the page stays responsive. The page's service worker makes it cross-origin isolated (Supabase's two CPUs share memory between workers, which needs that) and carries the preview. The first visit reloads once to be loaded through it. The page needs the network: it doesn't work offline. In another page's frame, it refuses to run and registers no tools.
Machines awake and asleep
A machine starts lazily, on its first command. Each one awake holds 540 to 740 MB, so only a few are awake at once.
- The limit is two awake machines unless the field Machines awake at
once, the tool
set_awake_limitorsetAwakeLimit(count)changes it: 1 to 8, for the page load. - Waking another suspends the least recently used idle one first, one capture or boot at a time.
- A busy machine, with a job, a copy or an open preview in it, is never suspended. A wake waits for one to finish, and says so.
- A lower limit suspends idle machines, least recently used first, and busy ones as they finish.
- An idle machine doesn't stay in memory either. With no job for 5 minutes, or with its tab hidden for a minute, it is suspended, its state saved and its worker ended, so the browser takes back its memory. The next command, or a key typed into its terminal, wakes it, files and all, and then runs. The terminal pages keep their machine running.
Suspended, a machine's state is saved in this browser (IndexedDB, a scope per runtime). Only a suspended machine's state is kept. A reload loses what an awake one did since its last suspend, and the browser asks before leaving. Start fresh… goes back to the machine as built, always after asking.
A machine that fails (it powered off, its worker crashed, a capture hung) is ended at once, and its job fails. Retry starts it again. When its files can't be fetched, the page says so.
WebMCP tools
Where the browser has WebMCP (document.modelContext), the page registers one set of tools.
Any WebMCP client can use them: a browser's built-in agent, an extension, a chat page. A client added
after the page starts, by an extension or a polyfill such as MCP-B's @mcp-b/global, is still
found for 15 seconds. The first drafts' provideContext works too.
| Tool | What it does |
|---|---|
list_runtimes | each machine: its runtime name, what it is for, its state (asleep, waking, awake, busy, suspending, failed) and a sample command |
run_command | starts command in runtime and returns its job id at once; timeout_seconds (default 300, at most 3600) and request_id (a retry returns the same job) are optional |
job_status | the job's output so far, ending [running], or as snowglobe mcp's ends: [exit N], [timed out], [stopped] |
cancel_job | stops the job: its command and everything it started are killed |
write_file | writes content (UTF-8 text, at most 1 MiB) at path in runtime, its directory made, with no shell quoting; returns once it is written, with the files it changed in a watched project |
list_files | a directory's files as an indented tree with sizes (default: the machine's watched project, web's /root/app); node_modules, dist and .git are listed, not entered |
read_file | the text of path, or of up to 20 paths in one call: 256 KiB of each at most (640 KiB in all), saying when it cut one; binary files are said, not shown |
write_files | several files at once (files: [{path, content}], 1 MiB in all), with move and delete, in one job: written to temporary names, then moved into place together, so web rebuilds once; it waits for that build and returns it: ok, or the compiler's error |
revert_changes | takes a watched project back: to: "previous" undoes the last change (the last 20 are kept), to: "start" goes back to how it began (itself undoable) |
build_status | how web's last build went: {version, state, error, ms, at} from its /__build |
run_sql | SQL on Supabase's Postgres (or runtime: "postgres") through psql with ON_ERROR_STOP, as a file of the job's (no quoting); then the Data API reloads its schema |
copy_file | copies from_path in from_runtime to to_path in to_runtime: any file up to 8 MiB, checked by sha256 on both ends; a client's cancel signal stops it |
open_preview | opens the page's preview on a web server in a machine: runtime, port and an optional path; returns the preview's address and what its first request got |
preview_snapshot | what the open preview shows, read from its page: address and title, an outline of its landmarks, headings and controls (labels, values, checked or not), each control with a ref like e3, its visible text, what it logged since it loaded (console errors and warnings, uncaught errors, rejected promises, failed requests) and whether it shows web's latest build; maxChars bounds it (default 12000) |
preview_interact | runs actions in the preview's page, in order, with real DOM events: click, type (value; React sees it), press (key), select, check, scroll, wait_for (text or a ref, gone, timeoutMs), each aimed by a ref from the last snapshot, a selector, or a control's label; stops at the first that fails and returns a fresh snapshot |
close_preview | closes it: the machines it kept awake can be suspended again |
set_awake_limit | how many machines may be awake at once, count 1 to 8 (2 by default), for the page load; list_runtimes reports it as awake_limit |
The tools are the page's own. --agent-exposed-to https://host (repeatable) shares them with
other origins too, when every machine of the page shares with that origin.
From a script: window.snowglobeAgent
Scripts on the page can use the same thing as window.snowglobeAgent:
- Jobs:
listRuntimes(),status(runtime),runCommand({runtime, command, timeoutSeconds, requestId}),readJob(jobId),cancelJob(jobId). - Files:
writeFile({runtime, path, content}),writeFiles({runtime, files, move, delete}),readFiles({runtime, paths}),listFiles({runtime, path, depth}),revert({runtime, to}),copyFile({fromRuntime, fromPath, toRuntime, toPath}). - Apps:
runSql({sql, runtime}),buildStatus({runtime, port}),openPreview({runtime, port, path}),closePreview(),previewSnapshot({maxChars}),previewInteract({actions, maxChars}). - Machines:
suspend(runtime),wake(runtime),startFresh(runtime),setAwakeLimit(count),unsaved().
How jobs and copies run on the page
- Jobs run as root on the guest's serial shell, beside the app, as
snowglobe sh's do. The terminal never shows them. - Each job starts in
/root, so relative paths work, and files persist between jobs. - One job runs at a time in each machine. A machine's operations go in the order asked: a run asked during a copy waits for it.
- A job's output keeps its most recent 1 MiB and says when it dropped some. Jobs run with
NO_COLOR=1andTERM=dumb, and their output reads as plain text. - Copies travel over the same serial line, as base64 in slices of a job each, so they are slow (tens of KiB a second). The target is replaced only once its sha256 checks out.
- What agents run and copy, by a tool or a script, shows under Earlier runs too.
The preview: a machine's web server, in the page
A web server in a machine shows in a frame of the page. Open it with Open preview
(runtime, port, path) or open_preview. Its address is
/snowglobe/agent/preview/<runtime>/<port>/<path>.
How a request gets there: the page's service worker hands it to the agent page. The agent page opens a TCP connection to the port on the machine's network address, writes the request as HTTP/1.1 and streams the answer back. A page in the frame can also open WebSockets to the same address (up to 32).
- A server must listen on
0.0.0.0, notlocalhost. - Pages need relative asset paths (Vite's
base: "./"). - The page in the frame is this site's own, so it reaches every machine's server the same way.
Supabase's API is
/snowglobe/agent/preview/supabase/54321, the URL to give supabase-js. - While a preview is open, its machine and every machine its page reaches stay awake.
- Nothing is answered unless a preview is open. A preview address opened from anywhere but the page is refused.
- The service worker puts one script first in each HTML page the preview shows
(
preview-hook.js). It passes what the page logs, its uncaught errors and its failed requests to the agent page, whichpreview_snapshotreports beside the page's outline.
The app studio: a React app on Supabase
The top of the page is a studio, laid out as AI app builders are. The page has no AI of its own: Connect an agent gives a prompt to paste into yours.
- The preview fills it, at desktop, tablet or phone width, with its address, Reload and New tab. A failed build's error shows over it.
- Code and Database sit beside it as tabs: the app's files, read from the machine as they change, with each one's last change; and Supabase's tables.
- The agent's steps run down its left side as a conversation: every file it edited (with the diff), command it ran, file it read, SQL it ran and build. Undo last change and Revert to starter… are there too.
The machines, with every control above, are below the studio.
The two machines come ready and connected, and the app starts empty, so the agent builds it from nothing:
- web has a blank React project in
/root/app: an empty page, with supabase-js set up insrc/supabase.js.serve --watchbuilds it, serves it on port 4173 and builds again on every change. - supabase has no tables of the app's yet.
The preview reloads without Vite's hot reload, which has not been tried over its WebSockets: while it is
open the page reads the server's /__build and reloads after each new build.
The app is React 19 with Vite, Tailwind v4 and TypeScript, with React Router, Zustand and clsx installed.
It has a tsconfig.json: .ts and .tsx build as they are, and
npm run typecheck runs tsc.
npm install works too, slowly. In the tab, every request the machine makes is the page's own
fetch(). The npm registry allows that for plain GETs but answers no CORS preflight, which
npm's own headers would need. So the machine's npm goes through a relay in serve
(127.0.0.1:4874) that asks the registry with nothing but Accept.
A session, step by step:
open_preview {runtime: "web", port: 4173}: the app, signed up and used in the page
list_files {runtime: "web"}, read_file {runtime: "web", paths: ["src/App.jsx", "src/styles.css"]}
write_files {runtime: "web", files: [{path: "/root/app/src/components/Todo.tsx", content: ...}, ...]}: the diffs show, web rebuilds, the preview reloads, the build's result comes back
preview_snapshot {}: the page as built, its controls with refs, and any runtime errors
preview_interact {actions: [{type: "type", ref: "e2", value: "Buy milk"}, {type: "click", ref: "e3"}]}: used as a person would, then seen again
run_sql {sql: "create table public.todos (...); alter table public.todos enable row level security; ..."}: the Data API sees it at once
On supabase: psql "$DB_URL" -c "select * from todos" shows what you added, with your user's id
The whole recipe is in llms.txt.
What it costs: opening the app starts web, and supabase once the app uses it. That is up to about
1.4 GB of the tab's memory, and seconds to a minute the first time. Builds and npm install
run in the emulated machine, so a rebuild takes seconds and an install of one package most of a
minute.