The TensorZero Gateway can optionally collect inference and feedback data for observability, optimization, evaluation, and experimentation. Under the hood, TensorZero stores this data in ClickHouse, an open-source columnar database that is optimized for analytical workloads.
If you’re planning to use the gateway without observability, you don’t need to deploy ClickHouse.

​
Deploy

​
Development

For development purposes, you can run a single-node ClickHouse instance locally (e.g. using Homebrew or Docker) or a cheap Development-tier cluster on ClickHouse Cloud. See the ClickHouse documentation for more details on configuring your ClickHouse deployment.

​
Production

​
Managed deployments

For production deployments, the easiest setup is to use a managed service like ClickHouse Cloud. ClickHouse Cloud is also available through the AWS Marketplace, GCP Marketplace, and Azure Marketplace. Other options for managed ClickHouse deployments include Tinybird (serverless) and Altinity (hands-on support).
TensorZero tests against ClickHouse Cloud’s regular and fast release channels.

​
Self-hosted deployments

You can alternatively run your own self-managed ClickHouse instance or cluster. TensorZero supports single-node and replicated deployments. It currently does not support sharded deployments. See the ClickHouse documentation for more details on configuring your ClickHouse deployment.
TensorZero tests against ClickHouse 24.12 and latest. We recommend pinning a version (24.12 or newer). ClickHouse will occasionally introduce breaking changes and other issues (e.g. 25.8 had multiple regressions).

​
Configure

​
Connecting to ClickHouse

To configure TensorZero to use ClickHouse, set the TENSORZERO_CLICKHOUSE_URL environment variable with your ClickHouse connection details.
.env
TENSORZERO_CLICKHOUSE_URL="http[s]://[username]:[password]@[hostname]:[port]/[database]"

# Example: ClickHouse running locally
TENSORZERO_CLICKHOUSE_URL="http://chuser:chpassword@localhost:8123/tensorzero"

# Example: ClickHouse Cloud
TENSORZERO_CLICKHOUSE_URL="https://USERNAME:[email protected]:8443/tensorzero"

# Example: TensorZero Gateway running in a container, ClickHouse running on host machine
TENSORZERO_CLICKHOUSE_URL="http://host.docker.internal:8123/tensorzero"
If you’re using a self-hosted replicated ClickHouse deployment, you must also provide the ClickHouse cluster name in the TENSORZERO_CLICKHOUSE_CLUSTER_NAME environment variable.

​
Applying database migrations

The TensorZero Gateway typically applies database migrations automatically when it starts up. If you’re using a self-hosted replicated ClickHouse deployment, you must apply database migrations manually with gateway --run-migrations-only. In this case, the gateway will not apply migrations automatically, and will error on startup if migrations are missing.