# Environment Setup

### What's in the environment

Three components run in your test environment.

* **Your application (SUT).** Kerno generates a Dockerfile and runs your app in a container, configured with the environment variables and startup sequence it detects from your codebase.
* **Real dependencies.** Postgres, MySQL, MongoDB, Redis, Kafka, RabbitMQ, and similar services run as real Docker containers with sensible defaults. See [Supported Technologies](/docs/references/supported-technologies.md) for the full list.
* **Sandbox.** External services your app calls (payment providers, email services, etc.) that cannot run locally are replaced with synthetic routes. The sandbox is also where test execution happens. All validations run here.

```mermaid
  %%{init: {"themeVariables": {"clusterBkg": "transparent", "clusterBorder": "#cccccc"}}}%%
  flowchart LR
      subgraph env["Test environment (Docker)"]
          APP[Your application - SUT]
          DB[(Postgres)]
          CACHE[(Redis)]
          QUEUE[(Kafka)]
          SANDBOX[Sandbox\nSynthetic routes + test execution]

          APP --> DB
          APP --> CACHE
          APP --> QUEUE
          APP --> SANDBOX
      end
```

Your environment includes the specific services Kerno detects in your codebase.

### The environment plan

Before building anything, Kerno analyzes your codebase and produces a plan. The plan covers the application's build and runtime configuration, every dependency the app needs, secrets with placeholder values for local dev, and any questions Kerno needs answered before it can proceed.

You or your agent review the plan, leave feedback, and Kerno regenerates it with your suggestions. Once you have no more feedback, Kerno starts building the environment.

You can also edit the plan directly at any time to add a missing service, change a port, or add context Kerno could not infer.

{% hint style="warning" %}
Do not edit the generated Compose files by hand. Kerno overwrites them on every regeneration.
{% endhint %}

### How the build works

Once the plan is approved, Kerno generates the Dockerfile and Compose files, builds the images, and starts the containers.

Build time depends on your stack. A simple project takes around five minutes. A complex one can take up to thirty minutes. This only happens the first time, subsequent runs start the\
environment instantly.

If something fails during the build (a service does not start, a port conflicts, a dependency is missing), Kerno surfaces what failed and asks you or your agent for help.

### Keeping the environment in sync

As your project evolves, Kerno keeps the environment current. When you change build files, Kerno re-analyzes your stack and updates the plan if needed. Review the updated plan and regenerate the Compose files to apply changes and rebuild.

{% hint style="warning" %}
Do not edit the generated Compose files by hand. Kerno overwrites them on every regeneration.
{% endhint %}

```mermaid
  flowchart LR
      A[Environment running] --> B[Build files change] --> C{Plan needs update?}
      C -->|yes| D[Review and rebuild]
      C -->|no| A
      D --> A
```


---

# 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:

```
GET https://kerno.gitbook.io/docs/core-concepts/environment-setup.md?ask=<question>
```

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.