Runtime Basic

A Runta runtime is the isolated execution environment where an agent or application process runs commands. The dashboard, CLI, Python SDK, TypeScript SDK, and REST API all operate on the same runtime resources.

Configure Access

export RUNTA_TOKEN=<tenant_token>

Create a Runtime

Create a named runtime with explicit CPU and memory requests:

runta run --name worker --cpus 2 --memory 2048

from runta import Runta

with Runta() as runta:
    runtime = runta.runtimes.create("worker", vcpus=2, memory_mib=2048)

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

const runta = new Runta();
const runtime = await runta.runtimes.create("worker", {
  vcpus: 2,
  memoryMiB: 2048,
});

curl -sS "$RUNTA_ENDPOINT/v1/runtimes" \
  -H "Authorization: Bearer $RUNTA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "worker",
    "resources": {
      "requests": { "vcpus": 2, "memory_mib": 2048 }
    }
  }'

The Python SDK defaults to wait=True and waits for the runtime to become ready before returning. The TypeScript SDK also waits by default.

List and Inspect

Use list calls when you need a fleet view, and get/inspect calls when you need the current state of one runtime.

runta ps -a
runta inspect worker

for item in runta.runtimes.list():
    print(item.id, item.name, item.cached_info.status)

runtime = runta.runtimes.get("worker")

for (const item of await runta.runtimes.list()) {
  console.log(item.id, item.name, item.cachedInfo.status);
}

const runtime = await runta.runtimes.get("worker");

Runtime IDs are UUIDs. The SDKs and CLI also accept display names for the common interactive paths shown in these examples.

Execute Commands

Commands are buffered: the API returns exit code, stdout, stderr, duration, and truncation flags.

runta exec worker -- sh -lc 'pwd && python3 --version'
runta exec -it worker bash

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

print(result.exit_code)
print(result.stdout_text)

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

Use runta exec -it <name> bash for a terminal session. The REST API does not expose persistent server-side session routes; SDK sessions are SDK-owned handles that route commands through the buffered exec API.

Lifecycle

These calls change runtime state without deleting the runtime record.

Task	CLI	Python	TypeScript
Boot a shut-down runtime	`runta boot worker`	`runtime.start()`	`await runtime.start()`
Pause a running runtime	`runta pause worker`	`runtime.pause()`	`await runtime.pause()`
Resume a paused runtime	`runta resume worker`	`runtime.resume()`	`await runtime.resume()`
Shut down a runtime	`runta shutdown worker`	`runtime.stop()`	`await runtime.stop()`
Delete a runtime	`runta rm worker`	`runtime.delete()`	`await runtime.delete()`

Published HTTP runtimes can also be created with an idle timeout:

runta run --name web --cpus 2 --memory 2048 --publish 8080/https --idle-timeout 300

The public ingress hostname is based on the runtime UUID. See Publish a Service for a full flow.

Resize

The CLI exposes memory resizing. The SDKs expose the same operation as resize_memory or resizeMemory.

runta resize --memory 4096 worker

runtime.resize_memory(4096)

await runtime.resizeMemory(4096);

For repeatable multi-runtime changes, use declarative configuration with runta apply -f deployment.json and runta delete -f deployment.json.