---
title: Configuration
---

Chronicle always runs as a **separate process** — the kernel — and your application talks to it as a **client** over gRPC. There is no in-process or embedded kernel to host inside your app, so on this side you're configuring *how your application connects and behaves as a client*. (To configure the kernel itself — ports, storage backends, features — see [Hosting Configuration](/chronicle/hosting/configuration/).)

## How client configuration flows

Every client setting can be supplied three ways, and they layer in this order — later wins:

1. **`appsettings.json`**, under the `Cratis:Chronicle` section — the usual home for the connection string and most settings.
2. **Environment variables**, with the `Cratis__Chronicle__` prefix (.NET maps the `__` separator onto nested keys) — convenient for containers and CI.
3. **Code**, via the `configureOptions` callback on `AddCratisChronicle` — it runs *after* binding, so it overrides configuration. Structural dependencies (custom resolvers and providers) can only be set here.

A minimal `appsettings.json`:

```json
{
  "Cratis": {
    "Chronicle": {
      "ConnectionString": "chronicle://localhost:35000",
      "EventStore": "my-store"
    }
  }
}
```

The matching registration on the host — `AddCratisChronicle` reads the section above, and the callback overrides it:

```csharp
builder.AddCratisChronicle(options => options.EventStore = "my-store");
```

`AddCratisChronicle` is an extension on the host builder — `IHostApplicationBuilder` for worker and console hosts, `WebApplicationBuilder` for ASP.NET Core. See the [getting-started host guides](/chronicle/get-started/) for the full setup of each.

## Topics

- [ChronicleOptions Reference](/chronicle/configuration/chronicle-options/) - Complete reference for all `ChronicleOptions`, `ChronicleClientOptions`, and `ChronicleAspNetCoreOptions` settings, including `appsettings.json` binding.
- [Connection Strings](/chronicle/connection-strings/) - The `chronicle://` connection string format, development defaults, and credentials.
- [Namespaces](/chronicle/namespaces/) - Resolve the event store namespace per request — the basis of multi-tenancy.
- [Camel Casing](/chronicle/configuration/camel-casing/) - Configure camel case naming policy for projection definitions and read model persistence.
- [gRPC Message Size](/chronicle/configuration/grpc-message-size/) - Configure maximum gRPC message sizes for large event batches.
- [Structural Dependencies](/chronicle/configuration/structural-dependencies/) - Configure artifact discovery, identity, namespace resolution, and other build-time dependencies via `ChronicleClient` constructor parameters or `IChronicleBuilder`.
- [TLS](/chronicle/configuration/tls/) - Configure client-side TLS options and certificate handling.

## Configuring the server

The kernel is configured separately from the client. See [Hosting Configuration](/chronicle/hosting/configuration/) for the `chronicle.json` file, environment variables, storage backends, and ports. To stand the kernel up locally, see [Run Chronicle locally](/chronicle/get-started/running-chronicle/).