> For the complete documentation index, see [llms.txt](https://docs.copia.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.copia.io/docs/actions/updating-runners.md).

# Updating Runners

Runners keep themselves current in two ways:

* **Automatic updates** — an idle runner notices when Copia advertises a newer version, then downloads, verifies, installs, and restarts onto it with no operator action. This is on by default.
* **Manual updates** — the **Runners** page in Copia generates a copy-paste script that updates a specific runner in place. Use this when automatic updates are disabled, when a runner is on a build that can't self-update, or when you'd rather update on your own schedule.

## Automatic updates

When Copia advertises a newer runner release, each eligible runner downloads and installs it on its next idle check and restarts onto the new binary. Discovery and installation are fully automatic.

### When automatic updates run

A runner auto-updates only when **all** of the following are true. Otherwise it stays on its current version until you update it manually.

* Auto-update is enabled in config (`update.enabled`, the default).
* The runner was **not** registered with `--disable-auto-update`.
* It is a long-lived runner — not started with `--once` and not an ephemeral runner.

### Restart behavior

How the runner restarts depends on how it was started:

* **Foreground / daemon** — the runner drains any running job, then re-launches itself onto the new binary.
* **Windows service** — a detached helper stops and restarts the service through the Service Control Manager, which relaunches it as the freshly installed binary. See [Runner as a Windows Service](broken://pages/c1c5d7217135d5795ae9506cd701a49f0e817d6d).

### Configuration

Auto-update is tuned in the runner's `config.yaml`:

```yaml
update:
  # Turn background auto-update on or off. On by default.
  enabled: true
  # How often, while idle, to check for a newer version.
  check_interval: 1h
  # Allow moving to a different (older) version than the one running.
  # Default false: only strictly newer versions are installed.
  allow_downgrade: false
```

To disable auto-update for a runner at registration time instead, pass `--disable-auto-update` to `act_runner register`. This is persisted in the runner's `.runner` file and takes precedence regardless of config.

## Manual updates

From the **Runners** page in Copia, any runner running an older version than the latest release shows an **update available** banner. Click **Generate Update Script** to produce a script tailored to that runner's operating system and architecture. (If Copia can't determine the runner's platform, select the OS and architecture in the dialog first.) A runner already on the latest version shows no banner.

Run the generated script **from the directory where the runner was installed**. The script:

{% stepper %}
{% step %}

## Download

Downloads the correct release archive for the runner's platform.
{% endstep %}

{% step %}

## Verify

Verifies its SHA-256 checksum and extracts the new binary — all before touching the installed runner, so a bad download aborts while the current runner is still running.
{% endstep %}

{% step %}

## Stop

Stops the running runner and waits for it to exit.
{% endstep %}

{% step %}

## Replace and restart

Replaces the old binary and restarts the runner.

On Windows the script auto-detects whether the runner is installed as a Windows service. If it is, the script stops the service through the Service Control Manager (which drains in-flight jobs), overwrites the exact executable the service points to, and restarts it via SCM. Otherwise it uses the standard foreground flow.
{% endstep %}
{% endstepper %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.copia.io/docs/actions/updating-runners.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.