Ona Python SDK

The public Python SDK exposes stable workflows from ona_sdk. For lower-level access, generated protobuf modules are available under gitpod.* and generated Connect service clients are available from client.services.

Install the package with pip install gitpod-sdk.

Run a Codex task in a repository with one call:

from gitpod.v1 import agent_pb2
from ona_sdk import create_client_from_env

ona = create_client_from_env()
run = ona.run_codex(
    repository_url="https://github.com/gitpod-io/template-golang-cli",
    task="Inspect the repository and improve its README.",
    model=agent_pb2.CODEX_OPEN_AI_MODEL_GPT_5_6_SOL,
    reasoning_effort=agent_pb2.CODEX_REASONING_EFFORT_HIGH,
)

for chunk in run.message_stream():
    print(chunk, end="")
result = run.watch_result()
run.delete_environment(force=True)

Omit repository_url for an empty scratch workspace. The message stream is live-only, and the caller must explicitly stop or delete the created environment.

from ona_sdk import create_client_from_env

ona = create_client_from_env()
env = ona.environments().create("https://github.com/gitpod-io/template-golang-cli")

result = env.run_command(
    command="pwd && git status --short",
    working_directory=env.workspace_dir(),
)

print(result.stdout)

create_client_from_env() reads ONA_API_KEY and falls back to GITPOD_API_KEY. If both are set, ONA_API_KEY takes precedence. It uses https://app.ona.com/api by default and accepts ONA_BASE_URL for a custom management-plane domain, local development, or replay verification. Use create_client(api_key=..., base_url=...) to pass values explicitly.

Use client.services when an operation is not covered by a high-level workflow:

from gitpod.v1.environment_pb2 import ListEnvironmentsRequest
from ona_sdk import create_client_from_env

client = create_client_from_env()
response = client.services.environment.list_environments(
    ListEnvironmentsRequest(),
)

The generated clients include every RPC in the public protobuf API and inherit the SDK's authentication, base URL, user agent, and default timeout. Direct calls raise connectrpc.errors.ConnectError; high-level workflows continue to raise the SDK error types documented below.

Pass new_debug_logger() to the client to get human-readable SDK debug logs. The formatter uses ANSI colors by default and honors NO_COLOR; pass no_color=True when writing plain logs.

The SDK is structured as:

• create_client* creates an SDK client for production Connect API calls.
• client.services provides typed, direct access to public API services.
• client.environments() returns environment workflows.
• client.run_codex() creates a workspace and starts an initial Codex task in one call.
• environments.create/get/list/start/stop/delete manages environments.
• Environment.run_command/read_file/write_file/git_changes performs environment ops.
• Environment.start_codex starts Codex in that environment.
• AgentSession.send_message/message_stream/watch_result interacts with the agent execution.

Runnable examples live in examples/.

High-level workflows and direct API access use the official Connect Python runtime and generated clients. Supervisor environment-ops calls use a small private Connect transport because generated supervisor service clients are not available. The package does not ship generated gRPC clients.