Runtime Basics

A Runta runtime is an isolated environment for AI agents. It gives agents a place to execute commands, use tools, read and write files, and keep task state while still giving you control over LLM token usage, secrets and network access.

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

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 stopped 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 stopped runtime	runtime.start()
Pause a running runtime	runtime.pause()
Resume a paused runtime	runtime.resume()
Shut down a runtime	runtime.stop()
Delete a runtime	runtime.delete()

TypeScript

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

Task	TypeScript SDK
Boot a stopped runtime	await runtime.start()
Pause a running runtime	await runtime.pause()
Resume a paused runtime	await runtime.resume()
Shut down a runtime	await runtime.stop()
Delete a runtime	await runtime.delete()