> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Ona SDK

> Create environments, run commands, and start Codex agents from Python, TypeScript, or Go.

<Note>Available on the Enterprise plan. [Contact sales](https://ona.com/contact/sales) to learn more.</Note>

<Warning>
  **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](/docs/api-reference/sdk-migration) for language-specific instructions.
</Warning>

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

<Tabs>
  <Tab title="Python">
    Install the [`gitpod-sdk` package](https://pypi.org/project/gitpod-sdk/):

    ```bash theme={null}
    python -m pip install gitpod-sdk
    ```

    Import the high-level SDK from `ona_sdk`. Python 3.10 or later is required.
  </Tab>

  <Tab title="TypeScript">
    Install the [`@gitpod/sdk` package](https://www.npmjs.com/package/@gitpod/sdk):

    ```bash theme={null}
    npm install @gitpod/sdk
    ```

    The package supports CommonJS and ECMAScript modules on Node.js 20 and later.
  </Tab>

  <Tab title="Go">
    Install the [`github.com/gitpod-io/gitpod-sdk-go` module](https://github.com/gitpod-io/gitpod-sdk-go):

    ```bash theme={null}
    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.
  </Tab>
</Tabs>

## Authenticate the SDK

Create a [personal access token](/docs/ona/integrations/personal-access-token), then set `ONA_API_KEY`:

```bash theme={null}
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:

```bash theme={null}
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.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    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 });
    }
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    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)
    }
    ```
  </Tab>
</Tabs>

## 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](https://ona.com/docs/api-reference) for the available services, methods, and fields. The API also covers organization reporting through the [Ona Intelligence usage API](/docs/ona/billing/ona-intelligence-usage-api) and [AI cost usage API](/docs/ona/billing/cost-usage-api).

## Run the full examples

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

* [Python package files](https://pypi.org/project/gitpod-sdk/#files): download the source distribution and open `examples/`.
* [TypeScript package examples](https://unpkg.com/browse/@gitpod/sdk@latest/examples/)
* [Go module source](https://github.com/gitpod-io/gitpod-sdk-go): open `sdk/examples/`.

## Troubleshooting

<Accordion title="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.
</Accordion>

<Accordion title="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.
</Accordion>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.