TypeScript SDK Skill

Create a typescript-sdk/SKILL.md file with this content.

typescript-sdk/SKILL.md

---
name: typescript-sdk
description: Build with the Runta TypeScript SDK. Use when Codex needs to write TypeScript or JavaScript code that creates, lists, inspects, resizes, pauses, resumes, stops, boots, deletes, or restores Runta runtimes; executes commands; reads, writes, uploads, or downloads files; configures egress; manages secrets and secret stubs; creates checkpoints; or handles Runta TypeScript SDK errors.
---

# Runta TypeScript SDK

## Operating Rules

Use this skill for Node.js, TypeScript, JavaScript, and user requests that explicitly ask for TypeScript. Match the repo's package manager and module style.

The TypeScript SDK requires Node.js 18 or newer. SDK calls are async, so use `await` and propagate or handle promises.

Never hardcode real tokens. The SDK reads `RUNTA_TOKEN` from the environment:

```bash
export RUNTA_TOKEN=rt...
```

Use TypeScript names and result fields. Do not mix in Python snake_case for SDK helpers:

| 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 | `allowed_hosts`, `denied_hosts` |

## Install

```bash
npm install @runta/runta-sdk
```

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

## Client Patterns

```ts
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.exit_code);
console.log(result.stdoutText);
await runtime.delete();
```

Common runtime interfaces:

```ts
const running = await runta.runtimes.list("running");
const runtime = await runta.runtimes.get("<runtime_id_or_name>");
await runtime.start();
await runtime.pause();
await runtime.resume();
await runtime.stop();
await runtime.refreshInfo();
await runtime.resizeMemory(4096);
await runtime.delete();
```

## Commands

Buffered commands accept a shell string or argv list:

```ts
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.exit_code);
console.log(result.stdoutText);
console.error(result.stderrText);
```

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

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

## Files

```ts
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.

```ts
await runtime.egress.setPolicy({
  mode: "allowlist",
  allowed_hosts: ["pypi.org", "*.pythonhosted.org"],
  denied_hosts: [],
});
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.

```ts
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

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

## Errors

The SDK throws `ConfigError` and `ApiError`.

```ts
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.