snowglobe

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 sh and cp, 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_WORKSPACE names 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 cp can'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

FlagWhat it doesExit
--max-runtime 30mends the run after this long, whatever it is doing124
--stop-file PATHends the run once PATH exists: create it from anywhere143
--log-dir DIRdurable 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:
    • start and restored;
    • 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: its reason (stop-file, max-runtime, guest-stopped or end) 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:

LabelWhat it does
snowglobe.agent-purposewhat the machine is good for, in a line
snowglobe.agent-samplea command to try
snowglobe.agent-watcha project directory, such as /root/app: the page shows which files in it each command changed, with their diffs
snowglobe.agent-namethe 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_limit or setAwakeLimit(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.

ToolWhat it does
list_runtimeseach machine: its runtime name, what it is for, its state (asleep, waking, awake, busy, suspending, failed) and a sample command
run_commandstarts 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_statusthe job's output so far, ending [running], or as snowglobe mcp's ends: [exit N], [timed out], [stopped]
cancel_jobstops the job: its command and everything it started are killed
write_filewrites 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_filesa 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_filethe 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_filesseveral 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_changestakes 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_statushow web's last build went: {version, state, error, ms, at} from its /__build
run_sqlSQL 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_filecopies 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_previewopens 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_snapshotwhat 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_interactruns 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_previewcloses it: the machines it kept awake can be suspended again
set_awake_limithow 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=1 and TERM=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, not localhost.
  • 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, which preview_snapshot reports 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 in src/supabase.js. serve --watch builds 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.