Getting started

Alpha

The API, CLI, SDK and image format may change between 0.x releases. Pin a version (KUMOBA_VERSION=0.2.2) for anything you depend on.

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.

Getting started ​

Next steps ​

Getting started

Next steps