API Reference

Complete API documentation for Playground.

Playground Class

Constructor

new Playground(options: PlaygroundOptions)

PlaygroundOptions

interface PlaygroundOptions {
  providers: Map<string, Provider>;
  imageMappingsPath: string;
}

Methods

createInstance()

Creates a new ephemeral VM instance.

async createInstance(args: CreateInstanceArgs): Promise<PlaygroundInstance>

Parameters:

interface CreateInstanceArgs {
  imageType: string;
  sshKey: string;
  startupScript?: string;
  preferredProvider?: string;
}

Returns: Promise<PlaygroundInstance>

Example:

const instance = await playground.createInstance({
  imageType: 'ubuntu-22-small',
  sshKey: 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAB... user@host',
  startupScript: '#!/bin/bash\napt-get update -y',
  preferredProvider: 'hetzner'
});

destroyInstance()

Destroys a specific VM instance.

async destroyInstance(providerName: string, instanceId: string): Promise<void>

getInstance()

Gets current status of a specific instance.

async getInstance(providerName: string, instanceId: string): Promise<Instance>

getAvailableImageTypes()

Gets available image types from mappings.

getAvailableImageTypes(): string[]

getAvailableProviders()

Gets available providers.

getAvailableProviders(): string[]

getImageMappings()

Gets image mappings for a specific image type.

getImageMappings(imageType: string): ImageMapping[]

PlaygroundInstance Interface

interface PlaygroundInstance extends Instance {
  provider: string;
  imageType: string;
  createdAt: number;
  ttl: number;
  sshKey: string;
}

Instance Interface

interface Instance {
  id: string;
  ip: string;
  providerData?: any;
}

ImageSpec Interface

interface ImageSpec {
  image: string;
  size: string;
}

ImageMapping Interface

interface ImageMapping {
  provider: string;
  image: string;
  size: string;
  priority: number;
  ttl?: number;
}

Provider Interface

interface Provider {
  createVM(spec: ImageSpec, sshKey: string, startupScript?: string): Promise<Instance>;
  destroyVM(instanceId: string): Promise<void>;
  getVM(instanceId: string): Promise<Instance>;
}

Provider Configurations

AWS Provider

interface AWSConfig {
  accessKeyId: string;
  secretAccessKey: string;
  region?: string;
  defaultSubnetId?: string;
  defaultSecurityGroupId?: string;
}

DigitalOcean Provider

interface DigitalOceanConfig {
  apiToken: string;
  defaultRegion?: string;
}

Hetzner Provider

interface HetznerConfig {
  apiToken: string;
  defaultLocation?: string;
}

Image Mappings YAML Structure

ubuntu-22-small:
  - provider: hetzner
    image: ubuntu-22.04
    size: cx11
    priority: 1
    ttl: 3600
  - provider: digitalocean
    image: ubuntu-22-04-x64
    size: s-1vcpu-1gb
    priority: 2
    ttl: 3600

ubuntu-22-medium:
  - provider: hetzner
    image: ubuntu-22.04
    size: cx21
    priority: 1
    ttl: 7200

PlaygroundUtils Class

Utility functions for managing instance lifecycles externally.

isExpired()

static isExpired(instance: PlaygroundInstance): boolean

getTimeToExpiry()

static getTimeToExpiry(instance: PlaygroundInstance): number

filterExpired()

static filterExpired(instances: PlaygroundInstance[]): PlaygroundInstance[]

filterActive()

static filterActive(instances: PlaygroundInstance[]): PlaygroundInstance[]

Playground Docs

Multi-cloud ephemeral VM library