Quickstart

Three steps take a new tenant from empty to useful. Budget about five minutes plus however long introspecting your database takes.

Before you start

• An LLM API key for an OpenAI-compatible endpoint. This is what powers Chat, metric digests, and generated SQL. See Providers for self-hosting through your own gateway.
• Database credentials for a read-only account. SEMANTIX never writes to your data, but a least-privilege role keeps that guarantee on your side too.

Note

A new tenant starts completely empty — no providers, no data sources, no scopes. That is expected, and it is what these three steps fix. See what a new tenant starts with for the full picture.

Step 1 — Add an LLM provider

Go to Admin → Providers and add your model endpoint.

• Name — anything unique, e.g. openrouter-gpt.
• Base URL — your OpenAI-compatible endpoint, e.g. https://openrouter.ai/api/v1.
• API key — stored encrypted; it is never shown again after saving.
• Model — the model id your provider expects.
• Set as default — on for the provider Chat should use. Only one provider can be the default; setting a new one automatically clears the previous.

Caution

If Chat answers with Missing Authentication header or a 401, the stored key is not a valid key for that endpoint. This is almost always a pasted password or an API key from the wrong provider. See troubleshooting.

Step 2 — Create a context scope

Go to Admin → Entity Registry → Scopes and click New Scope.

Only a label is required. Optionally add a description, a colour, and up to three owners.

A scope is the unit that shapes everything else: it groups the entities and metrics a team cares about, determines what Chat can see in a scoped conversation, and gives that team a board to watch. People like Revenue, Build, or Retention — one per team or domain is a good start.

Step 3 — Connect a data source

Go to Admin → Connectors, pick the template matching your database, and fill in the connection details. PostgreSQL is the usual starting point.

For PostgreSQL you need host, port, database, username, and password. Set Visibility to all so analysts can use it, or admins to keep it to admins only.

All the database templates run through SEMANTIX’s own read-only SQL server. Only SELECT, WITH, EXPLAIN, SHOW, TABLE, and VALUES are permitted, and results are row-limited. See read-only by design.

Then introspect

Connecting a data source does not populate your Registry. Open Entity Registry → your connector and run Introspect. SEMANTIX lists the tables and columns it can see and creates entity records for them, which is what makes them findable, governable, and usable in Chat.

Tip

Introspection is the step people miss. Without it the connector is connected but the Registry is still empty, and Chat has nothing to ground its answers in.

What comes next

Three optional steps, in rough order of usefulness:

• Choose the SEMANTIX models. On the Providers page, pick the generation and embedding models SEMANTIX should use, then run Reindex embeddings if you change the embedding model. See Providers.
• Set trust and certify metrics. On an entity’s page you can set a trust level from 0–5, and metrics can be certified once you trust them. Certified metrics are what make the scope board useful. See entity trust.
• Invite users and grant scopes. Under Admin → Users, create accounts and grant each person a scope — including which one is their primary. Without a granted scope, someone logging in sees an empty app. See Users.

For people who are not admins

If an admin has not set this up yet, you will land on an empty Home page asking for a context scope. Ask an admin to grant you one — your default view, Chat context, and boards all follow your primary scope. You can change it later in Settings.