runta-sdk 0.0.4

Python SDK for Runta runtime management

Runta Python SDK

This package provides matching async and sync SDKs. Both call the public runta-api HTTP/JSON service; they do not speak control-plane gRPC directly.

Install

pip install runta-sdk

For user-facing installation, configuration, and workflow examples, see doc.md.

For a full API reference with every public method, parameter, return value, and model field, see manual.md.

import asyncio

from runta import AsyncRunta


async def main():
    async with AsyncRunta(endpoint="http://127.0.0.1:8080") as runta:
        runtime = await runta.runtimes.create("example")
        result = await runtime.exec("echo hello")
        print(result.stdout_text)


asyncio.run(main())

from runta import Runta

runta = Runta(endpoint="http://127.0.0.1:8080")
runtime = runta.runtimes.create("example")
result = runtime.exec("echo hello")
print(result.stdout_text)
runta.close()

Authentication uses Runta(token="rt_...") or RUNTA_TOKEN. The endpoint uses Runta(endpoint="..."), RUNTA_ENDPOINT, or endpoint from the optional Runta config file.

Public REST endpoint lifecycle test

You can test the SDK against the hosted REST API by pointing the client at https://rest.runta.me and providing a Runta token:

export RUNTA_TOKEN="rt_..."
uv run python scripts/runta-lifecycle.py

The lifecycle script creates a runtime, starts it, runs a command, writes and reads a remote file, uploads a local file, downloads it back, pauses/resumes the runtime, then stops and deletes it. To pass credentials explicitly:

uv run python scripts/runta-lifecycle.py \
  --endpoint https://rest.runta.me \
  --token "$RUNTA_TOKEN"

Use --keep to leave the runtime behind for inspection.

The SDK is aligned with the current crates/runta-api REST routes. The OpenAPI contract exposes single-file raw byte routes at /v1/runtimes/{runtime_id}/files for runtime.files.read, runtime.files.write, runtime.files.upload, and runtime.files.download. SDK sessions are SDK-owned handles because persistent server-side session routes are not exposed.

REST contract

contracts/runta-api.openapi.yaml is copied from runta/crates/runta-api/openapi.yaml and is used by the SDK contract tests. CI refreshes this file from the latest successful runta OpenAPI contract artifact before running tests. If the artifact is unavailable, it falls back to the dev branch raw YAML and then to the checked-in contract.

To refresh it locally after changing runta-api:

cd ~/runta
cargo make openapi
cp crates/runta-api/openapi.yaml ~/RuntaPythonSDK/contracts/runta-api.openapi.yaml
cd ~/RuntaPythonSDK
uv run pytest tests/test_openapi_contract.py

To fetch the latest published contract directly:

scripts/fetch-runta-openapi.py

Live tests

The live test module runs mocked SDK workflow tests by default:

python -m unittest tests/test_live.py -v

Pass --live to run the real runtime tests. They create real runtimes and use external egress, so run them only with scripts/dev-api.sh already running:

uv run pytest --live

Local pytest loads .env automatically. The default local file uses:

RUNTA_ENDPOINT=http://127.0.0.1:8080
RUNTA_TOKEN_FILE=../runta/.dev/cli_token_dev-a

Copy or edit .env.example if your checkout paths differ.