Unikraft Sandbox

Runs tasks inside a per-session Unikraft Cloud (UKC) sandbox VM. One sandbox per session.

Full API shapes: see references/ukc_api.md.

Prerequisites

Check that these env vars are set before proceeding. They are inherited by all child processes (scripts, curl calls) automatically — no injection needed.

• UKC_TOKEN, UKC_METRO, UKC_USER, UKC_SANDBOX_IMAGE

If any are missing, stop and ask the user to export them.

Session State

Hold these in memory for the duration of the session:

• sandbox_name — generated name (also the tmp dir name under /tmp/)
• session_dir — local directory to sync with the sandbox (task-specific)

The FQDN is persisted to /tmp//fqdn by create-sandbox.sh and read from there by other scripts — no need to track it separately in memory.

Lifecycle

1. Create sandbox

Generate a name: sandbox-- (lowercase, hyphens only, valid as a directory name). Store as sandbox_name.

bash scripts/create-sandbox.sh <sandbox-name>

Capture stdout as sandbox_fqdn. The script:

• Checks if a sandbox with that name already exists — exits with an error if so
• Creates /tmp// with the SSH keypair inside
• Creates the UKC instance (passing the pubkey)
• Prints the instance FQDN

2. Sync local → sandbox (before a task)

bash scripts/sync-to-sandbox.sh <sandbox-name> <session-dir>

> ⚠️ Destructive sync: sync-to-sandbox.sh uses --delete, meaning any files present in /workspace on the sandbox that don't exist locally will be deleted. Do not manually create files in /workspace that you want to keep — they will be wiped on the next sync.

3. Execute commands

Prefer the exec API for most commands:

node scripts/exec-sandbox.js "$(cat /tmp/<sandbox-name>/fqdn)" "cd /workspace && <your command>"

Check exit code. Non-zero means the command failed. See references/ukc_api.md for response shape.

Use SSH directly only for interactive/PTY needs:

ssh -i /tmp/<sandbox-name>/id_ed25519 \
  -o StrictHostKeyChecking=no \
  -o ProxyCommand="openssl s_client -quiet -connect $(cat /tmp/<sandbox-name>/fqdn):2222 2>/dev/null" \
  root@"$(cat /tmp/<sandbox-name>/fqdn)"

4. Sync sandbox → local (after a task)

bash scripts/sync-from-sandbox.sh <sandbox-name> <session-dir>

5. Delete sandbox

When the session ends or the sandbox is no longer needed:

bash scripts/delete-sandbox.sh <sandbox-name>

This removes the UKC instance and the local /tmp// directory (including SSH keys).

Error Handling