@aperoc/toolkami

TypeScript client for the local toolkami gRPC daemon.

Install

npm install @aperoc/toolkami

The npm package auto-installs the Linux x64 toolkami daemon and toolkami-guest-agent during postinstall. Unsupported platforms fail fast during installation.

Usage

import { createClient } from "@aperoc/toolkami";

const client = await createClient({
  tcpAddress: "127.0.0.1:50061",
});

const versionResponse = await client.getVersion();
const pingResponse = await client.ping("npm");

console.log({ pingResponse, versionResponse });
client.close();

The client reuses an existing daemon at tcpAddress by default and auto-launches the packaged daemon when one is not already running.

Daemon Launch and NBD Permissions

The daemon requires read/write access to NBD block devices (/dev/nbd*).

• Default behavior: createClient(...) reuses existing daemon first, then auto-launches if unavailable.
• If your user lacks NBD permissions, auto-launch fails with an actionable error.
• To disable auto-launch and require an already-running daemon:

const client = await createClient({
  tcpAddress: "127.0.0.1:50061",
  autoLaunch: false,
});

• To explicitly opt into privileged launch:

const client = await createClient({
  tcpAddress: "127.0.0.1:50061",
  useSudo: true,
});

Spawn/Restore with Folder Mounts

import { createClient } from "@aperoc/toolkami";

const client = await createClient({ tcpAddress: "127.0.0.1:50061" });

const image = await client.build({
  dockerfileText: "FROM ubuntu:24.04\nWORKDIR /workspace",
  dockerfileBytesMax: 64_000,
});

const spawned = await client.spawn({
  imageId: image.imageId,
  mounts: [
    {
      sourceHostPath: "/abs/path/to/repo",
      targetPath: "/workspace/repo",
      // default is read-only when omitted
    },
  ],
});

const snap = await client.snapshot({ instanceId: spawned.instanceId });

const restored = await client.restore({
  snapshotId: snap.snapshotId,
  mounts: [
    {
      sourceHostPath: "/abs/path/to/repo",
      targetPath: "/workspace/repo",
    },
  ],
});

console.log(restored.instanceId);
client.close();