Skip to content
NOEMATA

Quickstart

From an empty directory to a rendered frame in seconds, entirely from the CLI. 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 20+ and a terminal. The CLI manages the database and collector binaries for you.
  • Optional: Claude Code for controlling 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. It 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 project — pointing an app at Noemata’s collector means editing that app’s own config, such as ~/.claude/settings.json. The wizard lists the files it would write and asks once; declining records external_edits: false and keeps every write inside the project.
  • Pick an agent for the panel — where a coding agent is installed, whether the in-browser agent panel drives it.

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 — ClickHouse, the collector, and the app server — and reconciles your integrations and installed packs on every run. Installed packs are managed by default — reinstalled each run, so upgrades come for free; set collect.integrations.managed to false in noemata.json to take ownership of them and version-control them in git instead (see Integrations & packs). (noemata up 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.

The app is served at https://localhost:3210 (over HTTPS when TLS is mkcert or self-signed). Add --open to open it in your browser:

Terminal window
noemata up --open

Two packs are always installed: @noemata (its 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), installed whenever the project has a ClickHouse database.

Open a dashboard

In the app, press Cmd + K (or click the magnify icon in the header) to search installed frames, and open one — say the services or traces dashboard. It renders, but it’s empty until data arrives. Next, get some flowing.

Get live data flowing

You need telemetry in ClickHouse for a dashboard to show anything. Two ways:

  • Install the Claude Code integration (fastest). If you have the Claude Code CLI, let the wizard install its integration — Noemata collects Claude Code’s own telemetry and installs its dashboard, giving you live data with zero extra setup. Re-run noemata config to add it if you skipped it.
  • Point your own OTLP exporter at the bundled collector. Send OpenTelemetry traces, logs, and metrics to the collector at http://localhost:4318 (OTLP/HTTP) or localhost:4317 (OTLP/gRPC). For most SDKs, set OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318. See Send telemetry.

You’ll also find data you never sent: Noemata observes itself. The app server (as the noemata-server service) and the bundled OpenTelemetry collector both report their own telemetry into ClickHouse — request metrics, collector throughput, queue depth, and export health — so the OpenTelemetry dashboards show the stack’s own health from the moment it’s running, before any of your own data arrives.

Once data lands, reopen the dashboard — the frame queries ClickHouse and renders it.

Useful commands

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

Next