---
toc_max_heading_level: 3
---

# Agent

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

```ini
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_WORKFLOWS` if not set, defaults to 1

## Workflows per agent

By default, the maximum workflows that are executed in parallel on an agent is 1. If required, you can add `WOODPECKER_MAX_WORKFLOWS` to increase your parallel processing for an agent.

```ini
WOODPECKER_SERVER=localhost:9000
WOODPECKER_AGENT_SECRET="your-shared-secret-goes-here"
WOODPECKER_MAX_WORKFLOWS=4
```

## Agent registration

When the agent starts it connects to the server using the token from `WOODPECKER_AGENT_SECRET`. The server identifies the agent and registers the agent in its database if it wasn't connected before.

There are two types of tokens to connect an agent to the server:

### Using system token

A _system token_ is a token that is used system-wide, e.g. when you set the same token in `WOODPECKER_AGENT_SECRET` on both the server and the agents.

In that case registration process would be as following:

1. The first time the agent communicates with the server, it is using the system token
1. The server registers the agent in its database if not done before and generates a unique ID which is then sent back to the agent
1. The agent stores the received ID in a file (configured by `WOODPECKER_AGENT_CONFIG_FILE`)
1. At the following startups, the agent uses the system token **and** its received ID to identify itself to the server

### Using agent token

An _agent token_ is a token that is used by only one particular agent. This unique token is applied to the agent by `WOODPECKER_AGENT_SECRET`.

To get an _agent token_ you have to register the agent manually in the server using the UI:

1. The administrator registers a new agent manually at `Settings -> Agents -> Add agent`
   ![Agent creation](./new-agent-registration.png)
   ![Agent created](./new-agent-created.png)
1. The generated token from the previous step has to be provided to the agent using `WOODPECKER_AGENT_SECRET`
1. The agent will connect to the server using the provided token and will update its status in the UI:
   ![Agent connected](./new-agent-connected.png)

## Environment variables

### SERVER

- Name: `WOODPECKER_SERVER`
- Default: `localhost:9000`

Configures gRPC address of the server.

---

### USERNAME

- Name: `WOODPECKER_USERNAME`
- Default: `x-oauth-basic`

The gRPC username.

---

### AGENT_SECRET

- Name: `WOODPECKER_AGENT_SECRET`
- Default: none

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

---

### AGENT_SECRET_FILE

- Name: `WOODPECKER_AGENT_SECRET_FILE`
- Default: none

Read the value for `WOODPECKER_AGENT_SECRET` from the specified filepath, e.g. `/etc/woodpecker/agent-secret.conf`

---

### LOG_LEVEL

- Name: `WOODPECKER_LOG_LEVEL`
- Default: `info`

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

---

### DEBUG_PRETTY

- Name: `WOODPECKER_DEBUG_PRETTY`
- Default: `false`

Enable pretty-printed debug output.

---

### DEBUG_NOCOLOR

- Name: `WOODPECKER_DEBUG_NOCOLOR`
- Default: `true`

Disable colored debug output.

---

### HOSTNAME

- Name: `WOODPECKER_HOSTNAME`
- Default: none

Configures the agent hostname.

---

### AGENT_CONFIG_FILE

- Name: `WOODPECKER_AGENT_CONFIG_FILE`
- Default: `/etc/woodpecker/agent.conf`

Configures the path of the agent config file.

---

### MAX_WORKFLOWS

- Name: `WOODPECKER_MAX_WORKFLOWS`
- Default: `1`

Configures the number of parallel workflows.

---

### AGENT_LABELS

- Name: `WOODPECKER_AGENT_LABELS`
- Default: none

Configures custom labels for the agent, to let workflows filter by it.
Use a list of key-value pairs like `key=value,second-key=*`. `*` can be used as a wildcard.
If you use `!` as key prefix it is mandatory for the workflow to have that label set (without !) set and matched.
By default, agents provide four additional labels `platform=os/arch`, `hostname=my-agent`, `backend=my-backend` and `repo=*` which can be overwritten if needed.
To learn how labels work, check out the [pipeline syntax page](../../20-usage/20-workflow-syntax.md#labels).

---

### HEALTHCHECK

- Name: `WOODPECKER_HEALTHCHECK`
- Default: `true`

Enable healthcheck endpoint.

---

### HEALTHCHECK_ADDR

- Name: `WOODPECKER_HEALTHCHECK_ADDR`
- Default: `:3000`

Configures healthcheck endpoint address.

---

### KEEPALIVE_TIME

- Name: `WOODPECKER_KEEPALIVE_TIME`
- Default: none

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

---

### KEEPALIVE_TIMEOUT

- Name: `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.

---

### GRPC_SECURE

- Name: `WOODPECKER_GRPC_SECURE`
- Default: `false`

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

---

### GRPC_VERIFY

- Name: `WOODPECKER_GRPC_VERIFY`
- Default: `true`

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

---

### BACKEND

- Name: `WOODPECKER_BACKEND`
- Default: `auto-detect`

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

### BACKEND_DOCKER\_\*

See [Docker backend configuration](./11-backends/10-docker.md#environment-variables)

---

### BACKEND_K8S\_\*

See [Kubernetes backend configuration](./11-backends/20-kubernetes.md#environment-variables)

---

### BACKEND_LOCAL\_\*

See [Local backend configuration](./11-backends/30-local.md#environment-variables)

### Advanced Settings

:::warning
Only change these If you know what you do.
:::

#### CONNECT_RETRY_COUNT

- Name: `WOODPECKER_CONNECT_RETRY_COUNT`
- Default: `5`

Configures number of times agent retries to connect to the server.

#### CONNECT_RETRY_DELAY

- Name: `WOODPECKER_CONNECT_RETRY_DELAY`
- Default: `2s`

Configures delay between agent connection retries to the server.
