Project config (noemata.json)

noemata.json at the workspace root is a project’s source of intent — how its database, UI, telemetry, and file store are wired. The setup wizard (noemata init / noemata config) writes it, and you can hand-edit it afterward; noemata up materializes it into the concrete service configs it starts.

Every authored field is snake_case, and every field is optional — an empty {} is a valid config that the wizard fills in. Ports default to "auto", which resolves to a per-worktree offset off a standard base so parallel worktrees don’t collide.

This page is a map of the top-level shape. The exhaustive, always-current field list lives in the generated JSON Schema, which editors use for autocomplete and validation — see $schema below.

Top-level shape

{
  "$schema": "./.data/schemas/project.json",
  "db": { "clickhouse": { "binary": {} } },
  "app": { "local": { "port": "auto", "tls": "self-signed" } },
  "collect": { "integrations": {}, "collector": { "binary": {} } },
  "fs": { "remote": {} },
  "agents": { "claude_code": {} }
}

Field	Purpose
$schema	Relative path to the generated JSON Schema (see below). Auto-managed.
db	The database Noemata reads and writes.
app	How the Noemata UI is served.
collect	The bundled OpenTelemetry collector and its integrations.
fs	The file-store topology.
agents	Per-agent settings.

$schema

A relative path to a generated JSON Schema, written to .data/schemas/project.json on every config write. It gives editors autocomplete and validation for noemata.json. It’s auto-managed — the wizard writes it and strips it back out when it reads the config, so you don’t author it by hand.

db

The database. Today the only backend is ClickHouse, under db.clickhouse, and you pick exactly one of two shapes:

• binary — a managed local ClickHouse that Noemata downloads and runs (version?, http_port?, native_port?, max_memory_gb?, data_dir?).
• external — a ClickHouse you already run, including ClickHouse Cloud (hosts?, http_port?, native_port?); up connects but never manages it.

Both share authentication? ("none" — the default — or "password"), default_database? (default "default"), namespace? (the prefix for Noemata-owned tables, default "noemata"), request_timeout? (query timeout in seconds, default 60 — bounds the client request and the default server-side max_execution_time), and query_settings? (a passthrough map of ClickHouse settings for every dashboard query). See Connect a database for the full treatment.

app

How the UI server is served, as one of:

• local — served on this host. port is a literal number or "auto" (the default, resolved per worktree off 3210); optional tls is "mkcert" (browser-trusted), "self-signed" (encrypted with a browser warning), or "none" (plain HTTP).
• external — a UI hosted elsewhere (hosts).

collect

Telemetry collection, split into integrations and collector:

• integrations — which integrations and packs reconcile into the project. installed lists them by id; noemata and opentelemetry are required and reconcile whether or not they appear there. managed (default true) sets whether Noemata owns the installed frame packs — reinstalled and gitignored — or you do, seeded once and version-controlled; skills selects which detected editors receive the integrations’ skill packs (true installs to all, false to none, or name specific hosts); external_edits (default true) governs whether reconciliation may write to files outside the project root, such as an app’s own telemetry config — setup asks once when an enabled integration writes there and records a decline as false, so every later unattended up honours it. Per-integration settings key in by integration id under installed — for claude_code, redact_content keeps the telemetry stream metadata-only, and hooks.validate_frames_on_edit (offline (default), online, or none) controls the per-edit frame-validation hook written to the repo/workspace root’s .claude/settings.json.
• collector — the bundled OTel collector: binary (a managed local collector, with optional version, http_port, grpc_port) or external (hosts).

fs

The file-store topology — where the workspace’s files live and who owns them. Pick one:

• remote (default) — the server owns the store and the browser is the only client; nothing is mirrored to local disk.
• sync — the server owns the store, and a local directory mirrors it via the noemata sync daemon.
• local — the server reads and writes the workspace directory on disk directly (requires the server to run on the same host).

agents

Per-agent settings, keyed by coding agent (the tool, not the model) — e.g. claude_code. The CLI copies this block verbatim into the generated server config. Set it to false to record that the panel was offered and declined: setup then stops suggesting an agent, and no agents block reaches the server. Omitting the key entirely means “not decided yet”, so setup offers whichever agent it detects.

The agent panel drives the coding agent installed on the server’s host — claude_code runs the claude binary found on the server’s PATH, so the panel is offered only where that binary exists. Set executable_path to an absolute path where it is installed somewhere PATH won’t reach, such as a container image.

See also

• CLI commands — the init / config / up commands that write and apply this file.
• Connect a database — the full db.clickhouse reference.
• Connect data — collector, integrations, and telemetry setup.