Start the environment

Learn how to set up, start, and update your Kerno 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.

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

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.

Tip: This operation run in the background. Avoid asking your agent for status updates every few seconds. Just wait for it to confirm completion.

A "containers running" status alone is not enough. Wait until Kerno confirms the environment is ready for validation before moving on.

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.

Don't edit the files manually. Kerno will overwrite your changes the next time it updates the environment.

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.

What's next

Now that your environment is running, you're ready to capture your first baseline.

Resources

Support

Get help from the Kerno team.

FAQs

Get answers to common questions.

Security

Learn how Kerno handles your code and data.