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

Optional framework integrations are installed through extras:

pip install "runta-sdk[harbor]"
pip install "runta-sdk[openai]"

The OpenAI extra installs the agents_runta provider module so Agents SDK users can run SandboxAgent workspaces on Runta without installing a separate adapter package.

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", memory_mib=1024, memory_max_mib=4096
        )
        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.com; 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.com 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.com \
  --token "$RUNTA_TOKEN"

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

The SDK is aligned with the current crates/runta-api routes. The OpenAPI contract exposes single-file raw byte routes at /v2/runtimes/{runtime_id}/files; runtime.files.read and runtime.files.write use those routes for small in-memory values. runtime.files.upload and runtime.files.download instead stream files or directory archives over the public exec WebSocket. They avoid the REST request-body limit, verify or stage content before committing it, and clean up temporary paths when a transfer is interrupted. SDK sessions are SDK-owned handles because persistent server-side session routes are not exposed.

runtime.files.upload("./project", "/workspace/project")
runtime.files.download("/workspace/dist", "./artifacts/")

Runtime creation, resource and egress updates, and streaming transfers retry transient failures with exponential backoff and Full jitter. The default is 16 total attempts, including the first request; set retry_max_attempts on Runta or AsyncRunta to use 1–16 attempts. Creation uses one idempotency key per call, and PATCH retries keep the original expected revision. HTTP create and PATCH operations have an eight-minute deadline. Each transfer connection uses the client's timeout (30 seconds by default); an established transfer has no overall time limit. Transfers restart from the beginning after a disconnect.

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 integration 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

Generate API reference

The public API reference is generated from runta.__all__, Python type annotations, and docstrings with Griffe. Every object exported by src/runta/__init__.py and every public method or attribute must have a docstring; generation fails when one is missing. Attribute docstrings are rendered in the generated field tables. The overview separates components into Sync, Async, and Shared sections, while paired class pages link to their counterpart and asynchronous methods retain the async keyword in signatures. Generated class pages are written to classes/sync/, classes/async/, and classes/shared/ instead of a single mixed directory.

Every class page includes a declaration. Publicly constructible classes include construction syntax, while SDK-owned handles explain how to access them from a client or runtime. Method sections use fully qualified names and render parameters, return values, raised exceptions, and examples from Google-style docstrings when available.

The generator records the package version and exact OpenAPI contract revision, then writes llms.txt and llms-full.txt alongside the Markdown for agent-oriented consumption.

uv run --extra dev python scripts/generate-api-reference.py

The command writes Markdown to docs/api/. That directory is ignored because the website repository owns the committed generated pages. To update the website when both repositories are sibling directories:

cd ../next.runta.com
npm run docs:generate:python-sdk

Set RUNTA_PYTHON_SDK_DIR=/path/to/python-sdk when the SDK checkout is elsewhere. Do not edit generated website pages manually; update Python docstrings or annotations and regenerate them instead.

The SDK CI uploads docs/api/ as the python-sdk-reference artifact. The website build downloads that artifact from the latest successful main CI run and extracts it into reference/sdk/python/api/ before building Starlight.

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 build dist *.egg-info to avoid stale package artifacts.
4. Run uv build and uvx twine check dist/*.
5. 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.