> ## 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.
# List Runners
> Lists all registered runners with optional filtering.
`Unary` ยท [`Runners`](/docs/api-reference/generated/runner/overview)
Lists all registered runners with optional filtering.
Use this method to:
* View all available runners
* Filter by runner type
* Monitor runner status
* Check runner availability
### Examples
* List all runners:
Shows all runners with pagination.
```yaml theme={null}
pagination:
pageSize: 20
```
* Filter by provider:
Lists only AWS EC2 runners.
```yaml theme={null}
filter:
providers: ["RUNNER_PROVIDER_AWS_EC2"]
pagination:
pageSize: 20
```
## Endpoint
```text theme={null}
POST /api/gitpod.v1.RunnerService/ListRunners
```
Send a Bearer token as described in [Authentication](/docs/api-reference#authenticate-requests). If your organization uses a custom management-plane domain, replace `https://app.ona.com` with that domain.
## Request example
```bash cURL theme={null}
export ONA_HOST=https://app.ona.com
export ONA_API_KEY=
curl --request POST \
--url "$ONA_HOST/api/gitpod.v1.RunnerService/ListRunners" \
--header "Authorization: Bearer $ONA_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"pagination": {
"pageSize": 1
}
}'
```
```python Python theme={null}
import gitpod.v1.pagination_pb2 as pagination_pb2
import gitpod.v1.runner_pb2 as runner_pb2
from ona_sdk import create_client_from_env
ona = create_client_from_env()
request = runner_pb2.ListRunnersRequest(
pagination=pagination_pb2.PaginationRequest(
page_size=1,
),
)
response = ona.services.runner.list_runners(request)
print(response)
```
```typescript TypeScript theme={null}
import { create } from "@bufbuild/protobuf";
import { createClientFromEnv } from "@gitpod/sdk";
import { ListRunnersRequestSchema } from "@gitpod/sdk/gitpod/v1/runner_pb";
async function main() {
const ona = createClientFromEnv();
const request = create(ListRunnersRequestSchema, {
pagination: {
pageSize: 1,
},
});
const response = await ona.services.runner.listRunners(request);
console.log(response);
}
main().catch(console.error);
```
```go Go theme={null}
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.ListRunnersRequest{
Pagination: &gitpodpb.PaginationRequest{
PageSize: 1,
},
})
response, err := ona.Services.Runner.ListRunners(context.Background(), request)
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Msg)
}
```
```json Request body theme={null}
{
"pagination": {
"pageSize": 1
}
}
```
## Request
`gitpod.v1.ListRunnersRequest`
| Field | Type | Required | Description |
| ------------ | ------------------------------------------------------- | -------- | -------------------------------------------------------------- |
| `pagination` | [PaginationRequest](#type-gitpod-v1-pagination-request) | No | pagination contains the pagination options for listing runners |
| `filter` | [Filter](#type-gitpod-v1-list-runners-request-filter) | No | |
## Response
`gitpod.v1.ListRunnersResponse`
| Field | Type | Required | Description |
| ------------ | --------------------------------------------------------- | -------- | -------------------------------------------------------------- |
| `pagination` | [PaginationResponse](#type-gitpod-v1-pagination-response) | No | pagination contains the pagination options for listing runners |
| `runners` | array of [Runner](#type-gitpod-v1-runner) | No | The runners registered in the scope |
## Related types
`gitpod.v1.ListRunnersRequest.Filter`
| Field | Type | Required | Description |
| ------------ | ---------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `creatorIds` | array of string | No | creator\_ids filters the response to only runner created by specified users Constraints: `repeated.items.string.uuid=true, repeated.max_items=25, repeated.min_items=0`. |
| `kinds` | array of [RunnerKind](#enum-gitpod-v1-runner-kind) | No | kinds filters the response to only runners of the specified kinds Constraints: `repeated.items.enum.defined_only=true, repeated.max_items=25, repeated.min_items=0`. |
| `providers` | array of [RunnerProvider](#enum-gitpod-v1-runner-provider) | No | providers filters the response to only runners of the specified providers Constraints: `repeated.items.enum.defined_only=true, repeated.max_items=25, repeated.min_items=0`. |
`gitpod.v1.PaginationRequest`
| Field | Type | Required | Description |
| ---------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `pageSize` | integer | No | Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. Constraints: `int32.gte=0, int32.lte=100`. |
| `token` | string | No | Token for the next set of results that was returned as next\_token of a PaginationResponse |
`gitpod.v1.PaginationResponse`
| Field | Type | Required | Description |
| ----------- | ------ | -------- | --------------------------------------------------------------------------------------- |
| `nextToken` | string | No | Token passed for retrieving the next set of results. Empty if there are no more results |
`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](#type-gitpod-v1-runner-spec) | No | The runner's specification |
| `status` | [RunnerStatus](#type-gitpod-v1-runner-status) | No | The runner's status |
| `creator` | [Subject](#type-gitpod-v1-subject) | No | creator is the identity of the creator of the environment |
| `kind` | [RunnerKind](#enum-gitpod-v1-runner-kind) | No | The runner's kind |
| `provider` | [RunnerProvider](#enum-gitpod-v1-runner-provider) | 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`. |
`gitpod.v1.RunnerSpec`
| Field | Type | Required | Description |
| --------------- | ----------------------------------------------- | -------- | -------------------------- |
| `desiredPhase` | [RunnerPhase](#enum-gitpod-v1-runner-phase) | No | |
| `configuration` | RunnerConfiguration | No | The runner's configuration |
| `variant` | [RunnerVariant](#enum-gitpod-v1-runner-variant) | No | The runner's variant |
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](#enum-gitpod-v1-runner-phase) | 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](#enum-gitpod-v1-runner-capability) | 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. |
`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](#enum-gitpod-v1-principal) | No | Principal is the principal of the subject Constraints: `enum.defined_only=true`. |
| 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 | |
| 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 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 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 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. |
| Value | Number | Description |
| ---------------------------- | -----: | ----------- |
| `RUNNER_VARIANT_UNSPECIFIED` | 0 | |
| `RUNNER_VARIANT_STANDARD` | 1 | |
| `RUNNER_VARIANT_ENTERPRISE` | 2 | |