runta-sdk 0.1.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 data type field, see manual.md.

To render the local Python API docs:

uv run --extra dev mkdocs serve -a 127.0.0.1:8000

import asyncio

from runta import AsyncRunta


async def main():
    async with AsyncRunta() 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()
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 defaults to https://api.runta.dev; override it with 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://api.runta.dev 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://api.runta.dev \
  --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-openapi/specs/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-openapi/specs/openapi.yaml ~/RuntaPythonSDK/contracts/runta-api.openapi.yaml
cd ~/RuntaPythonSDK
uv run python -m 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 python -m pytest --live

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

RUNTA_ENDPOINT=http://127.0.0.1:8080
RUNTA_TOKEN=rt_your_token

Copy or edit .env.example for your local endpoint and token.

Release

This repository publishes runta-sdk to PyPI from GitHub Releases.

1. Update version in pyproject.toml.
2. Run uv run --extra dev python -m pytest.
3. Run rm -rf dist && uv build and uvx twine check dist/*.
4. Commit the release change and create a GitHub Release whose tag is exactly v{pyproject version}, for example v0.0.5.

The Publish SDK workflow validates that the release tag matches pyproject.toml and publishes the built distributions to PyPI with trusted publishing.