Logchef: one binary in front of the ClickHouse you already run

A control plane, not a new place to put your logs

Logchef is a lightweight, self-hosted log analytics and observability platform for teams that want a strong query and control plane on top of the log backends they already run. You can connect ClickHouse, VictoriaLogs, or both, and it gives you one workflow for exploration, dashboards, saved queries, alerting and access control, without moving or reshaping your data.

That last clause is the whole positioning. Logchef is not a log store, it is a workspace in front of one, and it is deliberately agnostic about the storage engine underneath. The repository description calls it a single-binary log analytics interface for ClickHouse, and the README calls it the open-source log workspace for ClickHouse and VictoriaLogs.

The query model follows from that. LogchefQL is the vendor-neutral query language, and when you need the native thing you can drop into SQL for ClickHouse or LogsQL for VictoriaLogs. The project says you can use the same LogchefQL search workflow across backends and drop into native LogsQL when you need it, carrying source-level auth, tenant headers and immutable scope through every query.

Those last three terms are the ones that matter for anyone running this in production. Tenant headers and immutable scope are about isolation between sources, and source-level auth is about credentials that are bound to a datasource rather than to the workspace as a whole. A log platform that cannot answer those questions is a toy, so their presence in the release notes is a signal about what kind of tool this is.

The implementation is Go, the licence is AGPL-3.0, and the homepage is logchef.app with a live demo at demo.logchef.app.

Version 2.0 turned a second backend into a first class citizen

The 2.0 release notes describe a major expansion of what Logchef can sit in front of, and the VictoriaLogs support is the headline.

Before 2.0, the natural assumption was that a Logchef deployment pointed at ClickHouse. Afterwards, VictoriaLogs is a first-class datasource with the same LogchefQL workflow, native LogsQL when needed, and per-source authentication, tenant headers and immutable scope carried through every query.

The second headline is dashboards that mix both backends on one grid. You can put ClickHouse panels and VictoriaLogs panels on the same dashboard, drag and resize them in place, and choose between time series, stat, breakdown and table views. A cross-backend dashboard is the thing that makes a two-backend estate bearable, because the alternative is two browser tabs and a mental join.

The third is live tail as an operational feature rather than a viewer. Live tail streams matching rows into the explorer and into the CLI on both backends, including native VictoriaLogs tailing.

Two smaller changes round out the release. The product can run without an identity provider, since built-in email and password authentication works on its own or alongside OIDC, and OIDC deployments can auto-provision new users safely. And the release adds what the notes call a broad security and reliability pass, with dashboard caching, ClickHouse query guardrails, opt-in rate limiting and streaming for large ClickHouse results.

The guardrails and rate limiting are the parts an operator should care about most, because they are the difference between a query interface that can melt a cluster and one that cannot.

Dashboards, scheduled alerts and a natural language query assistant

The feature list is arranged around the workflow rather than around components, which is a good sign for a tool meant to be used daily.

Exploration is query first: fast filtering with LogchefQL, plus native SQL or LogsQL depending on the source, and a live tail that streams matching logs in real time from the explorer.

Dashboards are multi-panel views, with time series, stat, breakdown and table panels sharing a time range and a direct-manipulation grid editor, so panels are dragged and resized rather than configured through a form.

Alerting is scheduled and source aware. The rules are evaluated against a source and notifications go out by email or webhook. Source awareness matters because a threshold that makes sense for one log stream may be meaningless for another, and a rule that does not know which backend it is talking to will either page you constantly or never.

Then there is the AI Query Assistant, which turns natural language into LogchefQL, ClickHouse SQL or LogsQL. The repository also depends on the OpenAI client and the AWS Bedrock runtime, so the assistant can run against either, and the MCP endpoint with OAuth sign-in lets an assistant in your IDE reach the same query surface.

The CLI completes the set, with syntax highlighting and multi-context support, covering query, explain, histogram, tail, doctor and more. Between the CLI and the MCP endpoint, an assistant can query logs without a human copying a query into a browser.

Access control that does not require an identity provider

The authentication story is described as OIDC or local auth plus RBAC. SSO out of the box, or run without an external identity provider using built-in email and password authentication.

That flexibility is unusual and it is the practical reason to consider this project at all in a small team. Self-hosted log platforms usually assume a company identity provider exists, and if yours does not, the usual outcome is that everyone shares one account and the audit trail is worthless. Logchef lets you start with local accounts and add OIDC later, and OIDC deployments can auto-provision new users safely, which removes the main reason to write a provisioning script.

The role model is not spelled out in detail in the README, so the practical advice is to read the documentation on logchef.app for how roles and permissions are scoped, and in particular whether a role is global or per source.

The dependency list gives a hint about the implementation. There are two OIDC libraries, coreos/go-oidc and zitadel/oidc, plus go-jose for token handling and the standard oauth2 and crypto modules, and the HTTP stack is Fiber v3 with the swaggo contrib for the API documentation. The sqlc.yaml file and the swaggo dependency together suggest generated database code and generated OpenAPI documentation, which is a good sign for a project whose API is meant to be consumed by other tools.

Deploying with Compose, Helm, or a single executable

The quickest path is a Compose file.

# Download the Docker Compose file
curl -LO https://raw.githubusercontent.com/mr-karan/logchef/refs/heads/main/deployment/docker/docker-compose.yml

# Start the services
docker compose up -d

The interface is then at http://localhost:8125.

For Kubernetes there is a chart in the deployment/helm directory, and it is more than just Logchef.

helm install logchef ./deployment/helm --namespace logchef --create-namespace

The chart covers Logchef, Dex and ClickHouse via the Altinity operator, so a cluster deployment can bring up an identity provider and the log store as well. The options and requirements live in the chart's values.yaml file.

The most interesting deployment fact is the metadata store. It is pluggable, with zero-config SQLite by default, and you can opt into Postgres for multi-replica high availability. That is the right default for the common case, one instance and one binary, and the right escape hatch for the case where you run more than one replica and need them to agree.

Everything else follows from the single binary claim: one executable and no runtime dependencies, plus Prometheus metrics for usage and performance. The goreleaser configuration at the root handles the release artefacts for both the server and the CLI.

The CLI and the MCP endpoint as first class surfaces

The CLI is a separate binary from the server, versioned separately, and the install instructions are explicit about the platform matrix.

CLI_VERSION="0.2.1"
BASE=https://github.com/mr-karan/logchef/releases/download/cli-v${CLI_VERSION}

curl -LO $BASE/logchef-cli_${CLI_VERSION}_macos-aarch64.tar.gz

There are builds for macOS on Apple Silicon and Intel, and for Linux on x86_64 and ARM64, the Linux ones being musl builds.

The command set covers the same ground as the UI, which is what you want from a terminal tool.

logchef auth --server https://logs.example.com
logchef query 'level="error"' --since 1h
logchef explain 'level="error"'
logchef histogram 'level="error"' --since 1h
logchef doctor

The explain command shows the generated SQL or LogsQL without running it, which is the fastest way to learn what a LogchefQL expression compiles to on a given backend. The histogram command draws counts over time as a terminal bar chart, which is enough for a lot of triage work without opening a browser. The doctor command diagnoses the setup, covering config, auth, server and defaults. And raw native queries go through the sql subcommand, taking SQL for ClickHouse and LogsQL for VictoriaLogs.

The MCP integration is the newer of the two surfaces. There is a built-in Model Context Protocol endpoint for AI assistants with OAuth sign-in, and the dependency on the mcp-go library is what makes it possible. Combined with the AI Query Assistant, it means an assistant can translate a question into a query and run it against your logs, which is a meaningful change in how incident triage feels.

Building from source: sqlc, a Bun frontend, and one Go binary

The Dockerfile is the clearest description of how the project is put together, and it is a three stage build.

The frontend is built with Bun on a debian base image, and the comment explains the unusual detail that Vite is configured to write its build output to a directory inside the Go source tree, so that the Go binary can embed it. The mirror of that layout in the build stage is there to make the resolved path land in the right place.

FROM oven/bun:1.4.2-debian AS frontend-builder

FROM golang:1.27-bookworm AS builder

The backend stage pins a sqlc version, downloads the sqlc binary rather than installing it with go install, installs the sqlite development headers, and then fetches the Go dependencies with a cache mount before copying the sources in. The build arguments are the version, the target OS and the target architecture, which is the standard goreleaser style matrix.

The Go module itself requires Go 1.27.0, and the dependency list shows the shape of the system: the ClickHouse driver and SQL parser, the Fiber web framework with the swaggo documentation tooling, pgx for Postgres, modernc.org/sqlite for the default metadata store, koanf for configuration with TOML, environment and file providers, golang-migrate for schema changes, the OIDC libraries, and the MCP and OpenAI clients for the assistant features. There is also a rust-toolchain.toml at the root, which suggests a small Rust component somewhere in the tree.

Development follows the same split, with the Justfile providing the sqlc-generate, dev-docker and build targets, and a just check target that contributors are asked to run before submitting. The repository also holds rfcs and plans directories, an AGENTS.md and a CLAUDE.md, and a renovate.json for dependency updates.

The licence is AGPL-3.0, with the text in the LICENSE file at the root, and the release cadence is brisk, with v2.4.0 on 2026-10-13 and the last push on 2026-10-19.

Editorial conclusion

Adopt Logchef when your team already stores logs in ClickHouse or VictoriaLogs and needs an exploration, dashboard and alerting layer on top without migrating the data, and when a single Go binary plus one container is what you want to operate. Do not adopt it if you need the logs to live somewhere other than those two backends, and think twice about the licence, because AGPL-3.0 reaches a modified service you host for others, which is exactly what a hosted log platform would be. Before the first deployment, decide whether your metadata store is SQLite or Postgres, since multi-replica high availability requires the latter, and pin the version you run, because the release line moved from 2.3 to 2.4 in the week before this review.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. mr-karan/logchef on GitHub
3. Project website
4. README
5. Releases