Runta ComputeSDK Integration

This folder is the primary integration track for using Runta as a ComputeSDK sandbox provider.

The integration should be a JavaScript/TypeScript package that adapts ComputeSDK's provider contract to Runta runtimes. It should not depend on the Python SDK at runtime. The Python SDK remains the reference for Runta REST semantics, but ComputeSDK users run in Node and expect npm packages.

Package Target

Recommended published package name:

@runta/computesdk

If the provider is upstreamed into the ComputeSDK monorepo, the package can be published there as:

@computesdk/runta

Both names should expose the same public factory:

import { runta } from "@runta/computesdk";
import { compute } from "computesdk";

const sdk = compute.setConfig({
  defaultProvider: runta({
    token: process.env.RUNTA_TOKEN,
    endpoint: process.env.RUNTA_ENDPOINT ?? "https://api.runta.me",
  }),
});

const sandbox = await sdk.sandbox.create({
  options: {
    name: "example",
    ports: [3000],
  },
});

const result = await sandbox.runCommand("echo hello");
console.log(result.stdout);

Goals

• Provide a first-class ComputeSDK provider for Runta.
• Keep ComputeSDK dependencies out of the core Python SDK.
• Implement the standard sandbox lifecycle: create, get, list, destroy.
• Execute shell commands with cwd, env, timeout, and optional background behavior.
• Support filesystem operations through Runta file APIs and shell fallbacks.
• Support snapshots by mapping ComputeSDK snapshots to Runta checkpoints.
• Support public URLs through Runta ingress once public endpoint resolution is available in the REST API.

Non-Goals

• Reusing the Python SDK from Node.
• Adding OpenAI Agents SDK concepts to the ComputeSDK provider.
• Blocking the first provider on streaming callbacks.
• Guessing public preview URLs when Runta runtime metadata does not expose one.

Local Development

npm install
npm run typecheck
npm test
npm run build

The current implementation includes:

• runta(config) provider factory
• fetch-based Runta REST client
• lifecycle mapping for create, get, list, and destroy
• command execution with final stdout/stderr
• filesystem read/write through Runta file APIs
• filesystem mkdir/readdir/exists/remove through shell fallbacks
• snapshot create/list/delete backed by Runta checkpoints
• mocked unit tests

getUrl({ port }) reads public URLs from Runta runtime ingress metadata when available. If Runta does not expose a URL for the requested port, it raises a clear unsupported error.

Implementation details are in docs/implementation.md. The phased roadmap is in docs/future-plan.md.