> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Keeper-in-Server Mode

ClickHouse Keeper can run as a standalone process or embedded inside a ClickHouse Server process. This page explains what that means, why you might enable it, and what it implies for image management in an air-gapped environment.

## Modes of Operation

### Standalone (default)

Keeper runs as a separate process using the dedicated `clickhouse-keeper` image. It has its own lifecycle and image tag. This is the default configuration.

### Server-embedded

Keeper runs inside a `clickhouse-server` process. Keeper pods use the `clickhouse-server` image rather than the `clickhouse-keeper` image.

Server-embedded mode is the intended long-term default.

## Why Use Server-Embedded Mode

The main reasons to switch:

* **Unified image supply chain**: in server-embedded mode, both Server and Keeper pods pull from the same `clickhouse-server` image repository, reducing the number of images you need to manage and mirror.
* **Future compatibility**: new configuration capabilities and operational features are being added to server-embedded Keeper first.
* **HTTPS metrics for Keeper**: the `clickhouse-keeper` image does not expose port `8443`. Port `8443` is part of the ClickHouse Server HTTP stack, so it is only available when Keeper runs inside a server process. This is required to scrape Keeper metrics over TLS with Prometheus.

## Image Registry Considerations

In standalone mode your registry needs two distinct images:

| Image               | Tag          | Used by                |
| ------------------- | ------------ | ---------------------- |
| `clickhouse-server` | `26.2.1.704` | ClickHouse Server pods |
| `clickhouse-keeper` | `26.2.1.258` | ClickHouse Keeper pods |

In server-embedded mode, Keeper pods switch to the `clickhouse-server` image. Keeper and Server can run at different tags — `keeper.image.tag` is independent of `server.image.tag` — so your registry must contain the `clickhouse-server` image at each tag in use:

| Image               | Tag                   | Used by                |
| ------------------- | --------------------- | ---------------------- |
| `clickhouse-server` | `26.2.1.704`          | ClickHouse Server pods |
| `clickhouse-server` | `<keeper-server-tag>` | ClickHouse Keeper pods |

`<keeper-server-tag>` may equal `26.2.1.704` or be a different build. ClickHouse Private publishes a validated `clickhouse-server` build for each Keeper release — see the [versions reference](/docs/cloud/clickhouse-private/reference/versions) for the tag to use. Mirror both tags to your private registry before enabling this mode.

## Enabling Server-Embedded Mode

Set `keeper.featureFlags.runKeeperInServer: true` in your cluster Helm values

```sh theme={null}
helm upgrade <release-name> \
  oci://<your-registry>/helm-charts/onprem-clickhouse-cluster \
  --version <version> \
  --namespace <namespace> \
  --reuse-values \
  --set "keeper.image.tag=<keeper-server-tag>" \
  --set "keeper.featureFlags.runKeeperInServer=true"
```

The operator rolls out Keeper pods one at a time, preserving quorum throughout the migration.

## Related How-To Guides

* [Expose Keeper Metrics over HTTPS](/docs/cloud/clickhouse-private/how-to/setup-prometheus-monitoring#expose-keeper-metrics-over-https-optional) — step-by-step instructions to enable the HTTPS metrics endpoint using server-embedded mode