Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.stacyide.xyz/llms.txt

Use this file to discover all available pages before exploring further.

The TypeScript SDK works in Node.js 18+ and exposes the same sandbox lifecycle as the REST API.

​
Prerequisites

  • Node.js 18+.
  • A running StacyVM server.
  • An API key when auth is enabled.

​
Install

npm install stacyvm

​
Connect

import { Client } from "stacyvm";

const client = new Client({
  baseUrl: process.env.STACYVM_URL ?? "http://localhost:7423",
  apiKey: process.env.STACYVM_API_KEY,
  userId: "user_123",
  timeout: 60_000,
});
​
baseUrl
string
StacyVM server URL. Defaults to http://localhost:7423.
​
apiKey
string
API key sent as X-API-Key when server auth is enabled.
​
userId
string
Tenant or owner identity sent as X-User-ID for quota and audit attribution.
​
timeout
number
Per-request HTTP timeout in milliseconds.

​
Run A Task

import { Client } from "stacyvm";

const client = new Client({
  baseUrl: "http://localhost:7423",
  apiKey: "sk_test_YOUR_API_KEY",
});

await client.withSandbox({ image: "node:20", ttl: "10m" }, async (sandbox) => {
  await sandbox.writeFile("/app/main.js", "console.log(40 + 2);\n");
  const result = await sandbox.exec("node /app/main.js", { timeout: "10s" });

  if (result.exit_code !== 0) {
    throw new Error(result.stderr);
  }

  console.log(result.stdout);
});
​
exit_code
integer
Process exit code returned by the runtime provider.
​
stdout
string
Captured standard output.
​
stderr
string
Captured standard error.
​
duration
string
Provider-reported execution duration.

​
Stream Output

for await (const chunk of sandbox.execStream("npm test")) {
  if (chunk.stream === "stdout") {
    process.stdout.write(chunk.data);
  } else {
    process.stderr.write(chunk.data);
  }
}

​
Handle Errors

import { Client, ForgevmError } from "stacyvm";

const client = new Client("http://localhost:7423");

try {
  await client.withSandbox({ image: "node:20", ttl: "10m" }, async (sandbox) => {
    await sandbox.exec("node /missing.js", { timeout: "10s" });
  });
} catch (error) {
  if (error instanceof ForgevmError) {
    console.error(error.message);
  } else {
    throw error;
  }
}