@slicervm/sdk

TypeScript SDK for the Slicer VM control-plane API.

Mirrors the Go SDK semantically. The top-level SlicerClient exposes hostGroups, vms, commits, and secrets namespaces for control-plane operations; per-VM operations live on a VM handle returned from client.vms.create() / client.vms.attach().

Supports Unix socket and HTTP(S) transports.

import { SlicerClient, GiB } from '@slicervm/sdk';

const client = new SlicerClient({ baseURL: '/Users/me/slicer-mac/slicer.sock' });

const vm = await client.vms.create(
  'sbox',
  { cpus: 1, ramBytes: GiB(1) },
  { wait: 'agent', waitTimeoutSec: 60 },
);

const result = await vm.execBuffered({ command: 'uname', args: ['-a'] });
console.log(result.stdout);

await vm.fs.writeFile('/tmp/hello.txt', 'hi');
console.log((await vm.fs.readFile('/tmp/hello.txt')).toString());

// Background exec — detached, survives disconnect, logs into an agent-side
// ring buffer. Manage via vm.bg.list/info/logs/kill/wait/remove.
const bg = await vm.bg.exec({ command: 'npm', args: ['run', 'dev'], cwd: '/app' });
for await (const f of vm.bg.logs(bg.execId, { follow: true })) {
  if (f.stdoutBytes) process.stdout.write(f.stdoutBytes);
}

await vm.delete();

Standalone daemon shutdown

Stop the daemon through its known socket or HTTP(S) URL, without looking up a PID. TCP connections use the configured bearer token as usual.

const client = new SlicerClient({ baseURL: '/absolute/path/to/private/slicer.sock' });
await client.shutdownDaemon({ signal: AbortSignal.timeout(30_000) });

This sends POST /daemon/shutdown and returns when the daemon accepts it with 202 Accepted, before VM cleanup finishes. Cancelling the request does not undo an accepted shutdown. The daemon uses its SIGTERM lifecycle, including configured graceful shutdown, suspend policy, and persistent VM restart intentions. A supervisor configured with Restart=always may restart it automatically.

Cold forks

A stopped persistent VM can be committed as an immutable disk parent, then forked into cold-booted children. Fork calls wait for agent readiness and guest identity finalisation by default. wait: 'none' acknowledges launch only; if requested asynchronous finalisation fails, the daemon removes the child rather than expose cloned identity or secrets with partially applied policy.

await vm.shutdown();
const parent = await vm.commit({
  tags: ['node-build'],
  cacheKey: 'node-build-v1',
});

const child = await parent.fork({
  wait: 'agent',
  waitTimeoutSec: 120,
  persistent: false,
  vcpu: 1,
  ramBytes: 512 * 1024 * 1024,
  network: { allow: [], drop: ['0.0.0.0/0'] },
  tagMode: 'replace',
  tags: ['job=node-build'],
  secrets: [],
});

const description = await child.describe();
console.log(description.parentCommitId, description.network.effective);

const cached = await client.commits.list({ cacheKey: 'node-build-v1' });
await child.delete();
await vm.delete();
await client.commits.delete(parent.commitId);

Examples

• slicer-x11 — a disposable cloud desktop built on this SDK: cold-fork a golden microVM per session and stream it to the browser over noVNC.

Status

Pre-release. See ts-plan.md.