> 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/core-concepts/environment-setup.md).

# Environment Setup

Kerno connects to your running app and the services it depends on, so it runs tests against your real stack. That gives you high-fidelity results that reflect how your app behaves in production.

```mermaid
  %%{init: {"themeVariables": {"clusterBkg": "transparent", "clusterBorder": "#cccccc"}}}%%
  flowchart LR
      subgraph yours["Your environment"]
          APP[Your running application]
          DEPS[(Databases, caches,<br/>queues, auth)]
          APP --> DEPS
      end
      SANDBOX[Kerno sandbox<br/>runs the scenarios]
      SANDBOX -->|HTTP| APP
      SANDBOX -.->|optional read/write access| DEPS
```

### How Kerno connects to your application

Kerno connects to your running application, and optionally to the services it depends on.

Where your application runs takes one of two shapes.

* **`local`** — the application runs on your machine, reached at the URL it listens on, such as `http://localhost:3000`.
* **`remote`** — the application runs somewhere else you can reach, such as a shared dev environment.

Before relying on that address, Kerno probes it from inside its own sandbox, so an unreachable application is caught immediately rather than surfacing later as a confusing test failure. Kerno treats the environment as ready only once that check passes, and runs endpoint tests only against a ready environment.

Kerno can run tests in two modes, black box and white box.

#### Black box testing

In black box mode, Kerno tests your application entirely from the outside, like any external client. It talks to your application only over HTTP, and sets up and verifies everything through your own endpoints, with no direct access to your dependencies.

This sets two limits. Kerno will not generate tests that rely on direct database access, and it cannot validate side effects that are not visible through your API, such as confirming what your endpoint wrote to the database

```mermaid
  flowchart LR
      S[Kerno sandbox] -->|HTTP| A[Your application]
      A --> D[(Dependencies)]
```

#### White box testing

Kerno may additionally reach those dependencies directly, for the cases your API cannot express. Two common examples are seeding a record that has no creation endpoint, and confirming that a stored password is not the plaintext that was submitted.

```mermaid
  flowchart LR
      S[Kerno sandbox] -->|HTTP| A[Your application]
      A --> D[(Dependencies)]
      S -->|read/write| D
      linkStyle 2 stroke:#f59e0b,stroke-width:2px
```

With that access, Kerno handles the data layer for you, reading and writing your dependencies to establish the state a test needs and to verify what your endpoint actually persisted. That is the work you would otherwise write fixtures and teardown code for.

To enable it, provide connection details for the services your application depends on: its database, but also a cache like Redis, a queue like Kafka or RabbitMQ, object storage, or an auth provider like Zitadel. See [Supported Technologies](/docs/references/supported-technologies.md) for the full list.

Once dependency access is configured, runs use it by default. See [Testing modes](/docs/references/testing-modes.md).

### How Kerno reads your database schema

Credentials alone are not enough to write to your database: Kerno also needs to know its shape. It reads that from your source, never by introspecting your running database. A final-state snapshot such as `schema.rb`, a `*.prisma` file or `schema.sql` is used when present, otherwise Kerno reads your migrations.

Most projects work automatically. When a schema cannot be derived, Kerno pauses and asks you for a path or for the DDL rather than guessing, and reuses your answer on later runs. See [Environment setup issues](/docs/troubleshooting/environment-setup-issues.md).

### How Kerno authenticates to your endpoints

For each endpoint, Kerno analyses your authentication code and records the mechanism the route uses, how to present the credential, and which roles or scopes it requires. Because Kerno reads your actual authentication code, it can handle a wide range of schemes. Common ones include bearer tokens and JWTs, session tokens, API keys in a custom header, and OAuth 2.0

Where it can, Kerno gets the credential the way a client would, by calling your sign-up or login route. Where no such route exists, it seeds the credential directly in your datastore or identity provider, one of the cases direct access exists for.

Some endpoints require Kerno to construct the credential itself. It reads the exact claims your verifier enforces, including the audience and issuer from your own configuration, and mints a properly signed JWT using the signing secret you supplied. This is real authentication. Your application verifies the token exactly as it verifies production traffic.

{% hint style="info" %}
**Kerno never keeps your secret values**. It records only the name of the environment variable each secret lives in, such as `DB_PASSWORD`, and reads the value from your environment when a test runs.
{% endhint %}