> For the complete documentation index, see [llms.txt](https://docs.lenses.io/latest/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lenses.io/latest/deployment/configuration/hq.md).

# HQ

This page describes how to configure HQ with its config.yaml file.

HQ reads its configuration from a single YAML file, **config.yaml**. On Linux, pass the file's path when you start HQ, for example `lenses-hq config.yaml`. The Docker and Helm installations provide the file for you; see [Installation](/latest/deployment/installation.md).

For every setting, its default and whether it is required, see the [Configuration Reference](/latest/deployment/configuration/hq/configuration-reference.md).

## License and EULA

Every configuration starts with the license. HQ does not start without a license key, or unless you accept the [Lenses EULA](https://lenses.io/legals/eula):

```yaml
license:
  key: license_key_...
  acceptEULA: true
```

## Example configuration

Only `license` and `database` are required; every other setting has a default. In practice you also need a way to log in, so this example adds an administrator with a password:

{% code title="config.yaml" %}

```yaml
license:
  key: license_key_...
  acceptEULA: true

database:
  host: postgres:5432
  database: hq
  username: hq
  password: $(HQ_DB_PASSWORD)    # Read from an environment variable.

auth:
  administrators:
    - admin                      # Full access for this user.
  users:
    - username: admin
      # bcrypt hash of "correcthorsebatterystaple". Use your own.
      password: $2a$10$F66cb6ZhnJjGCZuxlvKP1e84eytTpT1MDJcpBblHaZgsqp1/Aa0LG

http:
  address: :8080                 # UI and API. Default :8082.
  secureSessionCookies: false    # Needed while HQ is served over plain HTTP.

agents:
  address: :10000                # Where Agents connect. Default :10000.
```

{% endcode %}

With this file, the UI and API listen on port `8080`, Agents connect on port `10000`, and Prometheus metrics are served on port `9090`.

To create a password hash, see [Admin account](/latest/deployment/configuration/authentication/admin-account.md). To log in with your identity provider instead, see [SSO & SAML](/latest/deployment/configuration/authentication/sso-and-saml.md). Before you expose HQ, enable [TLS](/latest/deployment/configuration/hq/configuration-reference.md#tlsconfig) and set `secureSessionCookies` back to `true`.

## Read values from environment variables

HQ replaces `$(NAME)` anywhere in config.yaml with the value of the environment variable `NAME` before it reads the file. Use this to keep secrets, such as passwords and private keys, out of the file:

```yaml
database:
  password: $(HQ_DB_PASSWORD)
http:
  tls:
    enabled: true
    cert: $(HQ_TLS_CERT)
    key: $(HQ_TLS_KEY)
```

* Values that span several lines, such as PEM certificates, work when the placeholder is the whole value, as above.
* If the variable is not set, HQ leaves the text as it is and uses `$(NAME)` literally, for example as the password. Make sure every variable you reference is set.

## Check a configuration file

Test a configuration file without starting HQ:

```bash
lenses-hq test-config config.yaml
```

`test-config` checks that every required setting is present and that each value has the right type and format. A file that passes can still fail at startup, for example if two servers are set to the same address.

{% hint style="warning" %}
HQ ignores keys it does not recognise. A misspelled key does not cause an error; the setting keeps its default value.

To see the configuration HQ actually uses, set `logger.level` to `debug`. At startup, HQ logs it, with every default filled in and secrets redacted, in the message `The following configuration is used`.
{% endhint %}


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.lenses.io/latest/deployment/configuration/hq.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.