Unary · Runners
Gets details about a specific runner.
Use this method to:
- Check runner status
- View runner configuration
- Monitor runner health
- Verify runner capabilities
Examples
-
Get runner details:
Retrieves information about a specific runner.
runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
Endpoint
POST /api/gitpod.v1.RunnerService/GetRunner
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/GetRunner" \
--header "Authorization: Bearer $ONA_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"runnerId": "<runner-id>"
}'
import gitpod.v1.runner_pb2 as runner_pb2
from ona_sdk import create_client_from_env
ona = create_client_from_env()
request = runner_pb2.GetRunnerRequest(
runner_id="<runner-id>",
)
response = ona.services.runner.get_runner(request)
print(response)
import { create } from "@bufbuild/protobuf";
import { createClientFromEnv } from "@gitpod/sdk";
import { GetRunnerRequestSchema } from "@gitpod/sdk/gitpod/v1/runner_pb";
async function main() {
const ona = createClientFromEnv();
const request = create(GetRunnerRequestSchema, {
runnerId: "<runner-id>",
});
const response = await ona.services.runner.getRunner(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.GetRunnerRequest{
RunnerId: "<runner-id>",
})
response, err := ona.Services.Runner.GetRunner(context.Background(), request)
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Msg)
}
{
"runnerId": "<runner-id>"
}
Request
gitpod.v1.GetRunnerRequest
| Field | Type | Required | Description |
|---|---|---|---|
runnerId | string | No | Constraints: string.uuid=true. |
Response
gitpod.v1.GetRunnerResponse
| Field | Type | Required | Description |
|---|---|---|---|
runner | Runner | Yes | Constraints: required=true. |
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. |
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. |
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. |
RunnerVariant
RunnerVariant
| Value | Number | Description |
|---|---|---|
RUNNER_VARIANT_UNSPECIFIED | 0 | |
RUNNER_VARIANT_STANDARD | 1 | |
RUNNER_VARIANT_ENTERPRISE | 2 |