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

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

The Ona SDK lets you create environments, run tasks, manage automations, and control runners programmatically. Available in Python, Node/TypeScript, and Go.

## SDKs available

* **[Python SDK](https://pypi.org/project/gitpod-sdk/)**
* **[Node/TypeScript SDK](https://www.npmjs.com/package/@gitpod/sdk)**
* **[Go SDK](https://github.com/gitpod-io/gitpod-sdk-go)**

See the [API Reference](https://ona.com/docs/api-reference) for full details.

## Getting started

### 1. Sign up

Go to [app.ona.com](https://app.ona.com) and sign up. Then generate a [personal access token](/ona/integrations/personal-access-token) for SDK authentication.

### 2. Install the SDK

```bash theme={null}
# Python
pip install gitpod-sdk

# Node/TypeScript
npm install @gitpod/sdk

# Go
go get github.com/gitpod-io/gitpod-sdk-go
```

### 3. Authenticate

Set the `GITPOD_API_KEY` environment variable with your [personal access token](/ona/integrations/personal-access-token):

```bash theme={null}
export GITPOD_API_KEY="your_token_here"
```

<Tip>The SDK packages still use the `gitpod` naming convention (e.g. `GITPOD_API_KEY`, `from gitpod import Gitpod`). This will be updated in a future release.</Tip>

Or pass the token directly in code:

```python theme={null}
# Python
from gitpod import Gitpod
gitpod = Gitpod(bearer_token="your_token_here")
```

```go theme={null}
// Go
import (
	"github.com/gitpod-io/gitpod-sdk-go"
	"github.com/gitpod-io/gitpod-sdk-go/option"
)
client := gitpod.NewClient(option.WithBearerToken("your_token_here"))
```

```typescript theme={null}
// TypeScript
import { Gitpod } from '@gitpod/sdk';
const gitpod = new Gitpod({ bearerToken: 'your_token_here' });
```

### 4. Run an example

Create an environment and run a command with the Python SDK:

```python theme={null}
import asyncio
from gitpod import AsyncGitpod
import gitpod.lib as util

repo_url = "https://github.com/containerd/containerd"
command_to_execute = "go test -v -short ./..."

async def execute_command_in_environment():
    client = AsyncGitpod()

    machine_class_id = (await util.find_most_used_environment_class(client)).id

    create_params = {
        "desired_phase": "ENVIRONMENT_PHASE_RUNNING",
        "machine": {"class": machine_class_id},
        "content": {"initializer": {"specs": [{"context_url": {"url": repo_url}}]}}
    }

    environment = (await client.environments.create(spec=create_params)).environment

    await util.wait_for_environment_running(client, environment.id)

    async for line in await util.run_command(client, environment.id, command_to_execute):
        print(line)

    await client.environments.delete(environment_id=environment.id)

if __name__ == "__main__":
    asyncio.run(execute_command_in_environment())
```

<Tip>This is a simplified example. See the [full examples](https://github.com/gitpod-io/gitpod-sdk-python/tree/main/examples) in the Python SDK repository for production patterns including cleanup handling.</Tip>

## Examples

| Example            | Description                                                          | Link                                                                                              |
| ------------------ | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Run a command      | Initialize an environment from a Git repository and run a command    | [Python](https://github.com/gitpod-io/gitpod-sdk-python/blob/main/examples/run_command.py)        |
| Run a service      | Run a long-lived service (database, message queue) in an environment | [Python](https://github.com/gitpod-io/gitpod-sdk-python/blob/main/examples/run_service.py)        |
| File system access | Read and write files in an environment programmatically              | [Python](https://github.com/gitpod-io/gitpod-sdk-python/blob/main/examples/fs_access.py)          |
| SCM authentication | Authenticate with source control providers in an environment         | [Python](https://github.com/gitpod-io/gitpod-sdk-python/blob/main/examples/scm_auth.py)           |
| Anthropic tool use | Use the Anthropic tool with Model Context Protocol (MCP)             | [Python](https://github.com/gitpod-io/gitpod-sdk-python/blob/main/examples/anthropic_tool_use.py) |
| MCP server         | MCP server integration                                               | [Go](https://github.com/gitpod-io/gitpod-sdk-go/tree/main/examples/mcp-server)                    |