---
layout: docs
page_title: Runners
description: |-
  Waypoint utilizes "runners" to execute Waypoint operations remotely. Runners are responsible for performing builds and deploys, polling projects for changes, and more.
---

# Waypoint Runners

Waypoint utilizes "runners" to execute operations. Every build, deploy, or
release operation happens on a Waypoint runner. Waypoint has three kinds of
runners:

### CLI Runner

When you trigger an action with the CLI, i.e. by running `waypoint deploy`, the CLI acts as a runner
capable of performing your operation. If your deployment needs AWS credentials, or a valid kubectl context,
it can access the credentials on the developer workstation that it's running on.

If you only use Waypoint from the CLI, this is the only kind of runner that is used.

### Remote Runner

Not every operation in Waypoint needs to happen in response to a CLI invocation
from a privileged workstation. Waypoint can trigger deployments from the UI or
automatically based on git changes, or automatically poll the status of
applications in the background. In these cases, Waypoint needs a "remote
runner", a long-lived runner that is always available to run these operations.

Waypoint automatically installs a single remote runner by default when the Waypoint
server is installed with [`waypoint install`](/commands/install).

### On-demand runners

While the remote runner is capable of performing operations on its own, it also
supports plugins to spawn on-demand runners for a given platform. These
on-demand runners are ephemeral container instances that perform one operation
before exiting. These on-demand runners can perform container builds without
any privileged access, offer more isolation between operations, and allow
Waypoint to scale further.

On-demand runners: see [on-demand runners](/docs/runner/on-demand-runner) for more information.

## Runner Targeting

Runner targeting allows users to configure Waypoint to target specific runners
to execute operations for an application. A runner `profile` can be specified
in the `runner` stanza in the `waypoint.hcl` file. The `runner profile` can be
configured to use a specific static runner, or multiple, based on labels.

### Runner Targeting Example

Runners can have labels applied to them with the `-label` flag provided
alongside the `waypoint runner agent` command.

```terminal
$ waypoint runner agent -label=org=hashicorp -label=env=dev
```

After the runner has started, it can be adopted by the server for use in remote
operations. With `waypoint runner list`, you can see the full list of available
runners and their labels.

```shell-session
$ waypoint runner list
              ID             |  STATE   |  KIND  |         LABELS         | LAST REGISTERED
-----------------------------+----------+--------+------------------------+------------------
  01G4N53X8DCJR3DJ9R56D6KZKH | pending  | remote | env:dev org:hashicorp  |

$ waypoint runner adopt 01G4N53X8DCJR3DJ9R56D6KZKH
Runner "01G4N53X8DCJR3DJ9R56D6KZKH" adopted.

$ waypoint runner list
              ID             |  STATE   |  KIND  |         LABELS         | LAST REGISTERED
-----------------------------+----------+--------+------------------------+------------------
  01G4N53X8DCJR3DJ9R56D6KZKH | adopted  | remote | env:dev org:hashicorp  |
```

With a runner that has labels applied, you can then create a runner profile to
target that runner (or runners). When this runner profile is used, Waypoint
will only generate on-demand runners using a runner whose labels match those
specified in the runner profile.

```terminal
$ waypoint runner profile set -name=docker-hashicorp-dev -plugin-type=docker -target-runner-label=org=hashicorp -target-runner-label=env=dev
✓ Runner profile created
```

```shell-session
                  NAME                  | PLUGIN TYPE |               OCI URL                |              TARGET RUNNER              | DEFAULT
----------------------------------------+-------------+--------------------------------------+-----------------------------------------+----------
  docker-hashicorp-dev                  | docker      | hashicorp/waypoint-odr:latest        | labels: {"env":"dev","org":"hashicorp"} |
```

In the `waypoint.hcl` file, you can specify the runner profile to use with the
`runner` stanza. In this example, a user variable "org" and the built-in
`workspace` variable are interpolated into the runner profile name, so that at
the time of execution of remote operations, Waypoint uses the desired runner
profile.

```hcl
project = "example-nodejs"

app "example-nodejs" {
  runner {
    profile = "docker-${var.org}-${workspace.name}"
  }

  build {
    # ...
  }

  deploy {
    # ...
  }

  release {
    # ...
  }
}

variable "org" {
  type = string
}
```

An operation which would use the runner profile created in this example could
be initiated with `waypoint build -w=dev -var=org=hashicorp -local=false`.

### Runner Targeting Advantages

The example above demonstrates basic usage of runner targeting. However, in a
production environment, runner targeting may be essential to achieving high
availability. Multiple runners could be deployed with the same labels, and
then a runner profile which targets runners with those labels would "round
robin" between the available runners. If one goes down, as long as another with
the same labels is still online, remote operations will continue to work.

Also shown in the above example is runner targeting for multi-environment
operations. The workspace of the operation dev, is interpolated into the runner
profile name dynamically at operation runtime. Additional runners and runner
profiles could be created for a "test" or "prod" environment so that a runner
can deploy to the right environment at runtime.

Runner targeting is useful for workflows where you deploy to multiple clusters
in a platform. For example, if you have a runner in one Kubernetes cluster,
that runner could potentially only perform remote operations within that
cluster. However, if there were a runner in multiple Kubernetes clusters, you
would have the ability to deploy to any of the clusters with Waypoint remote
operations by targeting the appropriate runners in each cluster.

## Disabling Runners

Runners can be disabled if desired. With runners disabled, Waypoint executes
all operations via the local CLI (even when communicating with a remote
[server](/docs/server)).

### Unavailable Functionality

With runners disabled, certain functionality becomes unavailable:

- Remote operations
- Git polling

In addition to disabled functionality, consider that all clients must now
have proper credentials for the target platforms (such as AWS, GCP, etc.)
since without runners they must execute all operations locally.

### Disabling Runner Installation

Prior to installation, runners can be disabled by specifying the
`-runner=false` flag to the [`waypoint install`](/commands/install) command.
This will not install a runner.

To uninstall a runner that is already installed, the only option today is
to uninstall and reinstall Waypoint with a
[data snapshot and restore](/docs/server/run/maintenance#backup-restore). You
may also manually go into your platform and delete the runner, but Waypoint
can't automate this for you today.

If there is a runner which you'd no longer like your server to use for remote
operations, this runner can be "invalidated" for use by the server with the
`waypoint runner forget` command, with the ID of the runner provided.
