Gitpod SDK

Requires Enterprise plan. Contact sales for access.

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

SDKs available

• Python SDK
• Node/TypeScript SDK
• Go SDK

See the API Reference for full details.

Getting started

Watch the walkthrough below, then follow the steps to get 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:

export GITPOD_API_KEY="your_token_here"

Or pass the token directly in code:

# 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 = {
        "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())

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
Anthropic tool use	Use the Anthropic tool with Model Context Protocol (MCP)	Python
MCP server	MCP server integration	Go