Runta TypeScript SDK

Use this SDK to create Runta runtimes, run commands inside them, move files in and out, manage secrets, and create checkpoints from TypeScript or JavaScript.

Runta exposes REST APIs plus a WebSocket command stream. This package gives you a small typed wrapper around those APIs so you can write code like:

const runtime = await runta.runtimes.create("my-runtime");
const result = await runtime.exec("echo hello");
console.log(result.stdoutText);
await runtime.delete();

Requirements

• Node.js 18 or newer
• A Runta API token
• npm, pnpm, or yarn

Install

npm install @runta/runta-sdk

If you are trying this package from this repository before it is published, install dependencies and build it locally:

npm install
npm run build

Set Your Token

The easiest setup is an environment variable:

export RUNTA_TOKEN="rt_your_token_here"

Requests use https://api.runta.com by default. Override the endpoint with new Runta({ endpoint: "..." }), RUNTA_ENDPOINT, or endpoint in the optional Runta config file.

Do not commit real tokens to Git.

Your First Script

Create hello-runta.ts:

import { Runta } from "@runta/runta-sdk";

const runta = new Runta();

const runtime = await runta.runtimes.create("hello-typescript", {
  vcpus: 1,
  memoryMib: 1024,
  memoryMaxMib: 4096,
  idleSuspendAfterSecs: 300,
});

try {
  const result = await runtime.exec("echo hello from runta");
  console.log(result.stdoutText);
} finally {
  await runtime.delete();
}

Run it with a TypeScript runner such as tsx:

npm install --save-dev tsx
npx tsx hello-runta.ts

For plain JavaScript, create hello-runta.mjs with the same code and run:

node hello-runta.mjs

Common Tasks

Create And Boot A Runtime

const runtime = await runta.runtimes.create("worker", {
  vcpus: 1,
  memoryMib: 1024,
  memoryMaxMib: 4096,
});

await runtime.boot();

Run A Command

const result = await runtime.exec(["sh", "-lc", "pwd && ls -la"], {
  timeoutSecs: 30,
});

console.log(result.exitCode);
console.log(result.stdoutText);
console.error(result.stderrText);

You can pass a string when you want shell behavior:

await runtime.exec("cd /tmp && echo hello > message.txt");

Write And Read Files

await runtime.files.write("/tmp/message.txt", "hello");

const text = await runtime.files.readText("/tmp/message.txt");
console.log(text);

Upload And Download Files

await runtime.files.upload("./local-file.txt", "/tmp/local-file.txt");
await runtime.files.download("/tmp/local-file.txt", "./downloaded-file.txt");

upload and download stream files and directory archives over the runtime exec WebSocket, so they do not buffer the complete payload or use the REST request-body limit. File uploads verify the received byte count before an atomic rename; directory transfers use staging paths and clean them up when a transfer is interrupted.

Use write and read for small in-memory values. Use upload and download for repositories, archives, model inputs, build outputs, and other large paths:

await runtime.files.upload("./project", "/workspace/project");
await runtime.files.download("/workspace/dist", "./artifacts/");

List Or Fetch Runtimes

const running = await runta.runtimes.list("running");

const byId = await runta.runtimes.get("runtime-id");
const byName = await runta.runtimes.get("runtime-display-name");

Shut Down Or Delete A Runtime

await runtime.shutdown();
await runtime.delete();

Secrets

const secret = await runta.secrets.set("github-token", "secret-value");

const allSecrets = await runta.secrets.list();
const sameSecret = await runta.secrets.get("github-token");

await runta.secrets.delete(secret.id);

Egress Policy

await runtime.egress.setPolicy({
  mode: "allowlist",
  allowedHosts: ["example.com", "api.github.com"],
  deniedHosts: [],
});

console.log((await runtime.egress.get()).allowedHosts);

setPolicy() replaces the complete policy. Host entries are normalized, sorted, and deduplicated before the request is sent.

Checkpoints

const checkpoint = await runtime.checkpoints.create("full", "worker-checkpoint");

const restored = await runtime.restore(checkpoint.id, {
  name: "worker-restored",
});

Checkpoint creation waits for ready by default. Pass { wait: false } as the third argument to return the initial checkpoint metadata immediately, or poll later with runta.checkpoints.waitUntilReady(checkpoint.id).

Error Handling

The SDK throws typed errors:

import { ApiError, ConfigError, Runta } from "@runta/runta-sdk";

try {
  const runta = new Runta();
  await runta.runtimes.get("missing-runtime");
} catch (error) {
  if (error instanceof ApiError) {
    console.error(error.statusCode, error.code, error.message);
  } else if (error instanceof ConfigError) {
    console.error("Check RUNTA_TOKEN");
  } else {
    throw error;
  }
}

Token Configuration

Authentication uses the first available value from:

• new Runta({ token: "rt_..." })
• RUNTA_TOKEN
• token in RUNTA_CONFIG or ~/.config/runta/config.toml

Example config file:

token = "rt_your_token_here"

Development

Install dependencies:

npm install

Run checks:

npm run generate:openapi
npm run typecheck
npm test
npm run build

npm run generate:openapi regenerates src/internal/openapi/* from contracts/runta-api.openapi.yaml. npm run build runs it automatically.

Generate API Reference

The public API reference uses TypeDoc only to extract compiler-level reflection data. docs/reference.config.mjs then assigns every public export to a curated Core, Managers, or Shared page, or explicitly hides it with a reason and legacy redirect. The semantic renderer under scripts/reference/ produces the final Markdown instead of exposing TypeDoc's Classes, Interfaces, Functions, and Variables categories directly.

Every exported symbol must be accounted for, every visible declaration must have a JSDoc summary, and every public parameter must have a description from JSDoc or the shared parameter glossary. Key workflow methods must include an @example. Generation fails when any of those invariants is violated.

npm run docs:api

The command validates the public surface and writes semantic Markdown, llms.txt, llms-full.txt, and legacy-redirects.json to docs/api/. That directory is ignored because the website repository owns the committed generated pages. To update the website, run the following from a checkout where typescript-sdk and next.runta.com are sibling directories:

cd ../next.runta.com
npm run docs:generate:typescript-sdk

Set RUNTA_TYPESCRIPT_SDK_DIR=/path/to/typescript-sdk when the repositories are not siblings. Do not edit generated website pages manually; update JSDoc here and regenerate them instead.

The SDK CI uploads docs/api/ as the typescript-sdk-reference artifact. The website build downloads that artifact from the latest successful main CI run and extracts it into reference/sdk/typescript/api/ before building Starlight.

Run the live REST API test only when you intentionally want to create a real runtime:

RUNTA_LIVE=1 RUNTA_TOKEN="$RUNTA_TOKEN" npx vitest run tests/live.test.ts

Troubleshooting

missing token: pass token or set RUNTA_TOKEN

Set RUNTA_TOKEN, pass token to new Runta(...), or configure ~/.config/runta/config.toml.

ApiError: HTTP 401

The token is missing, expired, or not accepted by the API.

runtime ... did not reach running state

The runtime did not become ready before the wait timeout. Try a longer timeoutMs in runtime.boot({ wait: true, timeoutMs: 300000 }).

Live tests are skipped

That is expected unless RUNTA_LIVE=1 is set.