Copy page

Sandboxes

Configuration

Sandbox.create(spec, options) takes two arguments. The first says what the sandbox is. The second says how the call reaches it, and how long the call waits.

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

const sandbox = await Sandbox.create(
  {
    image: "nginx:latest",
    memory_mb: 1024,
    env: { LOG_LEVEL: "debug" },
  },
  {
    token: process.env.UKC_TOKEN,
    metro: "fra",
    bootTimeoutSeconds: 60,
  },
);

What the sandbox is

The first argument accepts the fields that POST /instances accepts, except autostart, timeout_s, wait_timeout_ms, and replicas. It also accepts two fields for the plugin. These are the fields with a sandbox default:

Field	Default	Description
image	debian-slim:latest	The instance image. UKC_SANDBOX_IMAGE replaces the default.
memory_mb	2048	The memory of the instance.
autokill	300000	The time in milliseconds that the platform keeps a stopped instance before it deletes it.
rom	plugins/sandbox:latest	The plugin ROM. Shorthand for one entry in plugins.
pluginName	sandbox	The plugin name, which is also its path segment.

An image for a sandbox must carry a shell and a main process that stays alive. The SDK sets autostart and timeout_s for you, because a plugin can't answer in a stopped instance. It excludes wait_timeout_ms and replicas, because a Sandbox addresses exactly one instance. If you pass one of these four fields, create throws an error of kind "config".

How the call behaves

Option	Default	Description
token	UKC_TOKEN	The bearer token.
metro	UKC_METRO	The metro of the sandbox, as a code or as a full http(s):// address.
client		An existing UnikraftCloud client to borrow, instead of a new one.
bootTimeoutSeconds	30	How long the call waits for the instance to reach running. Raise it for a large image.
ready	{}	How to wait for the plugin to answer, or false to return as soon as the instance exists.
signal		An AbortSignal that cancels the call.

Every option of the client constructor is also accepted, because Sandbox.create() builds a client from them.

create waits for the plugin by default, and gives up after 60 seconds. If the wait fails, create deletes the instance it made, so a broken sandbox doesn't linger. To wait longer, or to keep a failed sandbox for inspection:

Code
await Sandbox.create({}, { ready: { timeoutMs: 120_000 } });
await Sandbox.create({}, { ready: false });

Through a client

ukc.metro("fra").sandboxes.create(spec, options) takes the same first argument. Its options exclude token, metro, client, and the other client fields, because the call runs through the client that you reached it from.

Code
const sandbox = await ukc.metro("fra").sandboxes.create(
  { image: "nginx:latest", memory_mb: 1024 },
  { bootTimeoutSeconds: 60 },
);

Create from a snapshot

A template, a branch_from source, or a checkpoint replaces the image. The snapshot carries the image, the memory, and the plugins of its source, so the sandbox plugin comes with it.

Code
await using sandbox = await Sandbox.create({ template: { name: "my-template" } });

For a snapshot, the SDK applies no default image, memory, or plugin entry. Leave rom out, and pass pluginName only when the source attached the plugin under another name. See on-demand templates, branching, and checkpoints.

Your own plugin

A sandbox can run a plugin that you built with the plugin SDK, as long as it speaks the sandbox API. Name its ROM in rom:

Code
const sandbox = await Sandbox.create({
  image: "my-org/sandbox-base:latest",
  rom: "my-org/my-plugin:latest",
});

To give the plugin a config, attach it in plugins yourself, and omit rom.

Reference

Every field and option has a type. See SandboxSpec and SandboxCallOptions in the source for the complete list.