Copy page

Sandboxes

Sandboxes

A sandbox is an instance with the sandbox plugin attached: a microVM that runs the commands you give it, and that you move files in and out of. The Sandbox class wraps the plugin, so you write none of that by hand.

Your first sandbox

Code
import { Sandbox } from "@unikraft/cloud";

await using sandbox = await Sandbox.create();

const { stdout } = await sandbox.exec("echo hello");
console.log(stdout); // hello

Sandbox.create() reads the token from UKC_TOKEN. With nothing else set, it boots debian-slim:latest with 2 GiB of memory in the default metro. Configuration lists what you can change.

await using deletes the sandbox when the scope ends, even if the scope throws. It needs TypeScript 5.2 or newer, or a runtime with explicit resource management. Without it, call sandbox.delete() yourself.

Write a file and run it

Write a script into the sandbox, run it, and check the exit code before you trust the output:

Code
import { Sandbox } from "@unikraft/cloud";

await using sandbox = await Sandbox.create();

await sandbox.writeFile("/work/hello.sh", "echo hello from $(uname -m)\n");
const result = await sandbox.exec("sh /work/hello.sh");

if (result.exitcode !== 0) throw new Error(result.stderr);
console.log(result.stdout); // hello from x86_64

The instance underneath

A sandbox is a real instance, so the whole platform API still applies to it. sandbox.instance is a handle on that instance:

Code
const { name, state, memory_mb } = await sandbox.instance;
console.log(`${name} in ${sandbox.metro}: ${state}, ${memory_mb} MiB`);

await sandbox.instance.update({ memory_mb: 4096 });

sandbox.uuid and sandbox.metro identify the instance. sandbox.api is the raw plugin API, pinned to this sandbox.

Two ways in

Sandbox.create() builds its own client from the options you give it. A client that you already hold opens the same door through ukc.metro("fra").sandboxes, and spends no second token:

Code
import { UnikraftCloud } from "@unikraft/cloud";

const ukc = new UnikraftCloud({ token: process.env.UKC_TOKEN });
const sandbox = await ukc.metro("fra").sandboxes.create({ memory_mb: 512 });

console.log((await sandbox.exec("uname -a")).stdout);
await sandbox.delete();

sandboxes belongs to a metro client, not to ukc, because a sandbox lives in exactly one metro.

Next steps

• Configuration: the image, the memory, the metro, snapshots, and your own plugin.
• Commands: run a command to completion, or start one and control it.
• Files: read, write, and upload files.
• Existing sandboxes: reconnect from another process, and list sandboxes.
• examples/sandbox.ts: a complete program.
• Sandboxes: what the platform underneath gives a sandbox.