kumoba

Fast sandboxes for AI agents. Each sandbox is a real VM that boots in under a second, on your laptop, your servers or your cloud.

Documentation · 日本語 · Changelog

Alpha. Every release is installed and tested on real VMs, but the API, CLI and image format may change between 0.x releases.

• Fast. Create, boot, run and delete in about half a second on an Apple silicon Mac.
• Real VMs. Each sandbox has its own kernel, not a shared one.
• Built for agents. A CLI and SDKs where every command has a JSON Schema and returns the guest's exit code.
• Safe by default. Egress allowlists, secrets that never enter the VM, a log of every connection.
• Live desktop. Watch and drive a full desktop from your browser.
• Runs anywhere. Your laptop, your servers, your cloud. Apache-2.0.

Getting started

1. Install. On macOS, install libkrun first: brew tap slp/krun && brew install slp/krun/libkrun slp/krun/libkrunfw zstd. On Linux you need /dev/kvm and zstd.

curl -fsSL https://raw.githubusercontent.com/Parassharmaa/kumoba/main/scripts/install.sh | bash
export PATH="$HOME/.kumoba/bin:$PATH"     # add this to your shell profile

The installer puts the kumobad daemon, the kumoba CLI and the default image (Debian with Python, Node, Chromium and a desktop) in ~/.kumoba.

2. Start the daemon. It needs no configuration:

kumobad

Stop it with Ctrl-C. Sandboxes keep their disks across restarts.

3. Run something. In another terminal:

kumoba run -- python3 -c 'import platform; print(platform.platform())'

id=$(kumoba create --image default -q)       # a sandbox that stays around
kumoba start "$id" -q
kumoba exec "$id" -- pip install requests
echo 'print("hi")' | kumoba write-file "$id" --path /workspace/hi.py
kumoba exec "$id" --cwd /workspace -- python3 hi.py
kumoba shell "$id"                           # a terminal inside the sandbox; exit to leave
kumoba desktop "$id" --user kumoba --open    # the desktop, live in your browser
kumoba delete "$id"

Run kumoba to list every command, and kumoba <command> --help for its options.

4. Use it from code.

npm install kumoba

import { Kumoba } from "kumoba";

const kumoba = new Kumoba();

const once = await kumoba.run("python3 --version");     // fresh VM, deleted afterwards
console.log(once.stdout);

const sandbox = await kumoba.create({ user: "kumoba" });
await sandbox.files.write("/workspace/a.txt", "hello");
console.log((await sandbox.run("cat /workspace/a.txt")).stdout);
await sandbox.delete();

new Kumoba() finds the daemon by itself.

Learn more

License

Apache-2.0. libkrun is Apache-2.0; libkrunfw ships a GPL-2.0 Linux kernel. See NOTICE.