## CreateRunner

**post** `/gitpod.v1.RunnerService/CreateRunner`

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 cloud runner:

  Creates a new runner in AWS EC2.

  ```yaml
  name: "Production Runner"
  provider: RUNNER_PROVIDER_AWS_EC2
  spec:
    desiredPhase: RUNNER_PHASE_ACTIVE
    configuration:
      region: "us-west"
      releaseChannel: RUNNER_RELEASE_CHANNEL_STABLE
      autoUpdate: true
  ```

- Create local runner:

  Creates a new local runner on Linux.

  ```yaml
  name: "Local Development Runner"
  provider: RUNNER_PROVIDER_LINUX_HOST
  spec:
    desiredPhase: RUNNER_PHASE_ACTIVE
    configuration:
      releaseChannel: RUNNER_RELEASE_CHANNEL_LATEST
      autoUpdate: true
  ```

### Body Parameters

- `kind: optional RunnerKind`

  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.

  - `"RUNNER_KIND_UNSPECIFIED"`

  - `"RUNNER_KIND_LOCAL"`

  - `"RUNNER_KIND_REMOTE"`

  - `"RUNNER_KIND_LOCAL_CONFIGURATION"`

- `name: optional string`

  The runner name for humans

- `provider: optional RunnerProvider`

  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)

  - `"RUNNER_PROVIDER_UNSPECIFIED"`

  - `"RUNNER_PROVIDER_AWS_EC2"`

  - `"RUNNER_PROVIDER_LINUX_HOST"`

  - `"RUNNER_PROVIDER_DESKTOP_MAC"`

  - `"RUNNER_PROVIDER_MANAGED"`

  - `"RUNNER_PROVIDER_GCP"`

  - `"RUNNER_PROVIDER_DEV_AGENT"`

- `runnerManagerId: optional string`

  The runner manager id specifies the runner manager for the managed runner.
  This field is mandatory for managed runners, otheriwse should not be set.

- `spec: optional RunnerSpec`

  - `configuration: optional RunnerConfiguration`

    The runner's configuration

    - `autoUpdate: optional boolean`

      auto_update indicates whether the runner should automatically update itself.

    - `devcontainerImageCacheEnabled: optional boolean`

      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.

    - `logLevel: optional LogLevel`

      log_level is the log level for the runner

      - `"LOG_LEVEL_UNSPECIFIED"`

      - `"LOG_LEVEL_DEBUG"`

      - `"LOG_LEVEL_INFO"`

      - `"LOG_LEVEL_WARN"`

      - `"LOG_LEVEL_ERROR"`

    - `metrics: optional MetricsConfiguration`

      metrics contains configuration for the runner's metrics collection

      - `enabled: optional boolean`

        enabled indicates whether the runner should collect metrics

      - `managedMetricsEnabled: optional boolean`

        When true, the runner pushes metrics to the management plane via
        ReportRunnerMetrics instead of directly to the remote_write endpoint.

      - `password: optional string`

        password is the password to use for the metrics collector

      - `url: optional string`

        url is the URL of the metrics collector

      - `username: optional string`

        username is the username to use for the metrics collector

    - `region: optional string`

      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: optional RunnerReleaseChannel`

      The release channel the runner is on

      - `"RUNNER_RELEASE_CHANNEL_UNSPECIFIED"`

      - `"RUNNER_RELEASE_CHANNEL_STABLE"`

      - `"RUNNER_RELEASE_CHANNEL_LATEST"`

    - `updateWindow: optional UpdateWindow`

      update_window defines the daily time window (UTC) during which auto-updates are allowed.
      If not set, updates are allowed at any time.

      - `endHour: optional number`

        end_hour is the end of the update window as a UTC hour (0-23).
        If not set, defaults to start_hour + 2.

      - `startHour: optional number`

        start_hour is the beginning of the update window as a UTC hour (0-23).
        +required

  - `desiredPhase: optional RunnerPhase`

    RunnerPhase represents the phase a runner is in

    - `"RUNNER_PHASE_UNSPECIFIED"`

    - `"RUNNER_PHASE_CREATED"`

    - `"RUNNER_PHASE_INACTIVE"`

    - `"RUNNER_PHASE_ACTIVE"`

    - `"RUNNER_PHASE_DELETING"`

    - `"RUNNER_PHASE_DELETED"`

    - `"RUNNER_PHASE_DEGRADED"`

  - `variant: optional RunnerVariant`

    The runner's variant

    - `"RUNNER_VARIANT_UNSPECIFIED"`

    - `"RUNNER_VARIANT_STANDARD"`

    - `"RUNNER_VARIANT_ENTERPRISE"`

### Returns

- `runner: Runner`

  - `createdAt: optional string`

    Time when the Runner was created.

  - `creator: optional Subject`

    creator is the identity of the creator of the environment

    - `id: optional string`

      id is the UUID of the subject

    - `principal: optional Principal`

      Principal is the principal of the subject

      - `"PRINCIPAL_UNSPECIFIED"`

      - `"PRINCIPAL_ACCOUNT"`

      - `"PRINCIPAL_USER"`

      - `"PRINCIPAL_RUNNER"`

      - `"PRINCIPAL_ENVIRONMENT"`

      - `"PRINCIPAL_SERVICE_ACCOUNT"`

      - `"PRINCIPAL_RUNNER_MANAGER"`

  - `kind: optional RunnerKind`

    The runner's kind

    - `"RUNNER_KIND_UNSPECIFIED"`

    - `"RUNNER_KIND_LOCAL"`

    - `"RUNNER_KIND_REMOTE"`

    - `"RUNNER_KIND_LOCAL_CONFIGURATION"`

  - `name: optional string`

    The runner's name which is shown to users

  - `provider: optional RunnerProvider`

    The runner's provider

    - `"RUNNER_PROVIDER_UNSPECIFIED"`

    - `"RUNNER_PROVIDER_AWS_EC2"`

    - `"RUNNER_PROVIDER_LINUX_HOST"`

    - `"RUNNER_PROVIDER_DESKTOP_MAC"`

    - `"RUNNER_PROVIDER_MANAGED"`

    - `"RUNNER_PROVIDER_GCP"`

    - `"RUNNER_PROVIDER_DEV_AGENT"`

  - `runnerId: optional string`

  - `runnerManagerId: optional string`

    The runner manager id specifies the runner manager for the managed runner.
    This field is only set for managed runners.

  - `spec: optional RunnerSpec`

    The runner's specification

    - `configuration: optional RunnerConfiguration`

      The runner's configuration

      - `autoUpdate: optional boolean`

        auto_update indicates whether the runner should automatically update itself.

      - `devcontainerImageCacheEnabled: optional boolean`

        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.

      - `logLevel: optional LogLevel`

        log_level is the log level for the runner

        - `"LOG_LEVEL_UNSPECIFIED"`

        - `"LOG_LEVEL_DEBUG"`

        - `"LOG_LEVEL_INFO"`

        - `"LOG_LEVEL_WARN"`

        - `"LOG_LEVEL_ERROR"`

      - `metrics: optional MetricsConfiguration`

        metrics contains configuration for the runner's metrics collection

        - `enabled: optional boolean`

          enabled indicates whether the runner should collect metrics

        - `managedMetricsEnabled: optional boolean`

          When true, the runner pushes metrics to the management plane via
          ReportRunnerMetrics instead of directly to the remote_write endpoint.

        - `password: optional string`

          password is the password to use for the metrics collector

        - `url: optional string`

          url is the URL of the metrics collector

        - `username: optional string`

          username is the username to use for the metrics collector

      - `region: optional string`

        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: optional RunnerReleaseChannel`

        The release channel the runner is on

        - `"RUNNER_RELEASE_CHANNEL_UNSPECIFIED"`

        - `"RUNNER_RELEASE_CHANNEL_STABLE"`

        - `"RUNNER_RELEASE_CHANNEL_LATEST"`

      - `updateWindow: optional UpdateWindow`

        update_window defines the daily time window (UTC) during which auto-updates are allowed.
        If not set, updates are allowed at any time.

        - `endHour: optional number`

          end_hour is the end of the update window as a UTC hour (0-23).
          If not set, defaults to start_hour + 2.

        - `startHour: optional number`

          start_hour is the beginning of the update window as a UTC hour (0-23).
          +required

    - `desiredPhase: optional RunnerPhase`

      RunnerPhase represents the phase a runner is in

      - `"RUNNER_PHASE_UNSPECIFIED"`

      - `"RUNNER_PHASE_CREATED"`

      - `"RUNNER_PHASE_INACTIVE"`

      - `"RUNNER_PHASE_ACTIVE"`

      - `"RUNNER_PHASE_DELETING"`

      - `"RUNNER_PHASE_DELETED"`

      - `"RUNNER_PHASE_DEGRADED"`

    - `variant: optional RunnerVariant`

      The runner's variant

      - `"RUNNER_VARIANT_UNSPECIFIED"`

      - `"RUNNER_VARIANT_STANDARD"`

      - `"RUNNER_VARIANT_ENTERPRISE"`

  - `status: optional RunnerStatus`

    The runner's status

    - `additionalInfo: optional array of FieldValue`

      additional_info contains additional information about the runner,
      e.g. a CloudFormation stack URL.

      - `key: optional string`

      - `value: optional string`

    - `capabilities: optional array of RunnerCapability`

      capabilities is a list of capabilities the runner supports.

      - `"RUNNER_CAPABILITY_UNSPECIFIED"`

      - `"RUNNER_CAPABILITY_FETCH_LOCAL_SCM_INTEGRATIONS"`

      - `"RUNNER_CAPABILITY_SECRET_CONTAINER_REGISTRY"`

      - `"RUNNER_CAPABILITY_AGENT_EXECUTION"`

      - `"RUNNER_CAPABILITY_ALLOW_ENV_TOKEN_POPULATION"`

      - `"RUNNER_CAPABILITY_DEFAULT_DEV_CONTAINER_IMAGE"`

      - `"RUNNER_CAPABILITY_ENVIRONMENT_SNAPSHOT"`

      - `"RUNNER_CAPABILITY_PREBUILDS_BEFORE_SNAPSHOT_TRIGGER"`

      - `"RUNNER_CAPABILITY_LIST_SCM_ORGANIZATIONS"`

      - `"RUNNER_CAPABILITY_CHECK_REPOSITORY_ACCESS"`

      - `"RUNNER_CAPABILITY_RUNNER_SIDE_AGENT"`

      - `"RUNNER_CAPABILITY_WARM_POOL"`

      - `"RUNNER_CAPABILITY_ASG_WARM_POOL"`

      - `"RUNNER_CAPABILITY_PORT_AUTHENTICATION"`

    - `gatewayInfo: optional GatewayInfo`

      gateway_info is information about the gateway to which the runner is connected.

      - `gateway: optional Gateway`

        Gateway represents a system gateway that provides access to services

        - `name: string`

          name is the human-readable name of the gateway. name is unique across all gateways.

        - `url: string`

          url of the gateway

        - `region: optional string`

          region is the geographical region where the gateway is located

      - `latency: optional string`

        latency is the round-trip time of the runner to the gateway in milliseconds.

    - `llmUrl: optional string`

      llm_url is the URL of the LLM service to which the runner is connected.

    - `logUrl: optional string`

    - `message: optional string`

      The runner's reported message which is shown to users.
      This message adds more context to the runner's phase.

    - `phase: optional RunnerPhase`

      The runner's reported phase

    - `publicKey: optional string`

      public_key is the runner's public key used for encryption (32 bytes)

    - `region: optional string`

      region is the region the runner is running in, if applicable.

    - `supportBundleUrl: optional string`

      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.

    - `systemDetails: optional string`

    - `updatedAt: optional string`

      Time when the status was last updated.

    - `version: optional string`

  - `updatedAt: optional string`

    Time when the Runner was last udpated.

- `accessToken: optional string`

  deprecated, will be removed. Use exchange_token instead.

- `exchangeToken: optional string`

  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.

### Example

```http
curl https://app.gitpod.io/api/gitpod.v1.RunnerService/CreateRunner \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{}'
```

#### Response

```json
{
  "runner": {
    "createdAt": "2019-12-27T18:11:19.117Z",
    "creator": {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "principal": "PRINCIPAL_UNSPECIFIED"
    },
    "kind": "RUNNER_KIND_UNSPECIFIED",
    "name": "name",
    "provider": "RUNNER_PROVIDER_UNSPECIFIED",
    "runnerId": "runnerId",
    "runnerManagerId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "spec": {
      "configuration": {
        "autoUpdate": true,
        "continuousProfiling": true,
        "devcontainerImageCacheEnabled": true,
        "encryptedHoneycombApiKey": "U3RhaW5sZXNzIHJvY2tz",
        "logLevel": "LOG_LEVEL_UNSPECIFIED",
        "metrics": {
          "enabled": true,
          "includeVerboseMetrics": true,
          "managedMetricsEnabled": true,
          "password": "password",
          "url": "url",
          "username": "username"
        },
        "region": "region",
        "releaseChannel": "RUNNER_RELEASE_CHANNEL_UNSPECIFIED",
        "updateWindow": {
          "endHour": 0,
          "startHour": 0
        }
      },
      "desiredPhase": "RUNNER_PHASE_UNSPECIFIED",
      "variant": "RUNNER_VARIANT_UNSPECIFIED"
    },
    "status": {
      "additionalInfo": [
        {
          "key": "key",
          "value": "value"
        }
      ],
      "capabilities": [
        "RUNNER_CAPABILITY_UNSPECIFIED"
      ],
      "gatewayInfo": {
        "gateway": {
          "name": "name",
          "url": "url",
          "region": "region"
        },
        "latency": "+9125115.360s"
      },
      "llmUrl": "llmUrl",
      "logUrl": "logUrl",
      "message": "message",
      "phase": "RUNNER_PHASE_UNSPECIFIED",
      "publicKey": "U3RhaW5sZXNzIHJvY2tz",
      "region": "region",
      "supportBundleUrl": "supportBundleUrl",
      "systemDetails": "systemDetails",
      "updatedAt": "2019-12-27T18:11:19.117Z",
      "version": "version"
    },
    "updatedAt": "2019-12-27T18:11:19.117Z"
  },
  "accessToken": "accessToken",
  "exchangeToken": "exchangeToken"
}
```