TypeScript SDK

npm install @pandastack/sdk
# or: pnpm add @pandastack/sdk · yarn add @pandastack/sdk · bun add @pandastack/sdk

export PANDASTACK_API_KEY=pds_abc123def456...
export PANDASTACK_API=https://api.pandastack.ai   # optional, this is the default

import {
  Client,
  PandaStackError, AuthError, NotFoundError, BadRequestError, ServerError, NetworkError,
  type SandboxCreateOptions, type SandboxInfo, type ExecResult,
  type LifecycleInfo, type PreviewInfo, type SnapshotInfo,
  type TemplateInfo, type TemplateBuild, type TemplateBuildOptions,
  type TokenInfo, type CreatedToken, type MeInfo,
  type LogsOptions,
} from "@pandastack/sdk";

const client = new Client();        // reads env vars
const sandbox = await client.sandboxes.create({ template: "code-interpreter" });

new Client(config?: {
  apiUrl?: string;       // default: process.env.PANDASTACK_API ?? "https://api.pandastack.ai"
  apiKey?: string;       // default: process.env.PANDASTACK_API_KEY
  timeoutMs?: number;    // default: 30_000
})

const me = await client.me();         // → { user_id, email, org_id, ... }

const sandbox = await client.sandboxes.create({
  template:   "code-interpreter",   // default "ubuntu-24.04"; CPU + memory are baked in
  ttlSeconds: 3600,                 // default server-side (3600)
  persistent: false,
  fromSnapshot: "snap-…",           // boot from a specific snapshot
  metadata: { job: "demo" },
  volumes: [{ name: "data", readOnly: true }],
});

await client.sandboxes.list();             // Sandbox[]
await client.sandboxes.get(id);            // Sandbox
await client.sandboxes.delete(id);         // void

const result = await sandbox.exec("python3 -c 'print(2+2)'", { timeoutSeconds: 10 });
// { stdout: "4\n", stderr: "", exit_code: 0, exitCode: 0, duration_ms: 23 }

await sandbox.runCode("print('hi')", "python");
await sandbox.runCode("ls /workspace");                    // language defaults to "shell"
await sandbox.commands.run("ls /workspace");               // alias for exec

for await (const line of sandbox.logs({ stream: "both", follow: true })) {
  console.log(line);
  if (line.includes("Ready")) break;
}

await sandbox.filesystem.write("/workspace/in.txt", "hi\n");
const text = await sandbox.filesystem.read("/workspace/in.txt");   // string
await sandbox.filesystem.upload("./local.csv", "/workspace/data.csv");
await sandbox.filesystem.download("/workspace/out.csv", "./out.csv");

await sandbox.pause();
await sandbox.resume();

const snap   = await sandbox.snapshot();                 // SnapshotInfo
const child  = await sandbox.fork({ metadata: { branch: "exp" } });
const fanout = await sandbox.forkTree({ count: 8, metadata: { batch: "search" } });
await child.promote();                                   // detach from parent

await sandbox.hibernate();
await sandbox.wake();

await sandbox.setTtl(7200);
await sandbox.setPersistent(true);
await sandbox.lifecycle();   // { ttl_seconds, persistent, idle_seconds }

await sandbox.kill();

{
  await using sandbox = await client.sandboxes.create({ template: "code-interpreter" });
  await sandbox.exec("python3 train.py");
}  // sandbox.kill() auto-called

sandbox.previewUrl(3000);                                  // → "https://3000-…"
await sandbox.previewUrls();                               // → { 3000: "..." }

await client.templates.list();
await client.templates.get("code-interpreter");
await client.templates.delete("my-template");

const build = await client.templates.build({
  name:     "my-template",
  rootfs:   "/path/to/Dockerfile.tar",   // string | Blob | Uint8Array | ArrayBuffer
  sizeMb:   2048,
  kernel:   "kernel-6.1",                // optional
});
console.log(build.id, build.status);

await client.templates.builds();
await client.templates.buildStatus(build.id);

// Create — blocks until Postgres is accepting connections (~30–90s)
const db = await client.databases.create({ label: "my-app-db" }); // size is fixed by the postgres-16 template
console.log(db.connection_url);                  // postgres://...

await client.databases.list();                   // metadata only (no credentials)
await client.databases.get(db.id);               // full record incl. connection_url
await client.databases.connection(db.id);        // { connection_url, broker_url, broker_token }
await client.databases.delete(db.id);            // irreversible

const vol = await client.volumes.create({ name: "models", size_mb: 4096 });
await client.volumes.list();             // VolumeInfo[]
await client.volumes.get("models");
await client.volumes.delete("models");   // refused (409) while attached to a running sandbox

// Attach at create — appears as /dev/vdb (then vdc, ...) inside the guest
const sandbox = await client.sandboxes.create({
  template: "code-interpreter",
  volumes: [{ name: "models", readOnly: true }, { name: "scratch" }],
});
await sandbox.exec("mkdir -p /mnt/models && mount -o ro /dev/vdb /mnt/models");

// Create — only name + git_url are required; framework is auto-detected when omitted
const app = await client.apps.create({
  name: "my-site",
  git_url: "https://github.com/acme/my-site",
  git_branch: "main",                 // optional (default: main)
  framework: "nextjs",                // optional: nextjs | vite | node | static
  install_command: undefined,         // optional build/run overrides
  build_command: undefined,
  start_command: undefined,
  root_directory: undefined,          // optional sub-dir to build from
  port: 3000,                         // optional (default: 3000)
  env: { NODE_ENV: "production" },
});
console.log(app.id, app.url);         // `url` is populated once running

await client.apps.list();             // AppInfo[]
await client.apps.get(app.id);        // includes the stable `url`
await client.apps.update(app.id, { build_command: "npm run build:prod" });
await client.apps.delete(app.id);     // also tears down the runtime sandbox

const dep = await client.apps.deploy(app.id, { gitRef: "v1.2.0" });  // gitRef optional
await client.apps.deployments(app.id);             // newest first
await client.apps.deployment(app.id, dep.id);      // includes full build log

for await (const line of client.apps.deployLogs(app.id, dep.id)) {   // SSE stream
  console.log(line);
}

await client.apps.rollback(app.id);   // rebuild + flip back to the previous deployment

await client.tokens.list();                       // TokenInfo[]
const created = await client.tokens.create("ci-pipeline");  // CreatedToken (.token visible once)
await client.tokens.revoke(created.prefix);

try {
  const s = await client.sandboxes.get(id);
} catch (e) {
  if (e instanceof NotFoundError) {
    return client.sandboxes.create({ template: "code-interpreter" });
  }
  throw e;
}

const client = new Client({ apiUrl: "https://api.acme.dev" });
(client as any).previewHost = "preview.acme.dev";
sandbox.previewUrl(3000);  // → https://3000-{id}.preview.acme.dev