> ## 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.
# Update Runner
> Updates a runner's configuration.
`Unary` ยท [`Runners`](/docs/api-reference/generated/runner/overview)
Updates a runner's configuration.
Use this method to:
* Modify runner settings
* Update release channels
* Change runner status
* Configure auto-update settings
### Examples
* Update configuration:
Changes runner settings.
```yaml theme={null}
runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
name: "Updated Runner Name"
spec:
configuration:
releaseChannel: RUNNER_RELEASE_CHANNEL_LATEST
autoUpdate: true
```
## Endpoint
```text theme={null}
POST /api/gitpod.v1.RunnerService/UpdateRunner
```
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/UpdateRunner" \
--header "Authorization: Bearer $ONA_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"runnerId": ""
}'
```
```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.UpdateRunnerRequest(
runner_id="",
)
response = ona.services.runner.update_runner(request)
print(response)
```
```typescript TypeScript theme={null}
import { create } from "@bufbuild/protobuf";
import { createClientFromEnv } from "@gitpod/sdk";
import { UpdateRunnerRequestSchema } from "@gitpod/sdk/gitpod/v1/runner_pb";
async function main() {
const ona = createClientFromEnv();
const request = create(UpdateRunnerRequestSchema, {
runnerId: "",
});
const response = await ona.services.runner.updateRunner(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.UpdateRunnerRequest{
RunnerId: "",
})
response, err := ona.Services.Runner.UpdateRunner(context.Background(), request)
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Msg)
}
```
```json Request body theme={null}
{
"runnerId": ""
}
```
## Request
`gitpod.v1.UpdateRunnerRequest`
| Field | Type | Required | Description |
| ---------- | -------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------- |
| `runnerId` | string | No | runner\_id specifies which runner to be updated. Constraints: `string.uuid=true`. |
| `name` | string | No | The runner's name which is shown to users Constraints: `string.max_len=127, string.min_len=3`. |
| `spec` | [Spec](#type-gitpod-v1-update-runner-request-spec) | No | |
## Response
`gitpod.v1.UpdateRunnerResponse`
This message has no fields.
## Related types
`gitpod.v1.UpdateRunnerRequest.RunnerConfiguration`
| Field | Type | Required | Description |
| ------------------------------- | -------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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 shared devcontainer build cache is enabled for this runner. |
| `updateWindow` | UpdateWindow | No | update\_window defines the daily time window (UTC) during which auto-updates are allowed. start\_hour is required. If end\_hour is omitted, it defaults to start\_hour + 2. Send an empty UpdateWindow (no start\_hour or end\_hour) to clear a custom window and allow updates at any time. |
| `honeycombApiKey` | string | No | honeycomb\_api\_key is the plaintext API key for Honeycomb tracing. The backend encrypts it with the runner's public key before storing. This is an internal-only field used for debugging. |
| `continuousProfiling` | boolean | No | continuous\_profiling enables continuous profiling on the runner. This is an internal-only field used for debugging. |
| `warmComputeEnabled` | boolean | No | warm\_compute\_enabled controls the runner's use of dynamically scaled instance and disk pools to reduce environment startup times. Omitting this field leaves the runner's stored preference unchanged. The preference only takes effect for supported runners when warm compute is available to the organization. |
`gitpod.v1.UpdateRunnerRequest.Spec`
| Field | Type | Required | Description |
| --------------- | --------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `configuration` | [RunnerConfiguration](#type-gitpod-v1-update-runner-request-runner-configuration) | No | |
| `desiredPhase` | [RunnerPhase](#enum-gitpod-v1-runner-phase) | No | desired\_phase can currently only be updated on local-configuration runners, to toggle whether local runners are allowed for running environments in the organization. Set to: - ACTIVE to enable local runners. - INACTIVE to disable all local runners. Existing local runners and their environments will stop, and cannot be started again until the desired\_phase is set to ACTIVE. Use this carefully, as it will affect all users in the organization who use local runners. |
| Value | Number | Description |
| ----------------------- | -----: | ----------- |
| `LOG_LEVEL_UNSPECIFIED` | 0 | |
| `LOG_LEVEL_DEBUG` | 1 | |
| `LOG_LEVEL_INFO` | 2 | |
| `LOG_LEVEL_WARN` | 3 | |
| `LOG_LEVEL_ERROR` | 4 | |
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. |
| 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 |