> 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).

# Start the environment

Before Kerno can validate your code changes, it needs a real local stack to run against. This guide walks you through setting up and starting your Kerno environment for the first time.

### Prerequisites

Before you begin, make sure you have:

* Kerno installed and running in your project directory. See [Quick Start](/docs/getting-started/quickstart.md).
* Your AI coding agent connected to Kerno via MCP.
* Docker running on your machine.

### Step 1 — Trigger environment setup

Ask your agent to set up the Kerno environment for your project:

> "Set up Kerno for this project."

Kerno analyzes your codebase to detect backend applications, services, and dependencies. This takes 1-2 minutes. When analysis is complete, Kerno generates a Docker Compose plan and presents it for your review.

### Step 2 — Review the compose plan

Kerno presents a plan before starting anything. The plan describes the services it will provision, the ports they will use, and any configuration it needs from you.

Read through the plan carefully. If something looks wrong or missing, ask your agent to adjust it:

> "Use port 5433 for Postgres instead of 5432." "Add a Redis service."

Iterate until the plan reflects your stack accurately.

```mermaid
flowchart TD
    A[Ask agent:\nset up environment] --> B[Kerno analyzes codebase]
    B --> C{Multiple apps?}
    C -->|Yes| D[Select backend app]
    C -->|No| E[Kerno generates\ncompose plan]
    D --> E
    E --> F[Review plan]
    F --> G{Approved?}
    G -->|No| H[Give feedback]
    H --> E
    G -->|Yes| I[Kerno builds\nand starts stack]
    I --> J[Environment ready]
```

### Step 3 — Approve and build

Once you are satisfied with the plan, approve it:

> "Looks good, go ahead."

Kerno builds the containers and starts the stack. The first build typically takes 5-30 minutes depending on the services involved. Subsequent starts are significantly faster.

During setup, Kerno may ask you questions if it needs clarification or runs into something it can't resolve on its own. Answer directly in the chat and Kerno will continue.

{% hint style="info" icon="lightbulb" %}
Tip: This operation run in the background. Avoid asking your agent for status updates every few seconds. Just wait for it to confirm completion.
{% endhint %}

{% hint style="warning" %}
A "containers running" status alone is not enough. Wait until Kerno confirms the environment is ready for validation before moving on.
{% endhint %}

After the environment is set up, Kerno writes the following files to your project:

```
  .kerno/
  ├── Dockerfile                           # your app's container image
  ├── docker-compose.yml                   # main orchestration compose
  ├── docker-compose.sut.yaml              # your app service
  ├── docker-compose.postgres.yaml         # one compose file per dependency
  ├── docker-compose.redis.yaml
  ├── docker-compose.ts-sandbox.yaml       # Kerno's test runner
  ├── .env                                 # shared environment variables
  ├── .env.postgres                        # one env file per service
  ├── .env.redis
  ├── synthetic-routes/                    # mocked third-party services
  └── analysis/
      ├── docker-compose-plan.md           # the plan you approved
      ├── build-analysis.md                # your build system, dependencies, startup sequence
      ├── external-services-analysis.md    # detected services and how to run them
      └── security-analysis.md             # auth setup and secrets
```

These files can be committed to version control.

{% hint style="warning" %}
Don't edit the files manually. Kerno will overwrite your changes the next time it updates the environment.
{% endhint %}

### Update the environment

Once your environment is running, you can update it at any time by asking your agent in plain language:

> "Use Postgres 16 instead of 14." OR "Change how authentication is handled in the environment."

Kerno will update the compose plan and present it for your approval before applying anything. Once you approve, Kerno restarts the stack with the new configuration.

### Keeping the environment up to date

Kerno keeps your environment in sync with your committed code. Each time you run validation or implement a baseline, Kerno checks if the codebase has changed and updates the environment automatically if it has.

```mermaid
  flowchart LR
      A[Commit code changes] --> B[Run validation or\nimplement baseline]
      B --> C{Code changed?}
      C -->|Yes| D[Kerno updates\nenvironment]
      D --> E[Operation runs]
      C -->|No| E
```

### What's next

Now that your environment is running, you're ready to [capture your first baseline](/docs/guides/capture-a-baseline.md).

### Resources

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-comment-question" style="color:$info;">:comment-question:</i> <strong>Support</strong></td><td>Get help from the Kerno team.</td><td><a href="https://discord.gg/UncXsxUz">https://discord.gg/UncXsxUz</a></td></tr><tr><td><i class="fa-lightbulb" style="color:$info;">:lightbulb:</i> <strong>FAQs</strong></td><td>Get answers to common questions.</td><td><a href="/pages/zJKOG1wiwndWnBdcDH4o">/pages/zJKOG1wiwndWnBdcDH4o</a></td></tr><tr><td><i class="fa-shield-check" style="color:$info;">:shield-check:</i> <strong>Security</strong></td><td>Learn how Kerno handles your code and data.</td><td><a href="/pages/a868OKb6TDxWBmJlCO1H">/pages/a868OKb6TDxWBmJlCO1H</a></td></tr></tbody></table>


---

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://kerno.gitbook.io/docs/guides/start-the-environment.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.