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.
npm install instavm
Requirements: Node.js 18+, TypeScript 4.7+ (optional)
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.
instavm auth set-key
instavm auth status
printf '%s' "$INSTAVM_API_KEY" | instavm auth set-key
instavm whoami
instavm ls
instavm ls -a
instavm create --type computer-use --memory 4096
instavm connect vm_123
instavm deploy
instavm deploy --plan
instavm snapshot ls
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
instavm ls shows active VMs only. Use -a or --all to include terminated VM records.
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
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.
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.
auth: set-key, status, logoutwhoami: show account details and SSH keysls/list: show active VMs by default; use -a or --all for all VM recordscookbook: list, info, deploy for curated starter apps from instavm/cookbooksdeploy: experimental zero-config deploy for the current app directorycreate/new, rm/delete, clone, connect: core VM workflowssnapshot: ls, create, build, get, rmdesktop: status, start, stop, viewervolume: ls, get, create, update, rm, checkpoint, filesshare: create, set-public, set-private, revokessh-key: list, add, removedoc/docs, billing: docs and billing linksAll leaf commands support --json. Share visibility updates use share_id, which matches the public API.
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);
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 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);
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);
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);
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);
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' });
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);
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);
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');
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();
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();
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);
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 });
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;
}
}
npm install # Install dependencies
npm run test:unit # Unit tests
npm test # Full test suite
npm run build # Build package
Current package version: 0.16.0
instavm cookbookinstavm deploy for zero-config app deploys from the current directoryls now matches the SSH gateway: active VMs by default, -a or --all for all VM recordswhoami now uses the live /v1/users/me endpointinstavm CLI for npm, pnpm, yarn, bun, and global package installs~/.instavm/config.json with INSTAVM_API_KEY fallbackgetCurrentUser() and getSessionStatus(sessionId?) helpers for identity and desktop workflowsgetSessionAppUrl(sessionId?, port?) — session app URL with optional portlistSandboxes({ metadata?, limit? }) — list sandbox records with metadata filteringcomputerUse.head(sessionId, path) — HEAD proxy method for computer-use sessionscomputerUse.vncWebsockify(sessionId) — VNC websockify URL for remote desktop streamingvolumes for pre-attached volume mountsAPIKey type includes key_prefix and full_key fields/v1/vms and /v1/vms/For detailed release history, see GitHub Releases.
FAQs
Official JavaScript SDK and CLI for InstaVM
The npm package instavm receives a total of 130 weekly downloads. As such, instavm popularity was classified as not popular.
We found that instavm demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.