Tama Python SDK

Typed, agent-friendly access to Tama's control plane. The SDK can reuse the credentials written by the Tama CLI, so local scripts need no token plumbing.

cd sdks/python
uv sync --extra dev

from tama_sdk import Tama

with Tama(profile="production") as tama:
    machine = tama.new(name="worker", image="ubuntu:24.04")

    result = machine.exec(["git", "status", "--short"], check=True)
    print(result.stdout)

    prompt = machine.prompt(
        "Fix the failing tests, then summarize the change.",
        agent="codex",
    )
    print(prompt.output)

The common workflows mirror the CLI: new, list, rm, stop, start, fork, exec, logs, prompt, expose, unexpose, ports, desktop, and terminal. Returned machines keep those actions scoped:

machine = tama.get("worker")
machine.stop()
machine.start()

session = machine.prompt("Review the repository", detach=True)
for event in tama.logs(session.id):
    print(event.data, end="")

Secondary resources use discoverable collections:

tama.snapshots.list(machine="worker")
tama.templates.list()
tama.secrets.set("OPENAI_API_KEY", "...")
tama.tokens.create("ci")

For CI, set TAMA_TOKEN and optionally TAMA_API_URL. Configuration precedence is explicit constructor values, environment variables, then the selected CLI profile. The SDK never prints credentials.

The complete generated schema is available as tama_sdk.proto, and the generated service stub is available as tama.raw when a new RPC lands before its convenience wrapper.

Safety and retries

Read-only RPCs retry short UNAVAILABLE and DEADLINE_EXCEEDED failures with bounded exponential backoff. Mutations are never retried automatically: a timed-out create or snapshot may already be running on the server.

Development

uv run --extra dev python scripts/generate.py
uv run --extra dev pytest
uv run --extra dev ruff check .
uv run --extra dev mypy

The generated protobuf modules are committed so installing the wheel does not require protoc.