Setsuna SDK — TypeScript / JavaScript

setsuna-sdk is the programmatic client for Setsuna machines. It serves TypeScript and JavaScript on Node.js 24.14.0 or newer.

Installing the package does not grant access to the Setsuna service. An authorized Setsuna account is required. Learn more at semswitch.com/setsuna.

Install

npm install setsuna-sdk

TypeScript projects also need @types/node, because process output is delivered as Buffer data. The package is ESM-only: use import, or await import("setsuna-sdk") from CommonJS code, where require() fails.

Access tokens

Supply a Setsuna access token through getAccessToken: () => Promise<string>. The client calls it at connection admission and before expiry to renew the same connection. Return a current token each time. If renewal fails, work on that connection fails with UNAUTHORIZED. Errors from your provider reach your code unchanged. The SDK does not sign in, store tokens, or offer API keys.

First call

import { SetsunaClient } from "setsuna-sdk";

export async function firstCall(getAccessToken: () => Promise<string>): Promise<void> {
  const setsuna = new SetsunaClient({ remote: { getAccessToken } });
  try {
    const machine = await setsuna.machines.create({ leaseSeconds: 1800 });
    try {
      const result = await machine.exec("uname -a");
      console.log(result.exitCode, result.stdout);
    } finally {
      await setsuna.machines.destroy(machine.machineId);
    }
  } finally {
    await setsuna.close();
  }
}

setsuna.machines creates, lists, inspects, and destroys account microVMs. machines.create() returns a handle with its machineId and the lease fixed at readiness: leaseSeconds, expiresAt, and machineConfiguration. Use machine.exec() for commands and machine.processes for guest processes. machines.get(machineId) rebuilds a handle without a request. Parse stored IDs with parseMachineId(); it accepts sbx_ production and sandbox- operator-local IDs.

Files

machine.fs works on handles from machines.create() and machines.get(). Paths are absolute within the guest. This example writes text and streams bytes without collecting them in memory:

import type { Machine } from "setsuna-sdk";

export async function useFiles(machine: Machine, source: AsyncIterable<Uint8Array>): Promise<string> {
  await machine.fs.writeFile("/workspace/message.txt", "hello", { createParents: true });
  await machine.fs.writeStream("/workspace/data.bin", source);
  for await (const chunk of machine.fs.readStream("/workspace/data.bin")) {
    console.log(chunk.byteLength);
  }
  return machine.fs.readText("/workspace/message.txt");
}

fs also provides readFile, readDir, stat, exists, mkdir, remove, rename, copy, and chmod. Pass signal to cancel; streams also accept an idle timeout. Writes commit after the complete body arrives. After an unknown write outcome, inspect the file before retrying.

Pass leaseSeconds as a positive safe integer in whole seconds. The service fixes expiry at readiness; activity never extends it. Omission uses the account policy default; the SDK does not choose a lifetime. Values that cannot produce a representable expiry date are rejected. Destroy the machine when you are done. close() ends only this client's connection; it does not stop processes or machines.

Failures throw SetsunaError with a code and outcome. failed means the operation did not complete; unknown means its result cannot be established. Neither is retry advice. After an unknown outcome, check state before retrying. Machine codes use MACHINE_*; other service codes remain strings. Keep needed IDs instead of relying on machines.list(). A nonzero command exit is a result, not an error.

Examples

The source repository's examples/ covers lifecycle, execution, background processes, PTY, errors, and one-off run(). These files are not packaged. Copy one into a project with setsuna-sdk installed and call its exported function with getAccessToken. For example, await runLifecycle(getAccessToken) creates real machines on your account. Node.js 24 runs .ts files directly, or you can compile them with tsc.

The full client contract is docs/sdk.md in the source repository.

Copyright © 2026 SemSwitch, Inc. All rights reserved. Use of this package is subject to the included license and the SemSwitch Terms of Service.