---
layout: docs
page_title: Runner Configuration
description: |-
  Waypoint utilizes "runners" to execute Waypoint operations remotely. Runners can be configured to have environment variables and files exposed during certain project operations.
---

# Runner Configuration

Runners may require additional configuration such as cloud credentials,
Docker registry credentials, etc. Waypoint enables runners to be configured
with environment variables and files at runtime, either globally or specific
to certain environments.

## Environment Variables

### Via the CLI

You can set environment variables using [`waypoint config`](/commands/config-set)
with the `-runner` flag:

```shell-session
$ waypoint config set -runner AWS_ACCESS_KEY_ID=abcd AWS_SECRET_ACCESS_KEY=1234
```

This will expose these environment variables on every runner (including
the CLI when it runs operations locally). To unset any variables, assign it to
an empty value. You may view the set of runner configuration values using
`waypoint config get`:

```shell-session
$ waypoint config get -runner
```

~> **Security note:** These configuration values are stored as plaintext in the
Waypoint server. If you do not want to store any secrets on the Waypoint server,
you must set the environment variables manually when
[manually running the runner](/docs/runner/run-manual).

You can use the `-scope` flag paired with flags such as `-project`,
`-label-scope`, and `-workspace-scope` to set runner variables that are only
available within certain scoped situations. Variables are otherwise server
global by default.

### Via the `waypoint.hcl` File

Environment variables for runners can also be set via the `waypoint.hcl`
file. This uses the same syntax as the [`config` stanza](/docs/waypoint-hcl/config):

```hcl
config {
  runner {
    // All config in here is exposed only on runners.

    env = {
      AWS_ACCESS_KEY_ID = "abcd"
    }
  }

  // App config is here...
}
```

This configuration is scoped only to the project or application of
the `waypoint.hcl` file.

## Files

Using the `waypoint.hcl` file, you can configure files to be available
within runners for that project or application. You cannot configure files
to be available globally to the server. This behaves similarly to
[application configuration files](/docs/app-config/files).

```hcl
config {
  runner {
    file = {
      "config/config.json" = "file contents"
    }
  }

  // App config is here...
}
```

-> **Note:** The user that is running the runner must have permission to
write to the given file paths. File paths are not cleaned up after the
runner operation completes since we assume single-use runners.

## Dynamic Values

When using the `waypoint.hcl` format, runners may make use of
[dynamic values](/docs/app-config/dynamic) to source configuration
from external sources. The `runner` stanza also has access to
[internal values](/docs/app-config/internal) for composing multiple
values together.

Note that runner variables only have access to internal variables
specified within the `runner` stanza. Variables specified at the app-level
`config` stanza are not inherited.

For example, the following **is not valid**:

```hcl
// This is invalid!
config {
  internal = {
    "db_host" = "localhost"
    "db_user" = "admin"
  }

  runner {
    // This does not work because the "internal" variables were only
    // specified at the app-level, not the runner level.
    env = {
      "DB_ADDR" = "${config.internal.db_user}@${config.internal.db_host}"
    }
  }
}
```

## Runner profiles

To modify the way that Waypoint launches on-demand runners, see [runner profiles](/docs/runner/profiles).
