Sandbox SDK

Stridekit Sandbox SDK - Client library for interacting with Stridekit VM Agent via orchestrator.

Installation

npm install @stridekit/sandbox
# or
pnpm add @stridekit/sandbox

Quick Start

import { Sandbox } from '@stridekit/sandbox';

// Set API key via environment variable
// export STRIDEKIT_API_KEY="your-api-key"

// Create a new sandbox VM — resolves only once the VM is running
const sandbox = await Sandbox.create();

// Run a command
const result = await sandbox.commands.run({
  cmd: 'echo "Hello from Stridekit!"',
});

console.log(result.stdout); // "Hello from Stridekit!"

// Clean up
await sandbox.terminate();

Authentication

Generate an API key at app.stridekit.ai/orgs/{your-org}/api-keys.

The SDK supports multiple authentication methods.

Quick Overview

// 1. Environment variable (recommended)
// export STRIDEKIT_API_KEY="your-api-key"
const sandbox = await Sandbox.create();

// 2. Static configuration
Sandbox.config({ apiKey: 'your-api-key' });

// 3. Dynamic resolver
Sandbox.config({
  resolveApiKey: async () => await getToken(),
});

API Reference

Static Methods

Sandbox.config(options)

Configure SDK-wide settings.

Sandbox.config({
  apiKey?: string;              // Static API key
  resolveApiKey?: () => Promise<string>; // Dynamic resolver
  baseUrl?: string;             // Optional control plane override
});

The SDK targets the production control plane by default. For local development, set STRIDEKIT_CONTROL_PLANE_URL or pass baseUrl explicitly:

Sandbox.config({
  baseUrl: 'wss://sandbox-api-dev.stridekit.ai',
});

Sandbox.create(config?)

Create a new sandbox VM. Resolves only once the VM has reached the running state — no separate waitUntilReady() call is needed after create().

type SandboxCreateConfig = {
  vmConfig: {
    name: string; // VM name
    cpuCount: number; // Number of CPUs
    memoryMB: number; // Memory in MB
    preset: VmPreset; // e.g. 'ubuntu24' or 'alpine3'
    networkPolicy?: NetworkPolicy; // Egress policy (undefined = allow-all)
    exposedPorts?: ExposedPort[];
    timeoutSeconds?: number; // Auto-terminate after N seconds (max 18000)
    volumeMounts?: VolumeMount[];
    envVars?: Record<string, string>; // Global SDK-launched process env
  };
  timeout?: number; // Command timeout (ms)
  vmCreationTimeout?: number; // VM creation timeout (ms) — default: 180 000
};

Sandbox.connect(vmId, config?)

Connect to an existing VM.

const sandbox = await Sandbox.connect('vm-id', {
  vmConfig?: VmConfig;          // Optional VM config
  timeout?: number;             // Command timeout
});

Sandbox.list()

List all VMs.

const vms = await Sandbox.list();
console.log(vms); // [{ id: 'vm-123', status: 'running', ... }]

Instance Methods

sandbox.commands.run(options)

Execute a command in the sandbox.

const result = await sandbox.commands.run({
  cmd: string;           // Command to execute
  args?: string[];       // Command arguments
  cwd?: string;          // Working directory
  env?: Record<string, string>; // Environment variables
  sudo?: boolean;        // Run with sudo
  user?: string;         // Optional user to run as
  signal?: AbortSignal;  // Cancel on abort
});

// Returns:
{
  commandId: string;
  stdout: string;    // Complete stdout
  stderr: string;    // Complete stderr
  output: string;    // Combined stdout and stderr
  exitCode: number;  // Exit code
  success: boolean;
}

Detached commands return a live handle:

const command = await sandbox.commands.run({
  cmd: 'sleep 30',
  detached: true,
});

await command.cancel();

sandbox.terminate(opts?)

Stop the VM and free its resources. Safe to call multiple times.

// Non-blocking: submit the terminate request and return immediately
await sandbox.terminate();

// Blocking: wait until the VM is fully terminated
const stoppedSandbox = await sandbox.terminate({ blocking: true });

// Blocking with abort signal to cancel the wait
const controller = new AbortController();
await sandbox.terminate({ blocking: true, signal: controller.signal });

Options:

• opts.blocking — When true, waits until the VM status reaches terminated. Defaults to false.
• opts.signal — Optional AbortSignal to cancel a blocking wait.

Returns: Promise<Sandbox>

sandbox.getVmInfo()

Get VM information.

const info = sandbox.getVmInfo();
console.log(info); // { vmId: 'vm-123', hostname: '...', port: 443, status: 'running', cpuCount: 2, memoryMB: 2048, name: 'my-vm' }

Examples

See examples/authentication-examples.ts for comprehensive authentication examples.

Development

Building

nx build sandbox-sdk

Running Tests

nx test sandbox-sdk

Running SDK E2E Tests

The real-control-plane SDK e2e tests live in libs/sandbox-sdk-e2e. The default SDK e2e target runs the static contract suite. Seeded randomized e2e tests are available through explicit e2e-seeded* targets and can be replayed with the same E2E_SEED and scenario index.

# Static contract SDK e2e
E2E_MAX_WORKERS=2 E2E_MAX_LIVE_VMS=6 npx nx run sandbox-sdk-e2e:e2e

# Seeded randomized SDK e2e
E2E_SEED=sdk-e2e-local-001 E2E_SCENARIO_COUNT=10 E2E_MAX_WORKERS=2 E2E_MAX_LIVE_VMS=6 npx nx run sandbox-sdk-e2e:e2e-seeded

See ../sandbox-sdk-e2e/README.md for replay commands and long-running scenarios.

License

Proprietary — see LICENSE.