> For the complete documentation index, see [llms.txt](https://kerno.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kerno.gitbook.io/docs/guides/start-the-environment.md).

# How to Configure the Kerno Test Environment

### Introduction

Kerno tests your application by calling it over HTTP against your real stack, which means it needs your app running at an address it can reach. You connect the two through your coding agent, which saves the configuration, points Kerno at your app, and confirms Kerno can reach it.

In this guide, you will connect Kerno to your application, give it access to your database, and confirm the environment is ready to test.

### Prerequisites

Before you begin, you will need:

* Kerno installed and the agent running, with your coding agent connected over MCP. See the [Quickstart](/docs/getting-started/quickstart.md).
* Docker running on your machine.

### Step 1. Index your app

Tell your agent to set up Kerno for your project:

```
Set up Kerno for this project.
```

Kerno analyses your repository, indexes your codebase, and analyses its endpoints. See Codebase indexing.

If your repository contains more than one app, Kerno shows you the ones it found and asks which to index. Pick the backend(s) you want to test.

### Step 2. Connecting your app

Kerno needs your app running before it can test it. Start it yourself, or ask your coding agent to start it for you, then point Kerno at it.

To have your agent start the app and connect Kerno in one go:

```
Start my app locally and set up the Kerno environment for it.
```

Or start the app yourself and tell your agent to connect Kerno to it:

```
Set up the Kerno environment for this app.
```

If your app runs somewhere else you can reach, such as a shared dev environment, give that URL instead.

Your agent saves the URL, and Kerno probes it from inside its sandbox to confirm it is reachable, so a wrong address is caught now instead of failing mid-test.

Kerno then reports whether the environment is ready. Your agent waits for `ready_for_endpoint_test` to report `true` before running any tests, and you can check at any time:

```
Check the Kerno environment status.
```

{% hint style="info" %}
Kerno reaches your app from inside its own sandbox, so bind your app to `0.0.0.0` rather than `127.0.0.1`. An app bound only to localhost is invisible to the sandbox, and running containers do not mean Kerno is ready, so wait for the readiness signal before generating tests.
{% endhint %}

### Step 3. Giving Kerno database access (optional)

Kerno tests in one of two modes, depending on how much access you give it.

* **Black box (default).** Kerno talks to your app only over HTTP, like any external client, and works entirely through your own endpoints.
* **White box.** Kerno also connects to your dependencies, such as your database, cache, or queue. This lets it set up state and verify results your API does not expose, like seeding a record that has no creation endpoint, or checking that a stored password was hashed.

To turn on white box, tell your agent to connect your dependencies. It works out the connection details from your project, so you do not need to give ports or URLs yourself:

```
Connect Postgres and Redis to Kerno.
```

Kerno also needs your database schema, which it derives from your source automatically for most projects. If it cannot, it pauses and asks you for a path rather than guessing.

Your credentials stay on your machine. Kerno records only the name of the environment variable each secret lives in, such as `DB_PASSWORD`, and reads the value when a test runs. 

### Step 4. Updating your configuration

Kerno stores your settings under `.kerno/` at your repository root:

```
.kerno/
├── config.yaml          # your local settings and credentials, gitignored
├── default.config.yaml  # team-wide defaults, committed
└── scenarios/           # generated tests, committed
```

`config.yaml` holds your local settings and credentials and is gitignored. `default.config.yaml` holds team-wide defaults and is committed, as are your generated tests under `scenarios/`.

You rarely edit these by hand. Your agent writes them and keeps them current as things change. If your app moves to a new port or a dependency changes, Kerno reports that it can no longer reach your app, and your agent works out the new details and saves them. You can also tell it directly:

```
My app moved to port 4000. Update the Kerno config.
```

### Next Steps

Your app is connected to Kerno and the environment reports ready. Kerno can now reach your app over HTTP, and if you gave it dependency access, it can set up and verify state directly as well.

Next, [capture a baseline](/docs/guides/capture-a-baseline.md). Kerno generates tests for your endpoints and runs them against your app to record how it behaves today, which becomes the reference every future change is checked against. Continue to Capture a baseline.