woodpecker/docs/versioned_docs/version-0.15/30-administration/15-agent-config.md

# Agent configuration

Agents are configured by the command line or environment variables. At the minimum you need the following information:

```yaml
# docker-compose.yml
version: '3'

services:
  woodpecker-agent:
  [...]
  environment:
+   - WOODPECKER_SERVER=localhost:9000
+   - WOODPECKER_AGENT_SECRET="your-shared-secret-goes-here"

```

The following are automatically set and can be overridden:

- WOODPECKER_HOSTNAME if not set, becomes the OS' hostname
- WOODPECKER_MAX_PROCS if not set, defaults to 1

## Processes per agent

By default the maximum processes that are run per agent is 1. If required you can add `WOODPECKER_MAX_PROCS` to increase your parallel processing on a per-agent basis.

```yaml
# docker-compose.yml
version: '3'

services:
  woodpecker-agent:
  [...]
  environment:
    - WOODPECKER_SERVER=localhost:9000
    - WOODPECKER_AGENT_SECRET="your-shared-secret-goes-here"
+    - WOODPECKER_MAX_PROCS=4
```

## Filtering agents

When building your pipelines as long as you have set the platform or filter, builds can be made to only run code on certain agents.

```
- WOODPECKER_HOSTNAME=mycompany-ci-01.example.com
- WOODPECKER_FILTER=
```

### Filter on Platform

Only want certain pipelines or steps to run on certain agents with specific platforms? Such as arm vs amd64?

```yaml
# .woodpecker.yml
pipeline:
  build:
   image: golang
   commands:
     - go build
     - go test
  when:
    platform: linux/amd64


  testing:
   image: golang
   commands:
     - go build
     - go test
  when:
    platform: linux/arm*


```

See [Conditionals Pipeline](../20-usage/20-pipeline-syntax.md#step-when---conditional-execution) syntax for more


## All agent configuration options

Here is the full list of configuration options and their default variables.
#### `DOCKER_HOST` 
> Default: empty 

Point to an alternate socket file or host. For example, "unix:////run/podman/podman.sock"

### `WOODPECKER_SERVER`
> Default: `localhost:9000`

Configures gRPC address of the server.

### `WOODPECKER_USERNAME`
> Default: `x-oauth-basic`

The gRPC username.

### `WOODPECKER_AGENT_SECRET`
> Default: empty

A shared secret used by server and agents to authenticate communication. A secret can be generated by `openssl rand -hex 32`.

### `WOODPECKER_LOG_LEVEL`
> Default: empty

Configures the logging level. Possible values are `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`, `disabled` and empty.

### `WOODPECKER_DEBUG_PRETTY`
> Default: `false`

Enable pretty-printed debug output.

### `WOODPECKER_DEBUG_NOCOLOR`
> Default: `true`

Disable colored debug output.

### `WOODPECKER_HOSTNAME`
> Default: empty

Configures the agent hostname.

### `WOODPECKER_MAX_PROCS`
> Default: `1`

Configures the number of parallel builds.

### `WOODPECKER_HEALTHCHECK`
> Default: `true`

Enable healthcheck endpoint.

### `WOODPECKER_KEEPALIVE_TIME`
> Default: empty

After a duration of this time of no activity, the agent pings the server to check if the transport is still alive.

### `WOODPECKER_KEEPALIVE_TIMEOUT`
> Default: `20s`

After pinging for a keepalive check, the agent waits for a duration of this time before closing the connection if no activity.

### `WOODPECKER_GRPC_SECURE`
> Default: `false`

Configures if the connection to `WOODPECKER_SERVER` should be made using a secure transport.

### `WOODPECKER_GRPC_VERIFY`
> Default: `true`

Configures if the gRPC server certificate should be verified, only valid when `WOODPECKER_GRPC_SECURE` is `true`.

### `WOODPECKER_BACKEND`
> Default: `auto-detect`

Configures the backend engine to run pipelines on. Possible values are `auto-detect` or `docker`.