Ona SDK

Available on the Enterprise plan. Contact sales to learn more.

SDK versions 1.x introduce a new API that is not compatible with versions 0.x. The package names remain the same, so update your code when upgrading from a 0.x version to a 1.x version. Follow Migrate from SDK versions 0.x for language-specific instructions.

Use the Ona SDK to create and manage environments, run commands, access files, and start Codex agents from Python, TypeScript, or Go.

Install an SDK

Python
TypeScript
Go

Install the gitpod-sdk package:

python -m pip install gitpod-sdk

Import the high-level SDK from ona_sdk. Python 3.10 or later is required.

Install the @gitpod/sdk package:

npm install @gitpod/sdk

The package supports CommonJS and ECMAScript modules on Node.js 20 and later.

Install the github.com/gitpod-io/gitpod-sdk-go module:

go get github.com/gitpod-io/gitpod-sdk-go

Import github.com/gitpod-io/gitpod-sdk-go/sdk for high-level workflows. Go 1.25 or later is required.

Authenticate the SDK

Create a personal access token, then set ONA_API_KEY:

export ONA_API_KEY="<personal-access-token>"

The SDK reads ONA_API_KEY when you use create_client_from_env, createClientFromEnv, or sdk.NewFromEnv. The default API URL is https://app.ona.com/api. If your organization uses a custom management-plane domain, also set:

export ONA_BASE_URL="https://<custom-domain>/api"

Python applications can use create_client(api_key=..., base_url=...), and TypeScript applications can use createClient({ apiKey, baseUrl }). Do not commit tokens to source control.

Create an environment and run a command

Each high-level client creates a running environment from a repository URL and returns an environment handle. The handle provides command, file, Git, and agent operations.

Python
TypeScript
Go

from ona_sdk import create_client_from_env

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

try:
    result = environment.run_command(
        command="pwd && git status --short",
        working_directory=environment.workspace_dir(),
    )
    print(result.stdout)
finally:
    environments.delete(environment.id(), force=True)

import { createClientFromEnv } from "@gitpod/sdk";

const ona = createClientFromEnv();
const environments = ona.environments();
const environment = await environments.create({
  contextUrl: "https://github.com/gitpod-io/template-golang-cli",
});

try {
  const result = await environment.runCommand({
    command: "pwd && git status --short",
    workingDirectory: environment.workspaceDir(),
  });
  console.log(result.stdout);
} finally {
  await environments.delete(environment.id(), { force: true });
}

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/gitpod-io/gitpod-sdk-go/sdk"
)

func main() {
    ctx := context.Background()
    ona, err := sdk.NewFromEnv()
    if err != nil {
        log.Fatal(err)
    }

    environments := ona.Environments()
    environment, err := environments.Create(ctx, sdk.CreateEnvironmentOptions{
        ContextURL: "https://github.com/gitpod-io/template-golang-cli",
    })
    if err != nil {
        log.Fatal(err)
    }
    defer environments.Delete(ctx, environment.ID(), sdk.DeleteEnvironmentOptions{Force: true})

    status := environment.Proto().GetStatus()
    workspaceDir := status.GetDevcontainer().GetRemoteWorkspaceFolder()
    if workspaceDir == "" {
        workspaceDir = status.GetContent().GetContentLocationInMachine()
    }

    result, err := environment.RunCommand(ctx, sdk.RunCommandOptions{
        Command:          "pwd && git status --short",
        WorkingDirectory: workspaceDir,
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Print(result.Stdout)
}

Choose high-level workflows or direct API clients

Use the high-level SDK for environment and Codex workflows. It handles tasks such as resolving repository context, selecting an environment class, waiting for state changes, connecting to environment operations, and mapping common failures to typed errors. Use the generated clients when the high-level SDK does not cover an API operation:

Python: protobuf messages are under gitpod.v1, and authenticated synchronous service clients are available from ona.services.
TypeScript: core service clients are available from ona.services. Generated protobuf schemas and service descriptors are exported from subpaths such as @gitpod/sdk/gitpod/v1/environment_pb.
Go: protobuf messages are in github.com/gitpod-io/gitpod-sdk-go/v1, and generated Connect clients are in github.com/gitpod-io/gitpod-sdk-go/v1/v1connect.

Direct API clients use protobuf request and response messages. See the API reference for the available services, methods, and fields. The API also covers organization reporting through the Ona Intelligence usage API and AI cost usage API.

Run the full examples

The published SDK packages include runnable examples for environment operations and Codex agents:

Python package files: download the source distribution and open examples/.
TypeScript package examples
Go module source: open sdk/examples/.

Troubleshooting

The SDK reports that ONA_API_KEY is required

Set ONA_API_KEY in the process that starts your application. SDK versions 1.x prefer ONA_API_KEY; GITPOD_API_KEY is supported as a compatibility fallback.

Requests fail when using a custom domain

Set ONA_BASE_URL to your custom management-plane origin followed by /api, for example https://ona.example.com/api. Do not use the vscode. subdomain.

Get Started

Using Ona

Configuration

Administration & Security

Infrastructure

Billing

Learn

Reference

Support

Releases

Ona SDK

Install an SDK

Authenticate the SDK

Create an environment and run a command

Choose high-level workflows or direct API clients

Run the full examples

Troubleshooting

​Install an SDK

​Authenticate the SDK

​Create an environment and run a command

​Choose high-level workflows or direct API clients

​Run the full examples

​Troubleshooting

Install an SDK

Authenticate the SDK

Create an environment and run a command

Choose high-level workflows or direct API clients

Run the full examples

Troubleshooting