# Superlog: the install command points at another repository, and compose brings up databases rather than the app

> An open-core observability workspace for OpenTelemetry data, with traces, logs and metrics grouped into incidents and a community agent runner that records a local summary. The repository documents installation through a separate skills repository, and its compose file starts Postgres, ClickHouse and a collector rather than any of the four applications.

**superloglabs/superlog** — Open-source observability tool that uses AI agents to self-heal your software

- Repository: https://github.com/superloglabs/superlog
- Website: https://superlog.sh
- Stars: 1,454 · Forks: 117
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/superloglabs-superlog

## The install line points at a different repository

There is no pip, npm or docker one-liner for installing the product here. The installation section consists of a single instruction to paste into a coding agent:

```
Run npx skills add superloglabs/skills --all and use the skills to install Superlog in this project
```

The repository that command fetches is superloglabs/skills, not this one, and a third sibling, superloglabs/otel-helpers, is linked next to it in the header as Helpers. So the entry point is a skills bundle pulled by name, and the skill files decide where the code goes. A skills-lock.json sits at the root of this repository, which is the recorded state of that kind of install. The header also links an MCP server listing page, which places the project in a directory of model-context-protocol servers, and the manifest carries the modelcontextprotocol SDK among its development dependencies along with the Anthropic SDK.

## The default agent runner records a summary and stops

The file is explicit about what the free edition contains: the web app and API, an OTLP ingest proxy, worker processes for incident grouping and background jobs, the Postgres schema with ClickHouse-backed telemetry queries, interfaces for pluggable investigation runtimes, and one default runner named community. That last item is the important one. The community agent runner records a local incident summary, so the agentic behaviour in the project description, watching infrastructure while you sleep, depends on an investigation runtime that the community edition does not ship. The interfaces are there for it. The hosted alternative is named in the same paragraph: Superlog Cloud, with a free tier, a pay-to-go plan and monthly credit packs. Apache 2.0 covers this repository, and the manifest repeats it as the licence field with the package marked private and unpublished.

## Compose brings up Postgres, ClickHouse and a collector

The quick start reads as if one command starts the system, and it does not:

```bash
pnpm install
```

```bash
docker compose up -d
pnpm --filter @superlog/db db:migrate
pnpm dev
```

The compose file defines three services and none of them is Superlog. Postgres runs the 16 image with a named volume and a healthcheck that calls pg_isready every five seconds, ClickHouse runs the 26.1 server image with its own volume, a file descriptor limit of 262144 in both directions and a healthcheck that wgets the ping endpoint, and the OpenTelemetry collector contrib image 0.150.1 mounts a single configuration file from infra/collector/config.yaml as read only. The four applications come up afterwards through pnpm dev, which is a turbo task, so the stack you end up running is databases and an ingest proxy in containers plus Node processes on the host.

## ClickHouse runs with an empty password and access management on

The telemetry database is the part to look at twice:

```
CLICKHOUSE_PASSWORD: ""
CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: "1"
```

An empty password with the default user and access management enabled means the default account can create users and databases, and nothing in the file asks you to change it. The port mapping publishes both interfaces to the host, 8123 for HTTP and 9000 for TCP, either side overridable through environment variables but defaulted to the standard numbers. Postgres is not much better: the user is postgres, the password is postgres, the database is superlog, and 5434 is mapped to the container's 5432. Both are ordinary choices for a local development stack, and both become a problem the moment that stack is reachable from another machine. Nothing in the compose file restricts either service to the loopback interface.

## The collector waits for ClickHouse to be healthy

The three services are ordered properly, which is rarer than it should be. The collector declares a dependency on clickhouse with the condition service_healthy rather than service_started, so it does not attempt to write telemetry into a server that is still starting. Its environment points at tcp://clickhouse:9000 with the same superlog database and the same empty password, and it publishes the two standard OTLP ports, 4317 for gRPC and 4318 for HTTP, both overridable by environment variable. The configuration itself is one file mounted read only from the repository, so collector behaviour is versioned with the code rather than set through a wall of environment variables. What is not in the compose file is any exporter for traces to an external backend, an authentication layer in front of the OTLP ports, or a retention policy for the ClickHouse volume.

## A second local stack lives behind portless-stack.sh

Alongside the documented path there is another one that the README never mentions. Four scripts drive it: dev:portless runs portless-stack.sh start, and dev:portless:env, dev:portless:status and dev:portless:stop run the same script with env, status and stop. Two Procfiles sit at the root, Procfile and Procfile.portless, along with a server.json, which is the vocabulary used by PaaS-style process managers. The three documented local ports are web on 5173, API on 4100 and OTLP intake on 4101, and none of those is in the compose file, so the portless stack is a different topology rather than a variant of the same one. Around it sits a set of git-worktree helpers, bootstrap, seed, verify and gc, each a shell script, which is the shape a project takes when several agents or several branches need their own local database.

## Six demo seeds and one security test

The script list ends with a demo and test surface rather than a test suite. Six demo tasks run TypeScript files through tsx: bootstrap-acme, seed-acme-telemetry, seed-rich-telemetry, seed-everything, provision-demo-project and verify-demo-isolation. Three of those seed telemetry, one provisions a demo project, and the last checks that the demo data stays isolated, which reads like a guard against a seeded database leaking into a real one. Alongside them sits test:ci-workflows, a single test file run with the node test runner, scripts/ci-workflow-security.test.ts, so the automated checks visible in the manifest are one security test for the CI workflows plus typecheck through turbo. Linting and formatting are handled by Biome, with lint as biome check and format as biome format with write. The root also carries a ROADMAP.md, a SECURITY.md, a design.md, a specs directory and a blog directory, none of which the file explains.

## Conclusion

Superlog is a reasonable base if you want incident grouping over OpenTelemetry data with the storage decisions already made: Drizzle-managed Postgres for schema and ClickHouse for telemetry, with a collector in front. Three things to check before you build on it. Installation is documented through a separate skills repository, so the entry point is an instruction to your coding agent rather than a command you run here. The default agent runner named community only records a local incident summary, so the self-healing behaviour in the project description depends on a runtime you have not got yet. And the local compose file starts ClickHouse with an empty password and access management enabled, on host ports 8123 and 9000, which is fine on a laptop and not fine anywhere else. There are no GitHub releases, and the last commit on main is dated 2026-10-02.

## FAQ

### What is Superlog?

An open-source agentic telemetry system, described as an open-core observability workspace for OpenTelemetry data. It ingests traces, logs and metrics, groups noisy signals into incidents, and gives teams a local-first product surface for debugging production systems.

### How do I install Superlog into a project?

The file gives one instruction for a coding agent: run npx skills add superloglabs/skills --all and use the skills to install Superlog in the project. The skills come from a separate repository, superloglabs/skills, and a skills-lock.json at the root records that kind of install.

### What do I need to run Superlog locally?

Node.js 20 or newer, pnpm 9 or newer, and Docker. Then pnpm install, docker compose up -d, pnpm --filter @superlog/db db:migrate and pnpm dev. The documented local ports are 5173 for the web app, 4100 for the API and 4101 for OTLP intake.

### Which databases does Superlog use?

Postgres for the schema, with the Drizzle schema and migrations in packages/db, and ClickHouse for telemetry queries. The OpenTelemetry collector in the compose file writes into ClickHouse over tcp://clickhouse:9000 and waits for that service to report healthy first.

### Is Superlog fully open source or is there a paid tier?

This repository is the fully open-source community edition, containing the web app and API, the OTLP ingest proxy, workers, the database schema, ClickHouse-backed queries and agent runner interfaces with a default community runner that records a local incident summary. A hosted Superlog Cloud edition is offered separately with a free tier, a pay-to-go plan and monthly credit packs. The repository itself is Apache 2.0.

## Sources

- [Issues](https://github.com/superloglabs/superlog/issues)
- [License: Apache-2.0](https://github.com/superloglabs/superlog/blob/main/LICENSE)
- [Project website](https://superlog.sh)
- [README](https://github.com/superloglabs/superlog/blob/main/README.md)
- [superloglabs/superlog on GitHub](https://github.com/superloglabs/superlog)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/superloglabs-superlog