# Configuring Environments
Use an environment to represent one Kafka setup in Lenses. Each environment needs one Lenses Agent. The agent authenticates to Lenses with an `agent key`, then connects to Kafka and other services with a provisioning file.
{% hint style="info" %}
For the core model, see [Concepts](/latest/user-guide/getting-started/concepts.md).
{% endhint %}
## Before you start
Make sure you have:
1. access to Lenses
2. Kafka broker addresses
3. any Schema Registry, Kafka Connect, alerting, or monitoring endpoints you use
4. any TLS or mTLS `JKS` files
5. network access from the agent to each target service
## Create the environment
Open **Environments** from the left navigation. Select **+** in the header, or use the action on **Home**.
{% columns %}
{% column %}
{% endcolumn %}
{% column %}
{% endcolumn %}
{% endcolumns %}
Enter:
* environment name
* optional description
* tier, such as `dev`, `staging`, or `prod`
After you create the environment, copy the `agent key`.
{% hint style="info" %}
The `agent key` connects the agent to Lenses. It does not configure Kafka or any other service.
{% endhint %}
## Start the agent
Copy the startup command shown in the UI and run it where your agent will live.
{% hint style="warning" %}
The generated command assumes the default Lenses Docker Compose network. If you run the agent elsewhere, update hostnames, ports, and network routing to match your deployment.
{% endhint %}
## Configure service connections
When the agent appears, select **Start configuration**. You can also wait for the agent to connect first, then open the configuration tab.
If the agent starts with only an `agent key`, it connects to Lenses only. It does not connect to Kafka until you apply a provisioning file. For automation details, see [Provisioning](https://docs.lenses.io/latest/deployment/configuration/agent/automation). The schema is available in the [JSON schema repository](https://github.com/lensesio/json-schemas/blob/main/agent/provisioning.schema-6.1.json).
The configuration editor uses YAML. Use the left-side presets and toggles to insert starter blocks into the editor.
Select the connection type and preset that matches your setup. For example, Kafka over mTLS or Confluent Cloud. Then replace every placeholder value with real settings, such as broker addresses, usernames, ports, and secrets.
{% hint style="warning" %}
Fill in every required value before you test or apply. Use the editor problem panel to catch missing or invalid fields.
{% endhint %}
Some connection types support more than one entry. Common examples are Kafka Connect clusters and alert or monitoring integrations.
### TLS and mTLS files
If your services use TLS or mTLS, upload the required `JKS` files before you apply the configuration.
{% hint style="danger" %}
Uploaded file names must exactly match the file names referenced in the editor. For example, `kafka-truststore.jks`.
{% endhint %}
### Metrics and advanced settings
The presets do not cover every option. The placeholder YAML includes extra sections as comments. Uncomment and edit those blocks when you need metrics or advanced settings.
## Test the configuration
Select the beaker icon in the top-right of the editor to test the provisioning file. 
Lenses validates the file and shows errors in the editor and the problem panel.
## Apply the configuration
Select **Apply to Agent** when the test passes. Then open **Agent Logs** to follow startup and service connection status.
{% hint style="info" %}
Initial discovery can take a few minutes. Topics and optional services may appear gradually.
{% endhint %}
## Verify the environment
Confirm these checks after apply:
1. the agent shows as connected
2. Kafka appears in the environment
3. topics start loading
4. optional services, such as Schema Registry or Kafka Connect, appear if configured
5. **Agent Logs** show successful connections and no repeated errors
## Troubleshooting
If the environment does not connect, check:
1. the `agent key` is correct
2. broker addresses and ports are reachable from the agent
3. TLS or mTLS files are uploaded and named exactly as referenced
4. the YAML has no validation errors
5. credentials and secrets are valid
6. firewalls, DNS, and container networking allow access to each service
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.lenses.io/latest/user-guide/using/configuring-environments.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.