TypeScript SDK Quickstart

Get up and running with the Noid TypeScript SDK in minutes.

Installation

Install the Noid SDK using your preferred package manager:

npm install @noid/sdk

pnpm add @noid/sdk

yarn add @noid/sdk

Basic Usage

Initialize the Client

import { NoidClient } from '@noid/sdk';

const client = new NoidClient({
  serverUrl: 'http://localhost:7654',
  token: 'your-api-token',
});

Create a VM

// Create a new microVM
const vm = await client.createVM({
  name: 'my-vm',
  vcpus: 2,
  memory: 2048, // MB
});

console.log(`VM created: ${vm.name}`);

Execute Commands

// Execute a command in the VM
const result = await client.exec(vm.name, 'ls -la');
console.log(result.stdout);

// Execute with environment variables
const result = await client.exec(vm.name, 'node app.js', {
  env: {
    NODE_ENV: 'production',
    PORT: '3000',
  },
});

Create Checkpoints

// Create a checkpoint
await client.createCheckpoint(vm.name, 'stable-v1', {
  label: 'Clean development environment',
});

// List checkpoints
const checkpoints = await client.listCheckpoints(vm.name);
console.log(checkpoints);

Restore from Checkpoint

// Restore in-place
await client.restore(vm.name, 'stable-v1');

// Clone to new VM
await client.restore(vm.name, 'stable-v1', {
  as: 'test-instance-2',
});

List VMs

const vms = await client.listVMs();

for (const vm of vms) {
  console.log(`${vm.name}: ${vm.status}`);
  console.log(`  vCPUs: ${vm.vcpus}, Memory: ${vm.memory}MB`);
  console.log(`  IP: ${vm.ip || 'N/A'}`);
}

Destroy a VM

await client.destroyVM(vm.name);
console.log(`VM ${vm.name} destroyed`);

Complete Example

Here's a complete example showing a typical workflow:

import { NoidClient } from '@noid/sdk';

async function main() {
  // Initialize client
  const client = new NoidClient({
    serverUrl: process.env.NOID_SERVER || 'http://localhost:7654',
    token: process.env.NOID_TOKEN || '',
  });

  try {
    // Create a VM
    const vm = await client.createVM({
      name: 'dev-env',
      vcpus: 2,
      memory: 2048,
    });
    console.log(`✓ Created VM: ${vm.name}`);

    // Set up the environment
    await client.exec(vm.name, 'apt-get update -y');
    await client.exec(vm.name, 'apt-get install -y nodejs npm');
    console.log('✓ Installed Node.js');

    // Create a golden checkpoint
    await client.createCheckpoint(vm.name, 'golden', {
      label: 'Node.js development environment',
    });
    console.log('✓ Created checkpoint: golden');

    // Run some tests
    const result = await client.exec(vm.name, 'node --version');
    console.log(`Node version: ${result.stdout.trim()}`);

    // Restore to clean state
    await client.restore(vm.name, 'golden');
    console.log('✓ Restored to golden checkpoint');

    // Create a clone for testing
    await client.restore(vm.name, 'golden', {
      as: 'test-env',
    });
    console.log('✓ Created clone: test-env');

    // List all VMs
    const vms = await client.listVMs();
    console.log(`\nTotal VMs: ${vms.length}`);
    for (const vm of vms) {
      console.log(`  - ${vm.name} (${vm.status})`);
    }
  } catch (error) {
    console.error('Error:', error);
    process.exit(1);
  }
}

main();

Error Handling

The SDK throws errors for failed operations. Always wrap calls in try-catch blocks:

try {
  await client.createVM({ name: 'my-vm' });
} catch (error) {
  if (error instanceof NoidError) {
    console.error(`Noid error: ${error.message}`);
    console.error(`Status code: ${error.statusCode}`);
  } else {
    console.error(`Unexpected error: ${error}`);
  }
}

Configuration

The client accepts several configuration options:

const client = new NoidClient({
  // Required
  serverUrl: 'http://localhost:7654',
  token: 'your-api-token',

  // Optional
  timeout: 30000, // Request timeout in ms (default: 30000)
  retries: 3, // Number of retries for failed requests (default: 3)
  retryDelay: 1000, // Delay between retries in ms (default: 1000)
});

Environment Variables

You can use environment variables for configuration:

export NOID_SERVER=http://localhost:7654
export NOID_TOKEN=your-api-token

const client = new NoidClient({
  serverUrl: process.env.NOID_SERVER,
  token: process.env.NOID_TOKEN,
});

Next Steps