Home Features Architecture Docs SDKs Get Started
TypeScript Python Go
SDK

Go

Low-level Go client library and a powerful CLI for terminal-centric sandbox workflows. Import the SDK or use isolon-cli directly.

Installation

Import the SDK

bash
# Import in your Go project
import isolon "isolon/sdk/go/isolon"

# Or build the CLI from source
cd cmd/isolon-cli
go build -o isolon-cli .

Dependencies

go.mod
require (
    github.com/gorilla/websocket v1.5.3
)
Quick Start

Your first sandbox

main.go
package main

import (
    "context"
    "fmt"
    "log"

    isolon "isolon/sdk/go/isolon"
)

func main() {
    ctx := context.Background()
    client := isolon.NewClient("http://localhost:8080", "")

    // Create a sandbox
    ws, err := client.CreateWorkspace(ctx, isolon.WorkspaceRequest{
        Image:    "python:3.12-alpine",
        Cpus:     2,
        MemoryMB: 1024,
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Created sandbox: %s\n", ws.ID)

    // Execute a command
    resp, err := client.Exec(ctx, ws.ID, isolon.ExecRequest{
        Cmd:  "python",
        Args: []string{"-c", "print('Hello from MicroVM')"},
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(resp.Stdout)

    // Terminal session
    term, err := client.ConnectTerminal(ctx, ws.ID)
    if err != nil {
        log.Fatal(err)
    }
    defer term.Close()

    // Cleanup
    if err := client.DeleteWorkspace(ctx, ws.ID); err != nil {
        log.Fatal(err)
    }
}
CLI

isolon-cli

A powerful command-line interface built with Cobra. Supports environment variables and a ~/.isolon/current file for the most recently used sandbox.

bash
# Environment variables
export ISOLON_API_URL="http://localhost:8080"
export ISOLON_API_KEY="your-api-key"

# Create a sandbox
./isolon-cli create python:3.12-alpine
# Created: ws-abc123-dead-beef

# Execute a command
./isolon-cli exec ws-abc123 "python --version"
# Python 3.12.3

# Interactive shell
./isolon-cli shell ws-abc123
root@ws-abc123:~# # PTY session

# Stream logs
./isolon-cli logs ws-abc123

# Get stats
./isolon-cli stats ws-abc123

# List open ports
./isolon-cli ports ws-abc123

# Get preview URL
./isolon-cli preview ws-abc123 3000

# Create a snapshot
./isolon-cli snapshot ws-abc123

# Commit as reusable image
./isolon-cli commit ws-abc123 ml-ready

# List all sandboxes
./isolon-cli list

# Use a sandbox as default for subsequent commands
./isolon-cli use ws-abc123

# Destroy
./isolon-cli destroy ws-abc123

CLI commands reference

CommandDescription
create <image>Create a new sandbox
exec <id> <cmd>Execute a command in a sandbox
shell <id>Open an interactive PTY session
logs <id>Stream serial console logs
snapshot <id>Create a VM snapshot
stats <id>Get VM resource stats
ports <id>List open ports
preview <id> <port>Get a preview URL for a port
listList all sandboxes
use <id>Set the default sandbox for subsequent commands
destroy <id>Destroy a sandbox
API Reference

Go SDK

Client

MethodSignatureDescription
NewClientNewClient(baseURL, apiKey string) *ClientCreate a new client with base URL and optional API key
GetSystemStatsGetSystemStats(ctx) (*SystemStats, error)Get server-level CPU/memory stats

Workspace Lifecycle

MethodSignatureDescription
CreateWorkspaceCreateWorkspace(ctx, WorkspaceRequest) (*WorkspaceResponse, error)Create a new sandbox
DeleteWorkspaceDeleteWorkspace(ctx, id string) errorDestroy a sandbox
GetWorkspaceGetWorkspace(ctx, id string) (*Workspace, error)Get sandbox metadata
ListWorkspacesListWorkspaces(ctx) ([]*Workspace, error)List all sandboxes
PauseWorkspacePauseWorkspace(ctx, id string) errorPause the VM
ResumeWorkspaceResumeWorkspace(ctx, id string) errorResume the VM
ForkWorkspaceForkWorkspace(ctx, id string) (*WorkspaceResponse, error)Fork a sandbox
CommitWorkspaceCommitWorkspace(ctx, id, ref string) (*Image, error)Commit filesystem as image
CreateSnapshotCreateSnapshot(ctx, id string) (*SnapshotResponse, error)Create a VM snapshot
HealthHealth(ctx, id string) (*HealthResponse, error)Check workspace health
SetInternetSetInternet(ctx, id string, enabled bool) errorToggle internet access

Execution

MethodSignatureDescription
ExecExec(ctx, id string, ExecRequest) (*ExecResponse, error)Execute a command in a sandbox

File Operations

MethodSignatureDescription
ListFilesListFiles(ctx, id, path string) ([]FileInfo, error)List directory contents
ReadFileReadFile(ctx, id, path string) (*FileResponse, error)Read a file
WriteFileWriteFile(ctx, id string, WriteFileRequest) errorWrite a file
DeleteFileDeleteFile(ctx, id, path string) errorDelete a file
GetArchiveGetArchive(ctx, id string) ([]byte, error)Download workspace as tar archive

Terminal

MethodSignatureDescription
ConnectTerminalConnectTerminal(ctx, id string) (*Terminal, error)Open a WebSocket PTY session
ConnectLogsConnectLogs(ctx, id string) (*LogStream, error)Stream serial console logs

Process Management

MethodSignatureDescription
ListProcessesListProcesses(ctx, id string) ([]ProcessInfo, error)List running processes
KillProcessesKillProcesses(ctx, id string) errorKill all processes

Port & Preview

MethodSignatureDescription
GetPortsGetPorts(ctx, id string) ([]PortInfo, error)List open ports
GetPreviewURLGetPreviewURL(ctx, id string, port int) (*PreviewURL, error)Get a preview URL

Image & Snapshot

MethodSignatureDescription
WarmImageWarmImage(ctx, id string) errorPre-warm an image for faster boot

Key Types

types.go
type WorkspaceRequest struct {
    Image      string            `json:"image"`
    Cpus       int64             `json:"cpus,omitempty"`
    MemoryMB   int64             `json:"memory_mb,omitempty"`
    DiskSizeGB int               `json:"disk_size_gb,omitempty"`
    TimeoutMs  int64             `json:"timeout_ms,omitempty"`
    KeepAlive  bool              `json:"keep_alive,omitempty"`
    Env        map[string]string `json:"env,omitempty"`
    Labels     map[string]string `json:"labels,omitempty"`
    OnStart    []string          `json:"on_start,omitempty"`
    OnReady    []string          `json:"on_ready,omitempty"`
}

type ExecRequest struct {
    Cmd        string            `json:"cmd"`
    Args       []string          `json:"args,omitempty"`
    Envs       map[string]string `json:"env,omitempty"`
    Background bool              `json:"background,omitempty"`
    Language   string            `json:"language,omitempty"`
}

type ExecResponse struct {
    ExitCode int    `json:"exit_code"`
    Stdout   string `json:"stdout,omitempty"`
    Stderr   string `json:"stderr,omitempty"`
    Pid      int    `json:"pid,omitempty"`
}