@pandastack/sdk

TypeScript SDK for PandaStack, open-source Firecracker microVM sandboxes for AI agents and code execution.

Install

npm i @pandastack/sdk

Requires Node.js 18+ and uses native fetch (zero runtime dependencies).

Authentication

Create a token in the PandaStack dashboard, then set:

export PANDASTACK_API_KEY=ps_...

The SDK reads PANDASTACK_API (default https://api.pandastack.ai) and PANDASTACK_API_KEY, or ~/.config/pandastack/config.json with token, apiKey, or api_key.

Quickstart

import { Sandbox } from "@pandastack/sdk";

await using sb = await Sandbox.create({ template: "ubuntu-24.04" });
const result = await sb.exec("echo hello");
console.log(result.stdout);

Client

import { Client } from "@pandastack/sdk";

const client = new Client({ apiKey: process.env.PANDASTACK_API_KEY, timeoutMs: 60_000 });
const me = await client.me();
const sandboxes = await client.sandboxes.list();

Sandboxes

const sb = await client.sandboxes.create({
  template: "code-interpreter",
  cpu: 2,
  memoryMb: 2048,
  ttlSeconds: 300,
  persistent: false,
  metadata: { app: "demo" },
});

await sb.pause();
await sb.resume();
const snap = await sb.snapshot();
await sb.setTtl(600);
await sb.setPersistent(true);
console.log(await sb.lifecycle());
await sb.kill();

Exec and code

const result = await sb.exec("python3 --version", { timeoutSeconds: 10 });
await sb.commands.run("echo alias");
await sb.runCode("print('hello')", "python");
await sb.runCode("echo hello", "shell");

Filesystem

await sb.filesystem.write("/workspace/hello.txt", "hello");
console.log(await sb.filesystem.read("/workspace/hello.txt"));
await sb.filesystem.upload("./local.txt", "/workspace/local.txt");
await sb.filesystem.download("/workspace/result.txt", "./result.txt");

Logs

for await (const line of sb.logs({ stream: "both", follow: true })) {
  console.log(line);
}

Templates

const templates = await client.templates.list();
const ubuntu = await client.templates.get("ubuntu-24.04");
const build = await client.templates.build({ name: "custom", rootfs: "./rootfs.tar.gz", sizeMb: 2048 });
console.log(await client.templates.buildStatus(build.id));
await client.templates.delete("custom");

Tokens

Token management endpoints require dashboard/JWT auth.

const tokens = await client.tokens.list();
const created = await client.tokens.create("ci");
await client.tokens.revoke(created.prefix);

Errors

The SDK exports PandaStackError, AuthError, NotFoundError, BadRequestError, ServerError, and NetworkError. API errors include statusCode and response.