InstaVM JavaScript SDK + CLI

Official JavaScript/TypeScript SDK and installed CLI for InstaVM. Use it to manage VMs, snapshots, shares, volumes, desktops, account settings, and code execution from Node.js or your shell.

Installation

npm install instavm

Requirements: Node.js 18+, TypeScript 4.7+ (optional)

CLI

The published package includes an instavm binary.

npx instavm --help
pnpm exec instavm --help
yarn exec instavm --help
bunx instavm --help

If you want instavm directly on your PATH, install it globally:

npm install -g instavm
instavm --help

The CLI stores defaults in ~/.instavm/config.json, checks INSTAVM_API_KEY when no key is stored, and also respects INSTAVM_BASE_URL and INSTAVM_SSH_HOST.

Auth & Config

instavm auth set-key
instavm auth status
printf '%s' "$INSTAVM_API_KEY" | instavm auth set-key

Common Commands

instavm whoami
instavm ls
instavm ls -a
instavm ls --watch
instavm create --type computer-use --memory 4096
instavm connect vm_123
instavm deploy
instavm deploy --plan
instavm snapshot ls
instavm snapshot get <snapshot_id> --watch
instavm egress get --session <session_id>
instavm exec --cmd "print('hello from instavm')"
instavm browser read https://example.com
instavm browser screenshot https://example.com --out page.png
instavm volume ls
instavm volume files upload <volume_id> ./README.md --path docs/README.md
instavm share create vm_123 3000 --public
instavm share set-private <share_id>
instavm ssh-key list
instavm desktop viewer <session_id>
instavm doc
instavm billing portal
instavm login
instavm tape ls
instavm vault list
instavm desktop recordings ls

instavm ls shows active VMs only. Use -a or --all to include terminated VM records. On ANSI terminals the human-readable list uses colored status badges, and both instavm ls and instavm snapshot get support --watch for periodic refreshes.

Cookbooks

instavm cookbook pulls curated starter apps from the public instavm/cookbooks catalog, creates a VM, starts the service, creates the share, and returns the public URL.

instavm cookbook list
instavm cookbook info neon-city-webgl
instavm cookbook deploy neon-city-webgl
instavm cookbook deploy hello-fastapi
instavm cookbook deploy my-app --vault vault_a --vault vault_b
instavm deploy ./app --no-vault

The CLI syncs the cookbook repo into ~/.instavm/cookbooks/, checks for git, ssh, scp, and tar, prompts for any required secrets, and auto-registers a local public SSH key if your account does not already have one.

Deploy

instavm deploy tries to deploy the app in the current directory without asking you to create an instavm.yaml first. It detects a simple Node.js or Python web app, creates a VM, uploads the project, starts the service, and gives you a share URL.

instavm deploy
instavm deploy --plan
instavm deploy ./path/to/app

--plan shows the detected runtime, install command, start command, port, and secrets without creating a VM.

instavm deploy is experimental right now. The zero-config path is working best for straightforward Node.js and Python apps. Some runtimes and projects still need follow-up fixes or backend support.

Command Reference

• auth: set-key, status, logout
• login: browser PKCE login (writes profile API key)
• whoami: show account details and SSH keys
• ls/list: show active VMs by default; use -a or --all for all VM records
• cookbook: list, info, deploy for curated starter apps from instavm/cookbooks
• deploy: experimental zero-config deploy for the current app directory
• create/new, rm/delete, clone, connect: core VM workflows
• snapshot: ls, create, build, get, rm
• egress: get, set for VM and session egress policies
• exec: run inline commands, local files, or fetch async task results
• browser: read, screenshot; browser session (create, close, ls); navigate, click, type, fill, scroll, wait, extract
• desktop: status, start, stop, viewer; desktop recordings (ls, get, download, rm)
• vm/vms: includes vm update (memory, snapshot-on-terminate, snapshot name)
• tape: ls, get, start, stop, events, diff, branch, play, lanes, export, rm
• vault / secrets / secret: vault CRUD, secrets, services, setup, catalog, logs, discover
• pty: attach PTY shell to a VM over WebSocket
• billing: portal, status, allocation, usage, usage-history, check, rates, trends, forecast
• volume: ls, get, create, update, rm, checkpoint, files
• share: create, set-public, set-private, revoke
• ssh-key: list, add, remove
• doc/docs: docs links

All leaf commands support --json. Share visibility updates use share_id, which matches the public API.

Examples:

instavm egress set --session <session_id> --no-allow-package-managers --deny-http --domain pypi.org
instavm exec ./script.py
instavm exec result <task_id>
instavm browser read --session <browser_session_id>
instavm browser screenshot https://example.com --out ./page.png

Library Quick Start

import { InstaVM } from 'instavm';

const client = new InstaVM(process.env.INSTAVM_API_KEY || 'your_api_key');

const [me, vms] = await Promise.all([
  client.getCurrentUser(),
  client.vms.list(),
]);

console.log(me.email);
console.log(vms.length);

Parity with Python sandbox_client

This package tracks API and CLI parity with the official Python distribution instavm in sandbox_client (baseline ~0.23.0: instavm/sandbox_client.py, instavm/cli.py, instavm/_cookbook.py). The npm semver line is independent of Python’s pyproject.toml version—see Changelog.

Naming: the JS InstaVM client uses camelCase methods; several Python-style operations are also exposed as thin delegators on InstaVM (for example vault helpers) for readability across languages.

Not available in this JS SDK (by design; tied to the Python ecosystem or deferred):

• instavm.integrations.openai_agents (InstaVMSandboxClient)
• instavm.integrations.mounts (InstaVMCloudBucketMountStrategy)
• cassette_replay–style HTTP transports

Optional LLM integrations

Subpath exports match the Python integration modules. Install optional peers only for the stack you use:

| Import path | Purpose | Typical optional deps | |-------------|---------|------------------------| | instavm/integrations/openai | getOpenAITools, executeToolCall | none (uses your OpenAI client) | | instavm/integrations/azure-openai | Same tools + getSystemPrompt | — | | instavm/integrations/langchain | getLangchainTools() | @langchain/core | | instavm/integrations/llamaindex | getLlamaIndexTools() | llamaindex, zod | | instavm/integrations/ollama | getOllamaTools, executeOllamaTool, OllamaAgent | none (uses fetch to Ollama) |

import { getOpenAITools, executeToolCall } from 'instavm/integrations/openai';

Table of Contents

• CLI
  • Auth & Config
  • Common Commands
  • Cookbooks
  • Deploy
  • Command Reference
• Library Quick Start
• Parity with Python sandbox_client
• Code Execution
  • Cloud Mode
  • Local Mode
  • File Operations
  • Async Execution
• Sessions & Sandboxes
• VMs & Snapshots
• Volumes
  • Volume CRUD & Files
  • VM Volume Attachments
• Networking
  • Egress, Shares, SSH
• Browser Automation
  • Basic Browser Flow
  • Content Extraction
• Computer Use
• Platform APIs
• Error Handling
• Development & Testing
• Further Reading
• Changelog

Code Execution

Cloud Mode

Cloud mode gives you sessions, VM/network controls, platform APIs, and browser sessions.

import { InstaVM } from 'instavm';

const client = new InstaVM('your_api_key', {
  cpu_count: 2,
  memory_mb: 1024,
  env: { APP_ENV: 'dev' },
  metadata: { team: 'platform' },
});

const sessionId = await client.createSession();
console.log('session:', sessionId);

Local Mode

Local mode connects to a self-hosted runner for direct execution and browser helpers.

import { InstaVM } from 'instavm';

const client = new InstaVM('', {
  local: true,
  localURL: 'http://coderunner.local:8222',
});

const result = await client.execute("print('hello from local mode')");
console.log(result.stdout);

File Operations

const client = new InstaVM('your_api_key');
const sessionId = await client.createSession();

// Upload
await client.upload(
  [{ name: 'script.py', content: "print('uploaded')", path: '/app/script.py' }],
  { sessionId }
);

// Execute
await client.execute('python /app/script.py', { language: 'bash', sessionId });

// Download
const download = await client.download('output.json', { sessionId });
console.log(download.filename, download.size);

Async Execution

const client = new InstaVM('your_api_key');

const task = await client.executeAsync("sleep 5 && echo 'done'", { language: 'bash' });
const result = await client.getTaskResult(task.taskId, 2, 60);

console.log(result.stdout);

Sessions & Sandboxes

const client = new InstaVM('your_api_key');
const sessionId = await client.createSession();

// Get the publicly-reachable app URL (optionally for a specific port)
const appUrl = await client.getSessionAppUrl(sessionId, 8080);
console.log(appUrl.app_url);

// List sandbox records with optional metadata filter and limit
const sandboxes = await client.listSandboxes({
  metadata: { env: 'production' },
  limit: 50,
});
console.log(sandboxes.length);

VMs & Snapshots

const client = new InstaVM('your_api_key');

// Create a basic VM
const vm = await client.vms.create({ metadata: { purpose: 'dev' } }, true);
const vmId = String(vm.vm_id);

// Create a VM with pre-attached volumes
const vmWithVols = await client.vms.create({
  metadata: { purpose: 'data-processing' },
  volumes: [
    { volume_id: 'vol_abc', mount_path: '/data', mode: 'rw' },
  ],
}, true);

// List VMs
const vmList = await client.vms.list();              // GET /v1/vms  (running)
const vmAllRecords = await client.vms.listAllRecords(); // GET /v1/vms/ (all records)

// Snapshot a running VM
await client.vms.snapshot(vmId, { name: 'dev-base' }, true);

// Build a snapshot from an OCI image
await client.snapshots.create({
  oci_image: 'docker.io/library/python:3.11-slim',
  name: 'python-3-11-dev',
  vcpu_count: 2,
  memory_mb: 1024,
  type: 'user',
  build_args: {
    git_clone_url: 'https://github.com/example/repo.git',
    git_clone_branch: 'main',
    envs: { NODE_ENV: 'production' },
  },
});

const userSnapshots = await client.snapshots.list({ type: 'user' });

Volumes

Volume CRUD & Files

const client = new InstaVM('your_api_key');

// Create
const volume = await client.volumes.create({
  name: 'project-data',
  quota_bytes: 10 * 1024 * 1024 * 1024,
});
const volumeId = String(volume.id);

// Read / Update
await client.volumes.list(true);   // refresh_usage=true
await client.volumes.get(volumeId, true);
await client.volumes.update(volumeId, {
  name: 'project-data-v2',
  quota_bytes: 20 * 1024 * 1024 * 1024,
});

// File operations
await client.volumes.uploadFile(volumeId, {
  filePath: './README.md',
  path: 'docs/README.md',
  overwrite: true,
});

const files = await client.volumes.listFiles(volumeId, {
  prefix: 'docs/',
  recursive: true,
  limit: 1000,
});

const file = await client.volumes.downloadFile(volumeId, 'docs/README.md');
await client.volumes.deleteFile(volumeId, 'docs/README.md');

// Checkpoints
const checkpoint = await client.volumes.createCheckpoint(volumeId, { name: 'pre-release' });
await client.volumes.listCheckpoints(volumeId);
await client.volumes.deleteCheckpoint(volumeId, String(checkpoint.id));

// Cleanup
await client.volumes.delete(volumeId);

VM Volume Attachments

const vm = await client.vms.create({}, true);
const vmId = String(vm.vm_id);

await client.vms.mountVolume(vmId, {
  volume_id: volumeId,
  mount_path: '/data',
  mode: 'rw',
}, true);

await client.vms.listVolumes(vmId);
await client.vms.unmountVolume(vmId, volumeId, '/data', true);

Networking

Egress, Shares, SSH

const client = new InstaVM('your_api_key');
const sessionId = await client.createSession();

// Egress policy
await client.setSessionEgress(
  {
    allowPackageManagers: true,
    allowHttp: false,
    allowHttps: true,
    allowedDomains: ['npmjs.com', 'registry.npmjs.org'],
  },
  sessionId
);

// Public/private share links
const share = await client.shares.create({ session_id: sessionId, port: 3000, is_public: false });
await client.shares.update(String(share.share_id), { is_public: true });

// SSH key registration
const key = await client.addSshKey('ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... user@host');

Browser Automation

Basic Browser Flow

const client = new InstaVM('your_api_key');

const browser = await client.browser.createSession({ viewportWidth: 1366, viewportHeight: 768 });
await browser.navigate('https://example.com');
await browser.click('a');
const screenshot = await browser.screenshot({ fullPage: true });
await browser.close();

Content Extraction

LLM-friendly extraction with optional interactive-element and anchor discovery:

const browser = await client.browser.createSession();
await browser.navigate('https://example.com/docs');

const content = await browser.extractContent({
  includeInteractive: true,
  includeAnchors: true,
  maxAnchors: 30,
});

console.log(content.readableContent.title);
for (const anchor of (content.contentAnchors || []).slice(0, 5)) {
  console.log(anchor.text, anchor.selector);
}

await browser.close();

Computer Use

Control a full desktop environment inside a VM session:

const client = new InstaVM('your_api_key');
const sessionId = await client.createSession();

// Viewer URL and state
const viewer = await client.computerUse.viewerUrl(sessionId);
const state = await client.computerUse.get(sessionId, '/state');

// Proxy methods (GET, POST, HEAD)
const headResp = await client.computerUse.head(sessionId, '/state');

// VNC websockify URL for remote desktop streaming
const vnc = await client.computerUse.vncWebsockify(sessionId);

Platform APIs

API keys, audit logs, and webhooks:

const client = new InstaVM('your_api_key');

// API Keys
const apiKey = await client.apiKeys.create({ description: 'ci key' });

// Audit log
const events = await client.audit.events({ status: 'success', limit: 25 });

// Webhooks
const endpoint = await client.webhooks.createEndpoint({
  url: 'https://example.com/instavm/webhook',
  event_patterns: ['vm.*', 'snapshot.*'],
});

const deliveries = await client.webhooks.listDeliveries({ limit: 10 });

Error Handling

All SDK errors extend a typed hierarchy for precise catch handling:

import {
  InstaVM,
  AuthenticationError,
  ExecutionError,
  NetworkError,
  RateLimitError,
  SessionError,
} from 'instavm';

const client = new InstaVM('your_api_key');

try {
  await client.execute("raise Exception('boom')");
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.error('Rate limited');
  } else if (error instanceof SessionError) {
    console.error('Session issue:', error.message);
  } else if (error instanceof ExecutionError) {
    console.error('Execution failed:', error.message);
  } else if (error instanceof NetworkError) {
    console.error('Network issue:', error.message);
  } else {
    throw error;
  }
}

Development & Testing

npm install           # Install dependencies
npm run test:unit     # Unit tests (includes a repo scan for accidental secret patterns)
npm run build && npm run test:smoke   # After a build: CLI + dist SDK smoke checks
npm test              # Full vitest default suite
npm run test:e2e      # Live API tests — only when INSTAVM_API_KEY is set (see tests/integration/README.md)
npm run build         # Build package

Do not commit real API keys or .env files. Use placeholders in docs/tests (your_api_key, instavm_sk_test, test-api-key) and keep production keys in environment variables or GitHub Actions secrets.

Further Reading

• JavaScript SDK Docs
• VMs API
• Snapshots API
• Shares API
• Computer Use API
• Webhooks API

Changelog

When checking SDK / CLI parity with the official Python client, use a checkout of sandbox_client (for example ~/Documents/projects/sandbox_client — there is typically no Documents/project/ path). Treat [project] version in that repo’s pyproject.toml as the API parity baseline. Diff instavm/sandbox_client.py and instavm/cli.py against this SDK when adding or reviewing APIs.

npm semver is independent of the Python package version: this JS library advances on its own minor/patch line (for example 0.16.x → 0.17.0) and does not mirror Python’s pyproject.toml version number.

Current npm package version: 0.17.0

0.17.0

• Broad parity with Python sandbox_client ~0.23.0: tapes, vaults, PTY, recordings, credits, session/usage helpers, client-level browser APIs, cookbook/deploy vault flags (--vault, --no-vault, --no-setup-vault), expanded CLI (login, billing, tape, vault, pty, vm update, browser subcommands, desktop recordings), and integration entry points (integrations/openai, azure-openai, langchain, llamaindex, ollama)
• Added colored VM status badges, --watch refreshes for ls and snapshot get, and snapshot-build spinner coverage (from earlier 0.17 work)

0.16.1

• Fixed deploy and cookbook uploads through the SSH gateway by forcing legacy SCP mode

0.16.0

• Expanded CLI docs for instavm cookbook
• Added experimental instavm deploy for zero-config app deploys from the current directory

0.15.1

• ls now matches the SSH gateway: active VMs by default, -a or --all for all VM records
• whoami now uses the live /v1/users/me endpoint

0.15.0

• Installed instavm CLI for npm, pnpm, yarn, bun, and global package installs
• Stored CLI auth/config in ~/.instavm/config.json with INSTAVM_API_KEY fallback
• Added getCurrentUser() and getSessionStatus(sessionId?) helpers for identity and desktop workflows

0.13.0

• getSessionAppUrl(sessionId?, port?) — session app URL with optional port
• listSandboxes({ metadata?, limit? }) — list sandbox records with metadata filtering
• computerUse.head(sessionId, path) — HEAD proxy method for computer-use sessions
• computerUse.vncWebsockify(sessionId) — VNC websockify URL for remote desktop streaming
• VM creation now accepts volumes for pre-attached volume mounts
• APIKey type includes key_prefix and full_key fields

0.12.0

• Manager-based infrastructure APIs (VMs, volumes, snapshots, shares, custom domains, computer use, API keys, audit, webhooks)
• Snapshot build args support for env vars and Git clone inputs
• Distinct VM list helpers for /v1/vms and /v1/vms/

For detailed release history, see GitHub Releases.