Unary · Runners
Creates a new runner registration with the server. Registrations are very short-lived and must be renewed every 30 seconds.
Use this method to:
- Register organization runners
- Set up runner configurations
- Initialize runner credentials
- Configure auto-updates
Examples
-
Create an AWS runner:
Creates a new runner in AWS EC2.
name: "AWS Runner" provider: RUNNER_PROVIDER_AWS_EC2 spec: desiredPhase: RUNNER_PHASE_ACTIVE configuration: region: "us-west" releaseChannel: RUNNER_RELEASE_CHANNEL_STABLE autoUpdate: true -
Create a GCP runner:
Creates a new runner on Google Cloud Platform.
name: "GCP Runner" provider: RUNNER_PROVIDER_GCP spec: desiredPhase: RUNNER_PHASE_ACTIVE configuration: region: "us-central1" releaseChannel: RUNNER_RELEASE_CHANNEL_STABLE autoUpdate: true -
Create local runner (deprecated):
Creates a new local runner on Linux. Local runners are deprecated;
use RUNNER_PROVIDER_AWS_EC2 or RUNNER_PROVIDER_GCP instead.
name: "Local Development Runner" provider: RUNNER_PROVIDER_LINUX_HOST spec: desiredPhase: RUNNER_PHASE_ACTIVE configuration: releaseChannel: RUNNER_RELEASE_CHANNEL_LATEST autoUpdate: true
Endpoint
POST /api/gitpod.v1.RunnerService/CreateRunner
https://app.ona.com with that domain.
Request example
export ONA_HOST=https://app.ona.com
export ONA_API_KEY=<your-token>
curl --request POST \
--url "$ONA_HOST/api/gitpod.v1.RunnerService/CreateRunner" \
--header "Authorization: Bearer $ONA_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"name": "<name>"
}'
import gitpod.v1.runner_pb2 as runner_pb2
from ona_sdk import create_client_from_env
ona = create_client_from_env()
request = runner_pb2.CreateRunnerRequest(
name="<name>",
)
response = ona.services.runner.create_runner(request)
print(response)
import { create } from "@bufbuild/protobuf";
import { createClientFromEnv } from "@gitpod/sdk";
import { CreateRunnerRequestSchema } from "@gitpod/sdk/gitpod/v1/runner_pb";
async function main() {
const ona = createClientFromEnv();
const request = create(CreateRunnerRequestSchema, {
name: "<name>",
});
const response = await ona.services.runner.createRunner(request);
console.log(response);
}
main().catch(console.error);
package main
import (
"context"
"fmt"
"log"
"connectrpc.com/connect"
"github.com/gitpod-io/gitpod-sdk-go/sdk"
gitpodpb "github.com/gitpod-io/gitpod-sdk-go/v1"
)
func main() {
ona, err := sdk.NewFromEnv()
if err != nil {
log.Fatal(err)
}
request := connect.NewRequest(&gitpodpb.CreateRunnerRequest{
Name: "<name>",
})
response, err := ona.Services.Runner.CreateRunner(context.Background(), request)
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Msg)
}
{
"name": "<name>"
}
Request
gitpod.v1.CreateRunnerRequest
| Field | Type | Required | Description |
|---|---|---|---|
name | string | No | The runner name for humans Constraints: string.max_len=127, string.min_len=3. |
kind | RunnerKind | No | The runner’s kind This field is optional and here for backwards-compatibility. Use the provider field instead. If provider is set, the runner’s kind will be deduced from the provider. Only one of kind and provider must be set. Constraints: enum.defined_only=true. |
spec | RunnerSpec | No | |
provider | RunnerProvider | No | The specific implementation type of the runner This field is optional for backwards compatibility but will be required in the future. When specified, kind must not be specified (will be deduced from provider) Constraints: enum.defined_only=true. |
runnerManagerId | string | No | The runner manager id specifies the runner manager for the managed runner. This field is mandatory for managed runners, otheriwse should not be set. Constraints: ignore=1, string.uuid=true. |
Response
gitpod.v1.CreateRunnerResponse
| Field | Type | Required | Description |
|---|---|---|---|
runner | Runner | Yes | Constraints: required=true. |
accessToken | string | No | Deprecated. deprecated, will be removed. Use exchange_token instead. |
exchangeToken | string | No | exchange_token is a one-time use token that should be exchanged by the runner for an access token, using the IdentityService.ExchangeToken rpc. The token expires after 24 hours. |
Related types
Runner
Runner
gitpod.v1.Runner| Field | Type | Required | Description |
|---|---|---|---|
runnerId | string | No | |
createdAt | RFC 3339 timestamp | No | Time when the Runner was created. |
updatedAt | RFC 3339 timestamp | No | Time when the Runner was last udpated. |
name | string | No | The runner’s name which is shown to users |
spec | RunnerSpec | No | The runner’s specification |
status | RunnerStatus | No | The runner’s status |
creator | Subject | No | creator is the identity of the creator of the environment |
kind | RunnerKind | No | The runner’s kind |
provider | RunnerProvider | No | The runner’s provider |
runnerManagerId | string | No | The runner manager id specifies the runner manager for the managed runner. This field is only set for managed runners. Constraints: ignore=1, string.uuid=true. |
RunnerConfiguration
RunnerConfiguration
gitpod.v1.RunnerConfiguration| Field | Type | Required | Description |
|---|---|---|---|
region | string | No | Region to deploy the runner in, if applicable. This is mainly used for remote runners, and is only a hint. The runner may be deployed in a different region. See the runner’s status for the actual region. |
releaseChannel | RunnerReleaseChannel | No | The release channel the runner is on |
autoUpdate | boolean | No | auto_update indicates whether the runner should automatically update itself. |
metrics | MetricsConfiguration | No | metrics contains configuration for the runner’s metrics collection |
logLevel | LogLevel | No | log_level is the log level for the runner |
devcontainerImageCacheEnabled | boolean | No | devcontainer_image_cache_enabled controls whether the devcontainer build cache is enabled for this runner. Only takes effect on supported runners, currently only AWS EC2 and Gitpod-managed runners. |
updateWindow | UpdateWindow | No | update_window defines the daily time window (UTC) during which auto-updates are allowed. If not set, updates are allowed at any time. |
encryptedHoneycombApiKey | base64 string | No | encrypted_honeycomb_api_key is the Honeycomb API key encrypted with the runner’s public key. This is an internal-only field used for debugging and is not exposed in the dashboard UI. |
continuousProfiling | boolean | No | continuous_profiling indicates whether continuous profiling is enabled. This is an internal-only field used for debugging and is not exposed in the dashboard UI. |
warmComputeEnabled | boolean | No | warm_compute_enabled controls the runner’s use of dynamically scaled instance and disk pools to reduce environment startup times. When creating an AWS EC2 or GCP runner, omitting this field defaults the stored preference to enabled. For other providers, omission defaults the stored preference to disabled. The preference only takes effect for supported runners when warm compute is available to the organization. |
RunnerSpec
RunnerSpec
gitpod.v1.RunnerSpec| Field | Type | Required | Description |
|---|---|---|---|
desiredPhase | RunnerPhase | No | |
configuration | RunnerConfiguration | No | The runner’s configuration |
variant | RunnerVariant | No | The runner’s variant |
RunnerStatus
RunnerStatus
RunnerStatus represents the status of a runner
gitpod.v1.RunnerStatus| Field | Type | Required | Description |
|---|---|---|---|
updatedAt | RFC 3339 timestamp | No | Time when the status was last updated. |
version | string | No | |
systemDetails | string | No | |
phase | RunnerPhase | No | The runner’s reported phase |
logUrl | string | No | |
message | string | No | The runner’s reported message which is shown to users. This message adds more context to the runner’s phase. |
region | string | No | region is the region the runner is running in, if applicable. |
additionalInfo | array of FieldValue | No | additional_info contains additional information about the runner, e.g. a CloudFormation stack URL. |
capabilities | array of RunnerCapability | No | capabilities is a list of capabilities the runner supports. |
gatewayInfo | GatewayInfo | No | gateway_info is information about the gateway to which the runner is connected. |
llmUrl | string | No | llm_url is the URL of the LLM service to which the runner is connected. |
publicKey | base64 string | No | public_key is the runner’s public key used for encryption (32 bytes) Constraints: bytes.len=32. |
supportBundleUrl | string | No | support_bundle_url is the URL at which the runner support bundle can be accessed. This URL provides access to pprof profiles and other debug information. Only available for standalone runners. |
Subject
Subject
gitpod.v1.Subject| Field | Type | Required | Description |
|---|---|---|---|
id | string | No | id is the UUID of the subject Constraints: ignore=1, string.uuid=true. |
principal | Principal | No | Principal is the principal of the subject Constraints: enum.defined_only=true. |
LogLevel
LogLevel
| Value | Number | Description |
|---|---|---|
LOG_LEVEL_UNSPECIFIED | 0 | |
LOG_LEVEL_DEBUG | 1 | |
LOG_LEVEL_INFO | 2 | |
LOG_LEVEL_WARN | 3 | |
LOG_LEVEL_ERROR | 4 |
Principal
Principal
| Value | Number | Description |
|---|---|---|
PRINCIPAL_UNSPECIFIED | 0 | |
PRINCIPAL_ACCOUNT | 1 | |
PRINCIPAL_USER | 2 | |
PRINCIPAL_RUNNER | 3 | |
PRINCIPAL_ENVIRONMENT | 4 | |
PRINCIPAL_SERVICE_ACCOUNT | 5 | |
PRINCIPAL_RUNNER_MANAGER | 6 |
RunnerCapability
RunnerCapability
| Value | Number | Description |
|---|---|---|
RUNNER_CAPABILITY_UNSPECIFIED | 0 | |
RUNNER_CAPABILITY_FETCH_LOCAL_SCM_INTEGRATIONS | 1 | RUNNER_CAPABILITY_FETCH_LOCAL_SCM_INTEGRATIONS is used by local runners to indicate they support fetching SCM Integrations. |
RUNNER_CAPABILITY_SECRET_CONTAINER_REGISTRY | 2 | RUNNER_CAPABILITY_SECRET_CONTAINER_REGISTRY is used by runners to indicate they support secret container registries. |
RUNNER_CAPABILITY_AGENT_EXECUTION | 3 | RUNNER_CAPABILITY_AGENT_EXECUTION is used by runners to indicate they support agent execution. |
RUNNER_CAPABILITY_ALLOW_ENV_TOKEN_POPULATION | 4 | RUNNER_CAPABILITY_ALLOW_ENV_TOKEN_POPULATION is used by runners to indicate they support population of the environment token. |
RUNNER_CAPABILITY_DEFAULT_DEV_CONTAINER_IMAGE | 5 | RUNNER_CAPABILITY_DEFAULT_DEV_CONTAINER_IMAGE is used by runners to indicate they support the default dev container image. |
RUNNER_CAPABILITY_ENVIRONMENT_SNAPSHOT | 6 | RUNNER_CAPABILITY_ENVIRONMENT_SNAPSHOT is used by runners to indicate they support taking a snapshot of an environment. |
RUNNER_CAPABILITY_PREBUILDS_BEFORE_SNAPSHOT_TRIGGER | 7 | RUNNER_CAPABILITY_PREBUILDS_BEFORE_SNAPSHOT_TRIGGER is used by runners to indicate they support the before_snapshot automation trigger. This trigger fires after prebuild tasks complete but before the snapshot is taken. |
RUNNER_CAPABILITY_LIST_SCM_ORGANIZATIONS | 8 | RUNNER_CAPABILITY_LIST_SCM_ORGANIZATIONS is used by runners to indicate they support listing SCM organizations. |
RUNNER_CAPABILITY_CHECK_REPOSITORY_ACCESS | 9 | RUNNER_CAPABILITY_CHECK_REPOSITORY_ACCESS is used by runners to indicate they support checking repository access. |
RUNNER_CAPABILITY_RUNNER_SIDE_AGENT | 10 | RUNNER_CAPABILITY_RUNNER_SIDE_AGENT is used by runners to indicate they support runner-side agent execution. |
RUNNER_CAPABILITY_WARM_POOL | 11 | RUNNER_CAPABILITY_WARM_POOL is used by runners to indicate they support warm pools. |
RUNNER_CAPABILITY_ASG_WARM_POOL | 12 | RUNNER_CAPABILITY_ASG_WARM_POOL is used by runners to indicate they support ASG-backed warm pools. This is set when the CloudFormation stack includes ASG permissions and the runner has the asgWarmPoolEnabled flag set. |
RUNNER_CAPABILITY_PORT_AUTHENTICATION | 13 | RUNNER_CAPABILITY_PORT_AUTHENTICATION indicates the runner supports port authentication. This requires three conditions: 1. Runner code: port spec server on :7070 (met by this binary version) 2. Infrastructure: proxy configured with —management-plane-api-url and port 7070 reachable from proxy (varies per runner type) 3. Proxy code: port auth support (co-deployed with runner, implied by 1+2) |
RUNNER_CAPABILITY_HORIZONTAL_SCALING | 14 | RUNNER_CAPABILITY_HORIZONTAL_SCALING indicates the runner supports horizontal scaling with shard-aware request routing. When set, the management plane uses per-shard Redis Streams instead of broadcasting requests to all replicas via Pub/Sub. |
RUNNER_CAPABILITY_AGENT_EXECUTION_CNF | 15 | RUNNER_CAPABILITY_AGENT_EXECUTION_CNF indicates the runner can attach the custom CNF proof required by CNF-bound delegated actor tokens. |
RUNNER_CAPABILITY_REDIS_STREAM | 16 | RUNNER_CAPABILITY_REDIS_STREAM indicates the runner supports consuming requests and events via durable Redis Streams (per-shard and broadcast) instead of the legacy Redis Pub/Sub channel. |
RUNNER_CAPABILITY_DYNAMIC_LLM_REQUEST_HEADERS | 18 | RUNNER_CAPABILITY_DYNAMIC_LLM_REQUEST_HEADERS indicates the runner can distinguish CEL-backed LLM headers from literal proxy fallbacks and forward CEL expressions to supported in-environment agents. |
RunnerKind
RunnerKind
RunnerKind represents the kind of a runner
| Value | Number | Description |
|---|---|---|
RUNNER_KIND_UNSPECIFIED | 0 | Default zero value. Do not set explicitly. |
RUNNER_KIND_LOCAL | 1 | Deprecated. Deprecated: Local runners are no longer supported. Use RUNNER_PROVIDER_AWS_EC2 or RUNNER_PROVIDER_GCP instead. |
RUNNER_KIND_REMOTE | 2 | The runner is a remote runner |
RUNNER_KIND_LOCAL_CONFIGURATION | 3 | The runner is a system-managed runner that holds shared configuration for local runners. Every organization automatically has one of these runners, and it cannot be deleted nor can new runners of this kind be created. Organization admins can update this runner to change the shared configuration, including: - SCM Integrations. All local runners will use these integrations. - DesiredPhase. Can be set to STOPPED to disable all local runners. This runner cannot be used to run environments. |
RunnerPhase
RunnerPhase
RunnerPhase represents the phase a runner is in
| Value | Number | Description |
|---|---|---|
RUNNER_PHASE_UNSPECIFIED | 0 | Invalid phase |
RUNNER_PHASE_CREATED | 1 | The runner was created but not yet signed up |
RUNNER_PHASE_INACTIVE | 2 | The runner was signed up and is ready to be used, but has not communicated with us yet |
RUNNER_PHASE_ACTIVE | 3 | The runner was signed up and is ready to be used |
RUNNER_PHASE_DELETING | 4 | The runner is in the process of being deleted. |
RUNNER_PHASE_DELETED | 5 | The runner has been deleted. |
RUNNER_PHASE_DEGRADED | 6 | The runner is in a degraded state. |
RunnerProvider
RunnerProvider
RunnerProvider identifies the specific implementation type of a runner.
Each provider maps to a specific kind of runner (local or remote), as
specified below for each provider.
| Value | Number | Description |
|---|---|---|
RUNNER_PROVIDER_UNSPECIFIED | 0 | |
RUNNER_PROVIDER_AWS_EC2 | 1 | AWS EC2 based runner that deploys as a CloudFormation stack Kind: RUNNER_KIND_REMOTE |
RUNNER_PROVIDER_LINUX_HOST | 2 | Deprecated. Deprecated: Is no longer supported. Use RUNNER_PROVIDER_AWS_EC2 or RUNNER_PROVIDER_GCP instead. |
RUNNER_PROVIDER_DESKTOP_MAC | 3 | Deprecated. Deprecated: Is no longer supported. Use RUNNER_PROVIDER_AWS_EC2 or RUNNER_PROVIDER_GCP instead. |
RUNNER_PROVIDER_MANAGED | 4 | Internal use only. A runner managed by the Ona-operated RunnerManager. Do not use when creating your own runners. |
RUNNER_PROVIDER_GCP | 5 | Runner for GCP platform deployed using terraform Kind: RUNNER_KIND_REMOTE |
RUNNER_PROVIDER_DEV_AGENT | 6 | Internal use only. A development runner for testing within an Ona environment. Do not use when creating your own runners. |
RunnerReleaseChannel
RunnerReleaseChannel
| Value | Number | Description |
|---|---|---|
RUNNER_RELEASE_CHANNEL_UNSPECIFIED | 0 | Invalid release channel |
RUNNER_RELEASE_CHANNEL_STABLE | 1 | The runner is on the stable release channel |
RUNNER_RELEASE_CHANNEL_LATEST | 2 | The runner is on the latest release channel |
RunnerVariant
RunnerVariant
| Value | Number | Description |
|---|---|---|
RUNNER_VARIANT_UNSPECIFIED | 0 | |
RUNNER_VARIANT_STANDARD | 1 | |
RUNNER_VARIANT_ENTERPRISE | 2 |