@codivstack/sdk

CodivStack SDK for creating sandboxes and retrieving stats.

Install

npm install @codivstack/sdk

Usage

import { Sandbox } from '@codivstack/sdk';

// API key from env
// export CODIVSTACK_API_KEY="..."

const sandbox = await Sandbox.create({ cpu: 1, memory: 1024 });
const stats = await sandbox.getStats();

Sandbox id access:

const sandbox = await Sandbox.create({ cpu: 1, memory: 1024 });
const id = sandbox.id; // or sandbox.sandboxId

Get sandbox info:

const info = await Sandbox.get(id);

Get or create in one call:

const sbx = await Sandbox.createOrGet({
  sandboxId: 'sandbox-abc123',
  cpu: 1,
  memory: 1024,
  timeout: 3600000
});

Set defaults (so you can pass only sandboxId):

Sandbox.setDefaults({
  cpu: 1,
  memory: 1024,
  timeout: 3600000
});

const sbx = await Sandbox.createOrGet({ sandboxId: 'sandbox-abc123' });
const id = sbx.sandboxId;

List sandboxes:

const { sandboxes, count } = await Sandbox.list();

Pick specific fields:

const stats = await sandbox.getStats({
  select: [
    'resources.cpu',
    'resources.memory',
    'storage',
    'uptime'
  ]
});

Accessing nested values:

const stats = await sandbox.getStats();
const cpuUsage = stats.resources?.cpu?.usage;
const storagePercent = stats.resources?.storage?.percent;

Pass API key manually:

const sandbox = await Sandbox.create({
  apiKey: 'YOUR_API_KEY',
  cpu: 1,
  memory: 1024
});

Storage + metadata example:

const sandbox = await Sandbox.create({
  apiKey: 'YOUR_API_KEY',
  cpu: 1,
  memory: 1024,
  timeout: 3600000, // ms (1 hour)
  storageGB: 20,
  storage: {
    type: 's3',
    bucket: 'my-codivstack-backups',
    pathTemplate: '{userId}/{projectId}/workspace.tar.zst',
    autoBackup: true,
    autoRestore: true,
    credentials: {
      accessKeyId: 'AKIA...',
      secretAccessKey: '...',
      region: 'us-east-1'
    }
  },
  metadata: {
    userId: 'user-123',
    projectId: 'proj-456'
  }
});

Options

Sandbox.create supports:

• apiKey: API key (falls back to CODIVSTACK_API_KEY)
• baseUrl: API base URL (default: https://api.codivstack.dev)
• cpu, memory, timeout
• storageGB: disk limit (GB)
• storage: S3 backup config (type, bucket, pathTemplate, credentials, autoBackup, autoRestore)
• metadata: variables for pathTemplate (e.g., userId, projectId)

Notes

• This SDK is intended for backend use. Do not expose API keys in the browser.
• Requires Node >= 18 (built-in fetch).