The Gitpod SDK provides powerful tools for developers to interact programmatically with Ona environments. It allows you to automate environment creation, run tasks, manage automations, and scale infrastructure with runners. Available in Python, Node/Typescript, and Go, the SDK gives developers flexibility in their choice of language.

SDKs Available

For detailed API references, consult the API Reference.

End-to-End Walkthrough

Watch the video below to see an end-to-end walkthrough of how to use the Gitpod SDK. The steps below are based on the video.

1. Sign Up

2. Install the SDK

Install for your preferred language:
  • Python SDK:
    pip install gitpod-sdk
    
  • Node/Typescript SDK:
    npm install @gitpod/sdk
    
  • Go SDK:
    go get github.com/gitpod-io/gitpod-sdk-go
    

3. Authenticate

Authenticate using your personal access token. Set via environment variable or pass in code.
  • Option 1: Set the environment variable GITPOD_API_KEY:
    export GITPOD_API_KEY="your_token_here"
    
  • Option 2: Authenticate directly in your code:
    • For Python SDK:
      from gitpod_sdk import Gitpod
      
      gitpod = Gitpod(bearer_token="your_token_here")
      
    • For Go SDK:
      package main
      
      import (
          "github.com/gitpod-io/gitpod-sdk-go"
      )
      
      func main() {
          gitpod := gitpod.NewGitpod("your_token_here")
      }
      
    • For Node/Typescript SDK:
      import { Gitpod } from '@gitpod/sdk';
      
      const gitpod = new Gitpod({ bearerToken: 'your_token_here' });
      

4. Run an Example

Create an environment and run a command using 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 = {
        "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())

Available Examples

Examples in the SDK repositories:

1. Run a Command in an Environment

2. Run a Service in an Environment

3. Access the File System in an Environment

4. Use the Anthropic Tool in an Environment

5. MCP Server Example