Ona Python SDK

The public Python SDK exposes stable workflows from ona_sdk. Generated protobuf modules remain available under gitpod.* for lower-level message types, but the SDK intentionally does not expose every raw backend RPC.

Install the package with pip install ona-sdk.

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

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.environments() returns environment workflows.
• 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/.

The SDK uses Connect over the Python standard library HTTP stack. The package includes generated protobuf messages and type stubs, but it does not ship generated gRPC clients.