Skip to content
NOEMATA

Quickstart

This page walks the whole path from install to a dashboard showing live data. Everything runs locally: the CLI downloads and supervises a ClickHouse database, an OpenTelemetry collector, and the app server on your machine — no external services required.

Prerequisites

  • Node.js 22.15 or newer, and a terminal.
  • macOS or Linux, on arm64 or x64. The CLI downloads the ClickHouse and OpenTelemetry collector binaries for you, and those are the platforms they are published for; on anything else noemata up reports the services it cannot install. Windows is not supported — use WSL. Autostart is macOS-only.
  • Outbound HTTPS to github.com and builds.clickhouse.com for the first run, which is when those binaries are fetched into ~/.noemata/bin and ~/.clickhouse/versions. Behind a proxy, set NODE_USE_ENV_PROXY=1 alongside HTTPS_PROXY so Node honours it, and point NODE_EXTRA_CA_CERTS at your CA bundle if the proxy terminates TLS.
  • Optional: Claude Code, if you want to control your agent from the app.

Install

Terminal window
npm install -g noemata@canary

noemata has no stable release yet, so @canary is the tag to install. This puts the noemata command on your PATH.

Create a project

In an empty directory, run:

Terminal window
noemata init

This scaffolds a project and opens a short setup wizard, which asks you to:

  • Pick a database — a managed local ClickHouse (the default, downloaded and supervised for you) or an external one you already run.
  • Pick a TLS mode — mkcert (a locally-trusted certificate, the smoothest local experience), self-signed, or none.
  • Install integrations — Noemata auto-detects software on your machine (for example the Claude Code binary) and offers to wire up telemetry collection and dashboards for it.
  • Allow edits outside the repository — Some integrations will update files outside the repository this project lives in. E.g., Claude needs to be configured to send telemetry to Noemata’s endpoint. The wizard lists the files it would write and asks once; declining records external_edits: false and keeps every write inside the repository. Declining external edits might mean your integration doesn’t work the way you’d expect it to.
  • Install the agent skills — when the project is a subdirectory of a repo, the skills that teach coding agents to drive Noemata install at its root, shared by every project in it. The wizard names the directories and asks; declining records skills: false.
  • Pick an agent for the panel — when a coding agent is installed, you can use it through the agent panel.

noemata config re-opens this wizard later if you want to change any of it.

Start the stack

Terminal window
noemata up

noemata up starts the services it owns — ClickHouse, the collector, and the app server — and reconciles your integrations and installed packs on every run. It also runs the wizard itself on the very first run, so you can skip noemata init and go straight here. Running bare noemata is equivalent to noemata up.

Installed packs are managed by default: reinstalled on each run, so upgrades come for free. Set integrations.managed to false in noemata.json to take ownership of them and version-control them in git instead (see Ownership & version control).

The app is by default served at https://localhost:3210 (over HTTPS when TLS is mkcert or self-signed), and opens in your browser automatically when you run from a terminal.

Two packs are always installed: @noemata (Noemata’s own content plus these docs, available in-app under @frames/@noemata/docs/) and @opentelemetry — the OpenTelemetry semantic layer and dashboards in one pack (services, traces, logs, and more), which is used by any integration that uses OpenTelemetry data.

Open a dashboard

Open the nav bar or press Cmd + K to navigate to an existing frame. Note that it might take a few seconds for data to come in after launching Noemata.

Get live data flowing

If you’re using integrations, they’ll automatically configure applications they monitor to send data to Noemata’s endpoint. Some applications you own will require you to configure Noemata as the OTLP endpoint. Noemata usually runs its collector at the 4318 (http) and 4317 (grpc) ports. Your application’s documentation or the OpenTelemetry website can help you configure Noemata as the OTLP endpoint for your app, but for many SDKs, setting OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 is enough. See Send telemetry.

Noemata by default will also send telemetry from the app to its collector, and you’ll be able to monitor the browser, server, the collector and the database in Noemata itself.

Useful commands

Terminal window
noemata status     # service health
noemata validate   # check frames render
noemata down       # stop the stack

Next