Concept	TypeScript
Package	`@runta/runta-sdk`
Client	`Runta`
Create memory	`memoryMib`
Idle timeout	`idleSuspendAfterSecs`
Cached info	`cachedInfo`
stdout text	`stdoutText`
stderr text	`stderrText`
Egress policy fields	`allowedHosts`, `deniedHosts`

Install

npm install @runta/runta-sdk

Use the repo's package manager when it already uses pnpm, yarn, or bun.

Client Patterns

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

const runta = new Runta();
const runtime = await runta.runtimes.create("demo", {
  vcpus: 2,
  memoryMib: 2048,
  idleSuspendAfterSecs: 300,
});

const result = await runtime.exec(["sh", "-lc", "pwd && python3 --version"], {
  timeoutSecs: 30,
  env: { APP_ENV: "dev" },
});

console.log(result.exitCode);
console.log(result.stdoutText);
await runtime.delete();

Common runtime interfaces:

const running = await runta.runtimes.list("running");
const runtime = await runta.runtimes.get("<runtime_id_or_name>");
await runtime.boot();
await runtime.pause();
await runtime.resume();
await runtime.shutdown();
await runtime.refreshInfo();
await runtime.resizeMemory(4096);
await runtime.delete();

Commands

Buffered commands accept a shell string or argv list:

const result = await runtime.exec(["sh", "-lc", "cat input.txt && echo $APP_ENV"], {
  cwd: "/workspace",
  env: { APP_ENV: "dev" },
  stdin: "hello\n",
  timeoutSecs: 30,
  maxOutputBytes: 1024 * 1024,
});

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

Pass a string to runtime.exec() when shell behavior is desired:

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

Files

await runtime.files.write("/tmp/message.txt", "hello");
const text = await runtime.files.readText("/tmp/message.txt");
await runtime.files.upload("local-file.txt", "/tmp/local-file.txt");
await runtime.files.download("/tmp/local-file.txt", "./downloaded-file.txt");

runtime.files.read() returns Uint8Array. Use readText() for decoded text.

Egress

Egress hosts are hostnames or wildcard host patterns, not URLs. denylist with an empty denied list is the default open policy. allowlist permits only matching allowed hosts.

await runtime.egress.setPolicy({
  mode: "allowlist",
  allowedHosts: ["pypi.org", "*.pythonhosted.org"],
  deniedHosts: [],
});
const policy = await runtime.egress.get();

Secrets

Stored secret values live at runta.secrets. Runtime-scoped stubs live at runtime.secrets. Default stubs live at runta.secrets and are copied to new runtimes.

const secret = await runta.secrets.set("github-token", "secret-value", {
  cacheTtlSecs: 300,
});

const stub = await runtime.secrets.setSecretStub("https://api.github.com", {
  path: "/repos/*",
  config: {
    credential: "github-token",
    header: "Authorization",
    value: "Bearer ${credential}",
  },
});

const defaults = await runta.secrets.listDefaultSecretStubs();

Use list, get, and delete helpers for stored secrets. Use listSecretStubs, getSecretStub, and deleteSecretStub for runtime stubs.

Checkpoints

const checkpoint = await runtime.checkpoints.create("full", "demo-checkpoint");
const checkpoints = await runta.checkpoints.list();
const restored = await runtime.restore(checkpoint.id, { name: "restored-demo" });
await runta.checkpoints.delete(checkpoint.id);

Runtime and checkpoint list methods return all matching resources.

Errors

The SDK throws ConfigError and ApiError.

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;
  }
}

For missing token errors, set RUNTA_TOKEN. For HTTP 401, check whether the token is missing, expired, or rejected. For readiness timeouts, increase the wait timeout or inspect runtime state before retrying.

typescript-sdk

Runta TypeScript SDK

Operating Rules