Runtime Basics

A Runta runtime is an isolated computer where AI agents can work, persist state, and access external resources—with observability and control built in.

Configure Access

export RUNTA_TOKEN=rt...

Create a Runtime

Create a runtime with explicit CPU and memory requests:

CLI

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

Python

from runta import Runta

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

TypeScript

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

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

Trial Resource Quotas

Free trial organizations share aggregate limits of 32 vCPU and 64 GiB of memory across their runtimes.

Runta enforces these limits on the server when creating a runtime or restoring a checkpoint. If a request would exceed a limit, the CLI and API return a RESOURCE_EXHAUSTED error with the current usage, requested resources, and configured limit. Remove or resize an existing runtime, or request fewer resources, before retrying.

List and Inspect

CLI

runta ps -a
runta inspect demo

Python

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

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

TypeScript

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

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

Execute Commands

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

CLI

runta exec demo -- sh -lc 'pwd && python3 --version'   # one-shot session
runta exec -it demo bash                               # interactive session

Python

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

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

TypeScript

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

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

Use runta exec -it demo bash for an interactive session, or use the Runta web terminal.

Resize

Runta supports memory resizing while a runtime is running:

CLI

runta resize --memory 4096 demo

Python

runtime.resize_memory(4096)

TypeScript

await runtime.resizeMemory(4096);

Quick Reference

Lifecycle calls change runtime state without deleting the runtime record, except for delete, which permanently removes it.

CLI

Use the Runta CLI for terminal workflows, shell scripts, and direct runtime operations.

Task	CLI command
Boot a shut-down runtime	runta boot demo
Pause a running runtime	runta pause demo
Resume a paused runtime	runta resume demo
Shut down a runtime	runta shutdown demo
Delete a runtime	runta rm demo

Python

Use these calls after creating or resolving a Python runtime handle such as runtime.

Task	Python SDK
Boot a shut-down runtime	runtime.boot()
Pause a running runtime	runtime.pause()
Resume a paused runtime	runtime.resume()
Shut down a runtime	runtime.shutdown()
Delete a runtime	runtime.delete()

TypeScript

Use these promise-based calls after creating or resolving a TypeScript runtime handle.

Task	TypeScript SDK
Boot a shut-down runtime	await runtime.boot()
Pause a running runtime	await runtime.pause()
Resume a paused runtime	await runtime.resume()
Shut down a runtime	await runtime.shutdown()
Delete a runtime	await runtime.delete()