> ## 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.
# Create Runner
> Creates a new runner registration with the server.
`Unary` ยท [`Runners`](/docs/api-reference/generated/runner/overview)
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.
```yaml theme={null}
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.
```yaml theme={null}
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.
```yaml theme={null}
name: "Local Development Runner"
provider: RUNNER_PROVIDER_LINUX_HOST
spec:
desiredPhase: RUNNER_PHASE_ACTIVE
configuration:
releaseChannel: RUNNER_RELEASE_CHANNEL_LATEST
autoUpdate: true
```
## Endpoint
```text theme={null}
POST /api/gitpod.v1.RunnerService/CreateRunner
```
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/CreateRunner" \
--header "Authorization: Bearer $ONA_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"name": ""
}'
```
```python Python theme={null}
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="",
)
response = ona.services.runner.create_runner(request)
print(response)
```
```typescript TypeScript theme={null}
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: "",
});
const response = await ona.services.runner.createRunner(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.CreateRunnerRequest{
Name: "",
})
response, err := ona.Services.Runner.CreateRunner(context.Background(), request)
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Msg)
}
```
```json Request body theme={null}
{
"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](#enum-gitpod-v1-runner-kind) | 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](#type-gitpod-v1-runner-spec) | No | |
| `provider` | [RunnerProvider](#enum-gitpod-v1-runner-provider) | 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](#type-gitpod-v1-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
`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.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](#enum-gitpod-v1-runner-release-channel) | 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](#enum-gitpod-v1-log-level) | 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. |
`gitpod.v1.RunnerSpec`
| Field | Type | Required | Description |
| --------------- | ----------------------------------------------------------- | -------- | -------------------------- |
| `desiredPhase` | [RunnerPhase](#enum-gitpod-v1-runner-phase) | No | |
| `configuration` | [RunnerConfiguration](#type-gitpod-v1-runner-configuration) | 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 |
| ----------------------- | -----: | ----------- |
| `LOG_LEVEL_UNSPECIFIED` | 0 | |
| `LOG_LEVEL_DEBUG` | 1 | |
| `LOG_LEVEL_INFO` | 2 | |
| `LOG_LEVEL_WARN` | 3 | |
| `LOG_LEVEL_ERROR` | 4 | |
| 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_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 |
| Value | Number | Description |
| ---------------------------- | -----: | ----------- |
| `RUNNER_VARIANT_UNSPECIFIED` | 0 | |
| `RUNNER_VARIANT_STANDARD` | 1 | |
| `RUNNER_VARIANT_ENTERPRISE` | 2 | |