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.
The Ona SDK lets you create environments, run tasks, manage automations, and control runners programmatically. Available in Python, Node/TypeScript, and Go.
SDKs available
See the API Reference for full details.
Getting started
1. Sign up
Go to app.ona.com and sign up. Then generate a personal access token for SDK authentication.
2. Install the SDK
# 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:
export GITPOD_API_KEY="your_token_here"
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.
# Python
from gitpod import Gitpod
gitpod = Gitpod(bearer_token="your_token_here")
// 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
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:
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())
This is a simplified example. See the
full examples in the Python SDK repository for production patterns including cleanup handling.
Examples
| Example | Description | Link |
|---|
| Run a command | Initialize an environment from a Git repository and run a command | Python |
| Run a service | Run a long-lived service (database, message queue) in an environment | Python |
| File system access | Read and write files in an environment programmatically | Python |
| SCM authentication | Authenticate with source control providers in an environment | Python |
| Anthropic tool use | Use the Anthropic tool with Model Context Protocol (MCP) | Python |
| MCP server | MCP server integration | Go |
