@unikernelai/sandbox-cli

Command-line interface for the Unikernel AI Sandbox — unikernel-isolated code execution with sub-second cold starts.

npm i -g @unikernelai/sandbox-cli

Quick Start

# 1. Get an API key (opens browser)
unik auth login

# 2. Run code instantly (stateless — no sandbox)
unik run nodejs "console.log('Hello from a unikernel!')"
unik run python "print(2 ** 128)"
unik run shell  "uname -a && df -h"

# 3. One-shot sandbox (create + exec in 1 command)
unik sandbox run python "import sys; print(sys.version)"

# 4. Persistent sandbox (15 min TTL)
ID=$(unik sandbox create -q)        # -q = raw ID, no JSON
unik sandbox exec $ID nodejs "require('fs').writeFileSync('/tmp/x.json', '{\"v\":1}')"
unik sandbox exec @last shell "cat /tmp/x.json"   # @last reuses the most recent sandbox
unik sandbox delete @last

Authentication

# Browser login — provisions a free-tier key automatically
unik auth login

# Headless login — for CI/CD and agents
unik auth login --headless

# Manual key setup
unik auth set-key uk_live_abc123...

# Check stored credentials
unik auth whoami

# Clear credentials
unik auth logout

Credentials are stored in ~/.unik/config.json.

Commands

unik run <language> [code]

Stateless one-shot execution. No sandbox session — fastest path.

unik run nodejs "JSON.stringify({a:1,b:2})"
unik run python "import json; print(json.dumps({'hello': 'world'}))"
unik run shell "curl -s https://httpbin.org/ip"

# Read code from a local file
unik run python --file ./script.py

# Read code from stdin
echo 'print("from stdin")' | unik run python

# Custom timeout (max 8000ms)
unik run nodejs "while(true){}" --timeout 2000

Languages: python, nodejs, shell

unik sandbox run <language> [code] ⭐

The agent primitive. Creates a sandbox, executes code, and returns the result — all in one command, one network round-trip.

# Basic usage
unik sandbox run python "print('hello world')"

# From a local file
unik sandbox run nodejs --file ./app.js

# Auto-cleanup after execution
unik sandbox run python "print('ephemeral')" --rm

# Quiet mode — only stdout/stderr, no metadata
unik sandbox run shell "date" --quiet

# The sandbox is kept alive by default — run more code in it:
unik sandbox exec @last python "print('still here')"

unik sandbox create

Create a persistent sandbox session with a 15-minute TTL.

# Default: prints JSON in pipe mode, raw ID in interactive mode
unik sandbox create

# -q/--quiet: always output only the raw ID (best for scripting)
ID=$(unik sandbox create -q)
echo $ID   # sbx_a1b2c3d4...

unik sandbox exec <id> <language> [code]

Execute code inside an existing sandbox. Files and state persist between calls. Use @last (or just last) instead of an ID to reuse the most recently created sandbox.

unik sandbox exec $ID nodejs "require('fs').writeFileSync('/tmp/data.json', JSON.stringify({count: 42}))"
unik sandbox exec $ID python "import json; print(json.load(open('/tmp/data.json')))"

# Use @last to skip tracking IDs
unik sandbox exec @last shell "ls -la /tmp/"

# From a local file
unik sandbox exec @last python --file ./analyze.py

unik sandbox upload <id> <remote-path>

Upload a file to a sandbox. Use @last as the ID.

# From local file
unik sandbox upload @last /workspace/app.py -f ./app.py

# From stdin
echo "console.log('hi')" | unik sandbox upload @last /workspace/index.js

unik sandbox ls <id> [path]

List files in a sandbox.

unik sandbox ls @last
unik sandbox ls @last /workspace

unik sandbox delete <id>

Delete a sandbox. Supports --dry-run for safe preview.

unik sandbox delete @last
unik sandbox delete @last --dry-run

unik keys create

Create a new API key. Saved to ~/.unik/config.json by default.

unik keys create
unik keys create --label "ci-pipeline" --expires "2025-12-31T23:59:59Z"
unik keys create --no-save   # Print only, don't persist

unik keys list

List all API keys associated with your account.

unik keys revoke <id>

Revoke an API key. Supports --dry-run.

unik status

Check server health and component status.

unik status
# Status: ready
#   ✓ cloud
#   ✓ database

unik mcp

Run as an MCP (Model Context Protocol) server over stdio. Proxies JSON-RPC to the Unikernel AI sandbox backend.

Add to your MCP client config:

{
  "mcpServers": {
    "unikernel-sandbox": {
      "command": "unik",
      "args": ["mcp"]
    }
  }
}

unik schema

Output a machine-readable JSON schema of all commands — useful for AI agents to discover capabilities.

Agent & CI/CD Usage

The CLI automatically detects non-TTY environments (piped output, CI, AI agents) and switches to structured JSON output on stdout. Errors go to stderr as { ok: false, error: "..." }.

# Agent mode is automatic when stdout is not a TTY
RESULT=$(unik run nodejs "1+1" 2>/dev/null)
echo $RESULT
# {"ok":true,"status":"success","stdout":"2\n","stderr":"","execution_time_ms":3}

# Force JSON in interactive mode
unik run nodejs "1+1" --json

Agent Onboarding (3 commands)

npm i -g @unikernelai/sandbox-cli
unik auth login --headless
unik sandbox run nodejs "console.log('ready')" --rm

That's it. An AI agent goes from zero to executing code in an isolated unikernel in 3 commands.

Agent Onboarding (1 compound command)

npm i -g @unikernelai/sandbox-cli && unik auth login --headless && unik sandbox run python "print('ready')" --rm

Using as an MCP Server

{
  "mcpServers": {
    "sandbox": {
      "command": "unik",
      "args": ["mcp"]
    }
  }
}

This gives any MCP-compatible AI agent (Claude, Cursor, Windsurf, etc.) access to:

• Execute code in Python, Node.js, or shell
• Create and manage persistent sandboxes
• Upload/download files
• Manage dependencies

Configuration

| File | Purpose | |------|---------| | ~/.unik/config.json | API key, JWT, base URL | | ~/.unik/state.json | Last sandbox ID (for @last) |

{
  "api_key": "uk_live_...",
  "base_url": "https://sandbox.unikernel.ai"
}

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | Error (execution failed, auth error, network error) |

Limits

| Limit | Value | |-------|-------| | Execution timeout | 8,000 ms max | | Free tier rate limit | 2,000 req/min | | Free tier daily limit | 50,000 req/day | | Sandbox TTL | 15 minutes |

Links

• Website: unikernel.ai
• SDK: @unikernelai/sandbox
• API Endpoint: https://sandbox.unikernel.ai

License

MIT