# Ask and trace
Source: https://opendash.cloud/docs/ask
> How to ask good questions, how the analyst chooses its path, and how to read an answer, its labels, its sources and its full trace.
## Ask [#ask]
Open **Ask**, or press `N` from anywhere. Ask the way you'd ask a colleague: *"What was MRR last month, by plan?"*
- **Enter** sends, **Shift+Enter** adds a line, **Esc** stops a run.
- While a run is working, anything you type is added to your question, and the analyst reads it before its next step.
- The **@** button points the analyst at something specific: a metric, dataset, guide, verified query, skill or dashboard. The paperclip, paste or drop adds a file or an image (text, CSV, HTML, PDF, PNG, JPEG). Up to five attachments, at most two of them images.
- The analyst reads every source you can read. Sample data is marked as such and never mixed with your own.
- Choose the **model**, **provider** and **thinking level** in the composer: Low, Medium, High, Extra or Max, as the model allows. Your choice is remembered in your browser.
- Ask a follow-up in the same conversation; the analyst keeps the context.
- **⌘J** (Ctrl+J) opens the analyst beside any other page, such as a dashboard you're looking at.
- Ask for a [dashboard](/docs/dashboards) and the analyst plans and builds one.
Viewers can read what's shared with them but can't ask. See [Workspaces and roles](/docs/workspaces).
## How the analyst answers [#how-the-analyst-answers]
The analyst searches your [knowledge](/docs/knowledge), then takes the most governed path that can answer:
1. **A verified query** that matches the question, used as a template (adapting the period, never replayed blindly).
2. **A metric query** over [approved definitions](/docs/semantic-layer).
3. **SQL over datasets.**
4. **Raw SQL over the tables**, as a last resort. It is labelled, and always cross-checked.
Every query goes through the query gateway: read-only, time-limited, and checked for the traps of each SQL dialect.
It can also read [connected services](/docs/connections) such as Jira. A call that would change something there shows exactly what it would send, and runs only when you press **Allow once**.
A run that reaches the workspace's [limit for one run](/docs/models#spend-limits) pauses and asks before it continues.
## Read the answer [#read-the-answer]
Under each answer: **Copy**, **Sources**, **Trace**, **Remember**, **PDF** (the answer as a PDF to send on), **Repeat…** (a [routine](/docs/routines) from it) and, on a metric answer, **Watch**. Every query the analyst ran in the conversation opens to its SQL and rows.
### Labels [#labels]
| Label | Meaning |
|---|---|
| **Metric** | Built from definitions an admin approved. |
| **Unmodelled** | SQL written over the tables. Cross-checked, but not from a governed definition. |
| **Unverified** | The answer gate couldn't check every number. The answer is still shown, so you can see why. |
| **Not answered from your data** | The analyst couldn't answer from the data, and says so instead of guessing. |
### Numbers [#numbers]
Every number is a link. Open it to see the query cell it references and **the records behind it**, the rows that make up the figure. **Download this page** saves them as CSV. Personal-data columns are hidden, and the panel says so.
If a number is wrong, use **This number is wrong** on it. See [Learning loop](/docs/learning).
### Sources panel [#sources-panel]
| Tab | What it shows |
|---|---|
| **Interpretation** | How the analyst read your question, including any reading it had to choose. |
| **Context** | The glossary terms, guides, definitions and skills it used. |
| **Queries** | Every query it ran, with the SQL. |
| **Checks** | What the answer gate checked, and the cross-check of the headline number. |
| **Couldn't verify** | Only when something failed: what the gate couldn't check. |
### Trace [#trace]
The trace shows the whole run: status, time, model calls, tokens (and how much was cached), cost, and a timeline of every model call and tool call. It is how you find out *why* an answer came out the way it did.
When an answer used the asker's personal memory, other readers see only the structure of the run.
## The answer gate [#the-answer-gate]
The model never types a number. It cites cells of recorded query results, and the gate:
- resolves each reference to its cell;
- recomputes derived values (differences, ratios, shares);
- checks the claims around the numbers;
- requires a cross-check for the headline number.
An answer that fails goes back to the analyst. If it still fails, it ships marked **Unverified**, never hidden and never silently "fixed".
## From the terminal [#from-the-terminal]
Developers can ask from the command line and watch the run as it happens:
```bash
pnpm ask "What was MRR last month, by plan?"
```
It prints the thinking, SQL, results, the gate's problems and the answer.
---
# Core concepts
Source: https://opendash.cloud/docs/concepts
> The few ideas the rest of the docs build on, from workspaces and sources to the answer gate and the learning loop.
## The big picture [#the-big-picture]
You connect a **source** to a **workspace**. The **analyst** answers questions from it, guided by your **knowledge** and **semantic layer**. Every answer passes the **answer gate** before you see it. When the analyst gets something wrong, your correction enters the **learning loop**, and once approved, the fix applies to everyone. Questions you come back to become **dashboards**, built by the analyst for a job, and **routines**, which run on their own.
## Glossary [#glossary]
| Term | Meaning |
|---|---|
| **Workspace** | An organization in OpenDash: its members, sources, knowledge and everything built from them. Data never crosses between workspaces. |
| **Project** | A group inside a workspace for sharing conversations and dashboards with some people rather than everyone. |
| **Source** | A database OpenDash reads through a read-only user: PostgreSQL, MySQL or ClickHouse. |
| **Catalog** | What OpenDash learned about a source: its tables, columns and profiles. |
| **Analyst** | The agent that answers questions. It searches your knowledge, runs queries through the gateway, and writes the answer. |
| **Run** | One turn of the analyst, with every model call, tool call and query recorded. Its **trace** shows all of it. |
| **Query gateway** | The only way queries reach a source: read-only sessions, time and row limits, per-dialect safety checks, personal-data columns never returned. |
| **Answer gate** | Deterministic code that resolves and recomputes every number in an answer. An answer it can't check is marked **Unverified**, never hidden. |
| **Dataset** | A YAML definition of a table or query: its grain, columns, measures, segments and relationships. |
| **Metric** | A named, governed number over a dataset's measure, such as MRR. |
| **Governed path** | The order the analyst tries: a verified query, then a metric, then SQL over datasets, then raw SQL (labelled **Unmodelled**). |
| **Glossary term** | What a word means at your company, optionally mapped to a column and values. |
| **Guide** | Markdown advice for the analyst, pinned to every question or found by search. |
| **Verified query** | A metric query an admin saved from a good answer, used as a template for similar questions. |
| **Skill** | A named, step-by-step procedure the analyst follows when it fits. |
| **Memory** | Short notes the analyst keeps for one person only, such as a preference. |
| **Proposal** | A suggested change to shared knowledge, from a correction. It is checked and tested, then approved or rejected. |
| **Dashboard** | A live page the analyst builds for one job, from named queries it runs as the viewer. A draft until its owner publishes it. |
| **Connected service** | A service such as Jira or HubSpot, connected over MCP, that the analyst and dashboards can read. |
| **Routine** | Something that happens on its own: on a schedule, or when a check finds something. |
| **Insight** | Something a routine found: an anomaly, a crossed line, a goal at risk, missing data. It can be investigated and turned into a task. |
## Two promises [#two-promises]
**Read-only.** OpenDash never writes to your databases. Each query runs in a read-only session with a server-side time limit, as the user you connected, and the connection check warns you if that user could change data.
**Every number is traceable.** If a figure appears in an answer, it came from a query result you can open. That's what makes it safe to forward an answer to someone who wasn't in the conversation.
---
# Connected services
Source: https://opendash.cloud/docs/connections
> Connect services such as Jira, HubSpot or Fullstory over MCP, so the analyst and your dashboards can read what lives only there, and change things only when you allow each call.
Some of what you need lives outside your database: tickets in Jira, deals in HubSpot, sessions in Fullstory. Owners and admins connect such services as **MCP servers**, and the analyst can then read them beside your data, and dashboards can show them.
## Add a server [#add-a-server]
Under **Settings → Connections**, press **Add an MCP server** and enter its address. OpenDash checks that it speaks MCP and how it signs in (OAuth sign-in, an API key, or no sign-in), and registers itself where the server allows it.
Then choose whose account it uses:
| Account | What people see |
|---|---|
| **Each person's own** (recommended) | Everyone connects their own account and sees only what it can see. |
| **One account for everyone** | One shared account, connected by an admin. Everyone sees the same data. |
## Tools [#tools]
Once connected, the server lists its tools. Each is marked **Reads** or **Changes things**, and an admin sets each one to:
- **Always**: used without asking;
- **Ask first**: each call is shown to the person before it runs;
- **Blocked**: never used.
Separate switches decide what dashboards may use: **Dashboards may read with it**, and for a tool that changes things, whether a dashboard may offer it as a row's button.
## Your connections [#your-connections]
**Settings → My connections** lists every server, grouped into **Needs you**, **Yours**, **Not connected yet** and **Shared with everyone**. Connect your own account to a server here, or disconnect it.
## What the analyst may do [#what-the-analyst-may-do]
- **Read** with the tools an admin allowed, as you: with your own account, or the shared one.
- **Change things** only when you allow it. The call is shown exactly as it would be sent, and runs only when you press **Allow once**. **Not now** skips it. A change is sent at most once, even across a restart.
- **Never delete or overwrite.** A tool that may do either (the server says so, or doesn't say it doesn't) is never called.
- Routines, runs nobody is watching, and dashboards only read. A dashboard's row buttons are the exception: each press is confirmed by the person pressing it, with their own account.
From Slack, the analyst uses only servers shared with everyone. A call that needs a sign-in or an approval asks you to allow it in OpenDash.
## Turning it off [#turning-it-off]
On a self-hosted instance, `OPENDASH_MCP=0` turns connected services off: Settings hides them, the analyst isn't offered them, and nothing calls a server. See [Configuration](/docs/self-hosting/configuration#connected-services).
---
# Dashboards
Source: https://opendash.cloud/docs/dashboards
> Describe who a dashboard is for and what they do with it. The analyst plans it, builds it while you watch, and every number on it stays a query you can open.
A dashboard in OpenDash is built by the analyst for one job: a revenue review, a renewals desk, a support queue to work through. You say who it's for and what they decide with it. The analyst shows a plan, builds the dashboard on its page while you watch, and checks it before it calls it done.
Each dashboard has its own layout, written for its job, instead of a grid of standard tiles. It reads your data only through named queries, and the server checks and runs every one of them as the person viewing.
## Build one [#build-one]
### Describe the job [#describe-the-job]
Open **Dashboards** and press **New dashboard**, or pick a start: *Customer health*, *Revenue review* or *A queue to work through*. Either opens the analyst beside the page with the request begun, for you to finish. You can also ask for one from any conversation: *"Build me a dashboard for the success team: who's at risk and who needs a call this week."*
Say who will use it and what they decide with it. A sketch or a screenshot of a dashboard you like helps: attach it to the question.
### Review the plan [#review-the-plan]
Before it builds anything, the analyst replies with a plan: what the dashboard is for, the data it reads, and each page with the pieces on it, in the order a reader meets them. The plan also says what your data lacks, and anything a row's button would change in a connected service.
Press **Build it**, or reply to change the plan. A plan you haven't built yet waits in the list as **Planned**.
### Watch it build [#watch-it-build]
The dashboard opens with the conversation beside it, and you watch it take shape. Every save is built and checked before it reaches the page: each query against your data, and the layout at phone, tablet and desktop widths. **Stop** keeps the last draft that passed.
### Publish [#publish]
What the analyst built is a **draft** that only you see. Look it over, then **Publish** it. If any of its queries read data no admin has verified (the analyst's own SQL, a definition not released yet, or a connected service), OpenDash lists them and asks you to confirm first.
## Change it [#change-it]
- **Continue** opens the conversation it was built in. Ask for the change there: *"add churn beside MRR"*.
- **Select** lets you click a piece of the dashboard to point the analyst at it, then describe the change in the panel beside it. **Esc** leaves.
- **⌘J** (Ctrl+J) opens the analyst beside the dashboard from anywhere on its page.
Changes go into the draft, and the published version stays as it is until you publish again. **Undo these changes**, under the answer that made them, puts the draft back as it was before that run, as long as nothing was saved over it or published since.
**Versions** keeps every published version. The owner can restore any of them.
## Read it [#read-it]
- **Every number opens its rows.** Click a figure to see the records behind it.
- **Each chart and table says where its numbers come from** in a quiet line beneath it, such as *Warehouse · Accounts*. Hover it to see whether the data is verified.
- **Filters** such as a period or a plan narrow the whole dashboard, and stay in the page's address, so a link opens with the same view.
- A dashboard can also hold a **written summary** of its numbers, which says what it's written from.
### Freshness [#freshness]
Each query runs as the viewer, under that person's access, through the same read-only query gateway as a question. Results are cached for up to five minutes.
## Work from it [#work-from-it]
A dashboard can be a place to get work done, not only to read:
- **Work on records.** A queue or a list can give each record an owner, a status, a note and a follow-up date. These are kept in OpenDash, never written to your database, with who changed what and when. Viewers can read them but not change them.
- **Act in a connected service.** A row can have a button that changes something in a [connected service](/docs/connections), such as *Move to Done* in Jira. Every press is confirmed on OpenDash's own dialog and runs with the presser's own account. Tools that may delete or overwrite are never used.
## Data it can read [#data-it-can-read]
A dashboard can read any of your sources, not only the one its conversation started on, and combine them, say tickets from one and accounts from another. In order of preference it uses:
1. a released dataset or metric (verified);
2. a dataset not released yet, its numbers marked **Unverified**;
3. the analyst's own SQL over the tables a source has learned;
4. a connected service, such as Jira or HubSpot, read live each time the dashboard opens.
Sample data never mixes with your own.
A dashboard reads a connected service only with the tools an admin allowed for dashboards. On a server where each person connects their own account, every viewer sees what their own account can see, and is asked to sign in first. On a server with one account for everyone, everyone sees the same data. See [Connected services](/docs/connections).
## Sharing [#sharing]
**Who sees it** sets who can open it: **Only you**, **Its project**, or **Everyone** in the workspace. **Specific people…** shares it by name, each to **View** or **Can edit**.
- Editors change the draft from their own conversations, and see the draft and the build the owner sees. Only the owner publishes, restores a version, changes sharing, or deletes it. Owners and admins can delete any dashboard.
- A shared dashboard shows each reader the data their own access allows.
- When someone leaves the workspace, their shares end.
## Export [#export]
Dashboards are read in OpenDash and aren't exported. To send numbers to someone, download an answer as a **PDF** from its conversation, or set up a [routine](/docs/routines).
---
# OpenDash documentation
Source: https://opendash.cloud/docs
> OpenDash is the open-source AI analyst for startup operators. Connect a read-only database, ask in plain language, and get answers where every number traces back to a query you can open.
OpenDash answers questions about your business from your own database. It differs from a chatbot over SQL in three ways:
- **Numbers are never typed by a model.** Every figure in an answer is a reference to a cell of a recorded query result, and a deterministic answer gate (code, not a model) recomputes it before you see it. Open any number to see the query and rows behind it.
- **It learns your business, under review.** Glossary terms, guides, metrics and verified queries teach it how your company talks. Corrections from your team become proposals that are checked, tested and approved before they apply to everyone.
- **It runs where your data is.** It reads PostgreSQL, MySQL and ClickHouse through read-only users, never writes, and self-hosts with one `docker compose up`.
OpenDash is in beta. We’re continuing to improve the product with user feedback.
## Start here [#start-here]
Run OpenDash locally with sample data and ask your first question in about ten minutes.
Deploy it on your own infrastructure with Docker Compose.
The handful of ideas the rest of the docs build on.
Point it at your database with a read-only user.
## What you can do [#what-you-can-do]
| | |
|---|---|
| [Ask and trace](/docs/ask) | Ask in plain language. Every number links to its query, the rows behind it, and the checks it passed. |
| [Datasets and metrics](/docs/semantic-layer) | A small YAML semantic layer, so "MRR" means the same thing in every answer. |
| [Knowledge](/docs/knowledge) | Glossary terms, guides, verified queries and skills that teach the analyst your business. |
| [Learning loop](/docs/learning) | Corrections become reviewed, tested learnings for the whole team. |
| [Dashboards](/docs/dashboards) | Describe the job, and the analyst builds a live dashboard for it, every number a query you can open. |
| [Connected services](/docs/connections) | Read Jira, HubSpot and other services over MCP, and change things only when you allow each call. |
| [Routines and insights](/docs/routines) | A Monday summary, a scheduled question, or a watch that tells you when a metric moves and why. |
| [Slack and email](/docs/slack) | Ask from Slack; get routines by Slack or email. |
| [Models and providers](/docs/models) | Use the deployment's model keys, or bring your own provider per workspace. |
## Open source [#open-source]
OpenDash is **Apache 2.0 licensed**, except the `ee/` directory (single sign-on, directory sync and the audit chain), which is source-available. Self-hosted builds send no telemetry.
The system on one page.
Issues, pull requests and the DCO.
The open accuracy benchmark.
Every page has a **Copy page** button for its Markdown source. [`/llms.txt`](/llms.txt) indexes all pages, and [`/llms-full.txt`](/llms-full.txt) has their full text.
---
# Knowledge
Source: https://opendash.cloud/docs/knowledge
> Glossary terms, guides, verified queries, skills and memory. What each one teaches the analyst, when it's used, and who can change it.
Knowledge is how OpenDash learns the way your business talks. It lives under **Knowledge** and comes in five kinds:
| Kind | Teaches the analyst | Used |
|---|---|---|
| **Glossary term** | What a word means at your company | On every question |
| **Guide** | How to approach a topic or a table | Pinned: every question. Otherwise when search finds it |
| **Verified query** | How a question like this was answered correctly before | When a question matches |
| **Skill** | A step-by-step procedure | When it fits the question |
| **Memory** | One person's preferences | That person's questions only |
Everything except memory is shared by the workspace, versioned, and changed only by **owners and admins**. Saving creates a new draft version; the released version keeps answering until the new one is approved.
## Glossary terms [#glossary-terms]
A term says what a word means here, and optionally which column and values it maps to:
```yaml
term: SMB
means: Small businesses, here accounts with up to 50 employees.
synonyms: [small business, small businesses, SMBs]
maps_to:
column: "public.accounts.employee_band"
values: ["1-10", "11-50"]
```
`maps_to` can also name a `metric`, and `not` lists tables the term must never be read from. A mapping is checked against the catalog. A term can apply to one source or to the whole workspace.
On DashBench, questions that only a company's own definitions settle ("SMB", "last fiscal quarter") went from 3 of 6 right to 6 of 6 with the glossary, in half the model calls. See [DashBench](/docs/open-source/dashbench).
## Guides [#guides]
A guide is Markdown advice: how your company counts churn, which table is the source of truth, what to watch out for.
- **Pinned** guides are in front of the analyst on every question (up to 1,500 characters).
- **Unpinned** guides (up to 8,000 characters) are found by search when relevant: by keyword, and by meaning when embeddings are on.
- A guide can be attached to a **table**, and is given to the analyst whenever it reads that table.
## Verified queries [#verified-queries]
When an answer took the metric path and is right, an owner or admin can save its query as a **verified query**, with the question and other ways of phrasing it. Saving is the review.
When a similar question comes in, the analyst gets the closest verified queries and follows one as a template, adapting the period rather than replaying it. Only metric queries can be verified, not raw SQL.
## Skills [#skills]
A skill is a named procedure: a one-line "use it when", and Markdown steps. The name and the "use it when" line are in front of the analyst on every question; it reads the steps only when the skill fits. One skill ships built in: **investigate-a-change**. The analyst also has its own reference skills for building [dashboards](/docs/dashboards), read only when it builds one.
## Memory [#memory]
Memory is personal: only its owner's questions use it, and only its owner sees it. The analyst saves a short note when you ask it to ("remember…", "from now on…"), correct it, or state a preference. Up to 50 notes are kept.
## Goals [#goals]
Under **Settings → Goals**, owners and admins set a target on a verified metric, with a due date and whether it's a floor or a ceiling. **Home** shows progress and a forecast, and a routine can alert you when a goal is at risk.
---
# Learning loop
Source: https://opendash.cloud/docs/learning
> How a correction from anyone on the team becomes a checked, tested and reviewed learning that applies to everyone, and when it's released without waiting.
When the analyst gets something wrong, fixing it once should fix it for everyone, without letting one person's mistake become the team's truth. The learning loop does both.
## 1. Someone corrects an answer [#1-someone-corrects-an-answer]
On any answer, choose **Helpful** or **Not right**, and say what was wrong: *A number is wrong*, *Wrong definition*, *Missing context*, *Misread the question*, or *Something else*. On a single figure, use **This number is wrong**.
A thumbs-down that says what was wrong is a **correction**. Right away:
- it's saved to that person's [memory](/docs/knowledge#memory), so their next questions use it;
- it's saved as a draft guide on the source, for an admin to look at;
- it opens (or joins) a **learning proposal** for the team.
Taking the thumbs-down back undoes all of it.
## 2. The proposal is checked and tested [#2-the-proposal-is-checked-and-tested]
The **Curator** drafts a glossary term from the correction and keeps it as a proposed version. Then two things run before anyone has to look:
- **A check**: a query that proves the term against your data.
- **A test**: one analyst run with the unreleased term, graded on what its queries actually read.
## 3. Approve, or let it release itself [#3-approve-or-let-it-release-itself]
Owners and admins review proposals under **Knowledge → Proposals** and on **Knowledge → Learnings**, and can choose **Make it a team learning**, **Edit** or **Not this**, and **Revert** one after it's released. Everyone else can **Suggest for the team**.
A proposal is released **without waiting** only when all five hold:
1. It is stated outright in the correction.
2. It is low-risk: a new term that touches no released metric, dataset or term, and that no approver edited.
3. Its check passed.
4. Its test passed and used the term.
5. It was said by an owner or admin, or by two different people who are owners, admins or members.
Otherwise it waits for an approver's single tap. In Slack, approvers get **Make this a team learning?** right in the thread.
Every learning is a new version of a knowledge item, with who proposed it and why. Revert takes it back.
## Evals [#evals]
Under **Knowledge → Evals**, owners and admins get one test case per verified metric and per verified query. Run them with **Run now** or nightly. A case passes when the answer's gate passed and it cites the expected numbers, so you know when a change to definitions or knowledge breaks something that used to work.
---
# Models and providers
Source: https://opendash.cloud/docs/models
> Which models OpenDash offers, how to use the deployment's keys or your own provider per workspace, and how spend limits work.
## Providers [#providers]
Every workspace can use two kinds of provider:
- **OpenDash's own provider**, which uses the deployment's keys. With a Vercel AI Gateway key, every allowed model runs through the gateway; otherwise each maker's own key runs its models. See [Configuration](/docs/self-hosting/configuration#models).
- **Your workspace's own provider**, set up by owners and admins under **Settings → AI**: Anthropic, OpenAI, Google Gemini, Amazon Bedrock, Google Vertex AI, Vercel AI Gateway or OpenRouter.
Provider keys are encrypted with the instance's key before they're stored, and never shown again.
## Models [#models]
OpenDash offers models from an allowlist, not every model a provider has. **Claude Sonnet 5.5** is the default.
| Model | Maker |
|---|---|
| Claude Sonnet 5.5 (default) | Anthropic |
| Claude Opus 5.5 | Anthropic |
| Claude Haiku 5.5 | Anthropic |
| Claude Fable 5.1 | Anthropic |
| GPT-6.1 Sol | OpenAI |
| GPT-6 Luna | OpenAI |
| Gemini 3.1 Pro (preview) | Google |
| Gemini 3.8 Flash | Google |
Each person picks the model, provider and **thinking level** per question in the composer. Claude models take Low, Medium, High, Extra or Max (High by default), GPT models Low, Medium, High or Max (Medium by default), and Gemini Low or High (High by default). The Claude models' scores on the golden set are in [DashBench](/docs/open-source/dashbench); OpenAI's and Google's aren't measured yet.
## Embeddings [#embeddings]
With an OpenAI key (the deployment's `OPENAI_API_KEY` or a workspace's own OpenAI provider), the worker embeds released knowledge and table names, so the analyst also finds guides and terms **by meaning**, not only by their words. Without one, nothing is sent and search is by words.
## Spend limits [#spend-limits]
Owners and admins set limits under **Settings → Usage**:
| Limit | Covers |
|---|---|
| **Monthly limit**, **Daily limit** (UTC) | Questions people ask. |
| **Background work** | Investigations, routines and drafting definitions. $10 a month by default; $0 turns it off. |
| **One run** | Each question or dashboard build. No ceiling by default; a run that reaches it pauses and asks to continue. |
A warning appears at 80% of a limit. Every run's trace shows its model calls, tokens and cost.
---
# Architecture
Source: https://opendash.cloud/docs/open-source/architecture
> The whole system on one page. What runs, how a question becomes a checked answer, and the design decisions that shape the code.
OpenDash is two application images and one stateful dependency. Your warehouse holds the analytical data; OpenDash keeps only what it needs to run (conversations, definitions, results and jobs) in PostgreSQL.
## Ideas that shape the code [#ideas-that-shape-the-code]
- **Numbers are references.** The agent cites cells of recorded query runs, and a deterministic answer gate resolves and recomputes every claim. No model decides whether a figure is right.
- **A governed path first.** A verified query, then a metric query, then SQL over datasets, and only then raw SQL, which is labelled and always cross-checked. Datasets and metrics compile to SQL through OpenDash's own compiler, which only joins many-to-one, so a fan-out can't inflate a number.
- **Context is versioned.** Glossary terms, guides, verified queries and skills have immutable versions. Anything learned from users reaches shared scope only through a proposal that is checked, tested and reviewed.
- **Durability lives in the data model.** The transcript in Postgres is canonical. The job queue is the only liveness authority, each attempt is fenced by its number, tool calls are recorded, and side effects go through an idempotent outbox. Long waits are rows, not sleeping jobs.
- **Postgres does everything stateful.** Data, search (full text, trigram and vectors), jobs and change notification. There is no other store to run.
- **Tenancy by construction.** Every tenant table is keyed by `(org_id, id)` with row-level security, and is reached only through `withTenant`, which sets the tenant for one transaction. The application role can't bypass it.
- **Only workers reach customer databases**, through vetted addresses, as read-only sessions with server-side time limits.
- **One engine, many surfaces.** The web app, Slack, routines and the API run the same agent loop.
## How a question is answered [#how-a-question-is-answered]
### The web app records it [#the-web-app-records-it]
`web` saves the message and the run, and puts the run on the queue.
### A worker runs the analyst [#a-worker-runs-the-analyst]
A worker claims the run, rebuilds the conversation from Postgres, and runs the agent loop and its tools: search over your knowledge, metric queries and SQL through the query gateway.
### The answer gate checks it [#the-answer-gate-checks-it]
Every number in the draft answer must reference a cell of a recorded query result. The gate resolves and recomputes each one. An answer that can't be checked is sent back, and ships marked as unverified if it still fails.
### The browser sees it live [#the-browser-sees-it-live]
Events are written to Postgres, announced with `NOTIFY`, and streamed to the browser over server-sent events.
**Dashboards** are code the analyst writes against a definition of named queries and filters. The code is drawn in a sandboxed frame on an origin of its own, so it never runs where an OpenDash session does. The frame asks for a query by its id; the server checks it, runs it as the viewer under row-level security, and caches the result by the complete bound query. **Routines** are found by a dispatcher when due, run their action, and send through the outbox once per person and channel.
## Repository layout [#repository-layout]
```text
apps/web Next.js UI, oRPC API, SSE, Better Auth, webhooks
apps/worker agent runs, connection checks, syncs, routines, delivery
packages/db Drizzle schema, RLS policies, partitions
packages/auth Better Auth setup, organizations, API keys, tenant resolution
packages/core tenancy, context, semantic compiler, query gateway, routines, learning, answer gate
packages/agent the agent adapter, profiles, tools, prompts
packages/api the typed API: contracts, the oRPC router and handlers, the client
packages/apps the sandboxed frame runtime dashboards are drawn in, its bridge and checks
packages/charts chart drawing for the page, PDFs and Slack images
packages/connectors PostgreSQL, MySQL and ClickHouse drivers, with per-dialect safety
packages/slack the Slack bot and replies
packages/email transactional and routine email templates
packages/markdown an answer's markdown, for the page and the PDF
packages/pdf answer PDFs
packages/ui the design system and its tokens
packages/tokens the design tokens as values, for email and server-drawn charts
packages/evals DashBench: generators, questions, graders
infra/ docker compose files, Caddy, the self-host smoke test
ee/ enterprise features (OCVSAL)
```
## Stack [#stack]
| Layer | Choice |
|---|---|
| Runtime | Node 24 · pnpm and Turborepo · Biome · Vitest |
| Web | Next.js 16 · React 19 · Tailwind 4 · HeroUI · oRPC |
| Auth | Better Auth (organizations, API keys) |
| Agent | AI SDK, with provider packages for Anthropic, OpenAI, Google, Bedrock, Vertex, OpenRouter and the Vercel AI Gateway |
| Documents | Apache ECharts · react-pdf |
| Data | PostgreSQL · Drizzle · pgvector · pg-boss |
| Integrations | Slack · Resend or SMTP for email · MCP servers for connected services |
---
# Contributing
Source: https://opendash.cloud/docs/open-source/contributing
> How to propose a change to OpenDash, what a pull request needs to pass, and how commits are signed off.
Contributions to the Apache 2.0 core are welcome: bug fixes, connectors, docs, tests and features. The `ee/` directory is maintained by the maintainers only.
## Before you start [#before-you-start]
- **Open an issue first** for anything larger than a small fix, so the approach is agreed before you spend time on it.
- **Read `AGENTS.md`** in the repository. It lists the rules the code follows (how numbers are checked, tenant isolation, durability, the agent runtime, the design system). Most of them are enforced by lint rules and tests.
- **Skim the [architecture](/docs/open-source/architecture)**. It is one page.
- Everyone taking part follows the **Code of Conduct** (`CODE_OF_CONDUCT.md`).
## Make a change [#make-a-change]
### Set up [#set-up]
Follow [Local development](/docs/open-source/development): Node 24, pnpm and Docker, then `pnpm dx`.
### Branch from `main` [#branch-from-main]
Keep the change focused. Follow the nearest existing example of the same kind of thing.
### Run what CI runs [#run-what-ci-runs]
```bash
pnpm lint && pnpm typecheck && pnpm test && pnpm build
```
### Measure accuracy changes [#measure-accuracy-changes]
Changing prompts, tools, retrieval, the compiler or the answer gate? Run `pnpm golden` (or `pnpm evals`) and put the score change in the pull request. These need a model key, so CI doesn't run them.
### Open the pull request [#open-the-pull-request]
Describe what changed and why, and link the issue.
A few more rules:
- New UI components go in `packages/ui`, with an entry in the `/dev/ui` gallery.
- A new runtime dependency must pass `pnpm check:licenses`. See [Dependencies](/docs/open-source/licensing#dependencies).
- Examples in code, tests, comments, docs and commit messages come from the demo company (`pnpm demo:seed`), **never from a real workspace**: no customer's company name, table or column names, dashboard titles or values.
## Sign your commits [#sign-your-commits]
OpenDash uses the [Developer Certificate of Origin](https://developercertificate.org/). Add a `Signed-off-by:` line to each commit:
```bash
git commit -s -m "fix(connectors): retry the ClickHouse connection check once"
```
There is no CLA. By contributing, you agree your work is licensed under the Apache License 2.0.
## What CI checks [#what-ci-checks]
Every pull request and push to `main` runs, against a pgvector Postgres:
| Check | What it covers |
|---|---|
| `pnpm lint` | Biome, including the design-system and raw-database rules |
| `pnpm typecheck` | Strict TypeScript across the workspace |
| `pnpm check:licenses` | Every dependency's license against the allowlist |
| `pnpm test` | Unit tests, the tenancy suite (every tenant table has its policies; cross-organization access is denied), theme contrast |
| `pnpm build` | Every package and the web app |
| `pnpm check:links` | Relative links in the Markdown files |
A second workflow builds both images and runs the self-host smoke test: the full stack with Caddy, setup, health over HTTPS, the sign-in page, the worker, and a sign-up through a mail sink.
## Reporting bugs and security issues [#reporting-bugs-and-security-issues]
- **Bugs and feature requests:** GitHub issues, with your version, how you run OpenDash, and steps to reproduce.
- **Vulnerabilities:** never in a public issue. See [Report a vulnerability](/docs/open-source/security#report-a-vulnerability).
---
# DashBench
Source: https://opendash.cloud/docs/open-source/dashbench
> OpenDash's open accuracy benchmark and regression gate. How it's built, how answers are graded, how to run it, and the v0 baseline.
Every accuracy technique in OpenDash (the semantic layer, verified queries, repair loops, the answer gate, the learning loop) is only real if it can be measured. DashBench measures it, and it is built to be **published openly**: a reproducible alternative to vendor-run BI benchmarks, whose questions, schema, transcripts and rubric aren't public.
## Principles [#principles]
1. **Grade results, not SQL text.** A case passes when the answer's numbers match the reference result within tolerance, however the SQL was written.
2. **Every number must be cited.** A number that doesn't come from a query run never passes.
3. **Ambiguity is a skill.** Cases test sensible defaults, saying which reading was chosen, asking when it matters, and refusing when a question can't be answered from the data.
4. **Held-out phrasings.** Every question has a wording written by an outside author and never shown to the analyst, so the benchmark measures generalization rather than memorization.
5. **Measure the semantic layer's lift.** Runs with and without definitions show what the semantic layer is worth.
6. **Reproducible.** Seeded generators, fixed dates and pinned engines. Anyone can regenerate the data and re-run it.
## What's in v0 [#whats-in-v0]
72 questions on `dash-saas`, a generated B2B SaaS company with the traps real data has: trials, mid-month plan changes, refunds and credits, several currencies, test accounts, churn versus pause, and seats.
| Group | Questions | What it tests |
|---|---|---|
| Metric path | 17 | Dimensions, filters and periods over approved metrics |
| SQL over tables | 16 | Questions no metric covers |
| Readings and refusals | 6 | Ambiguous words, missing data, forecasts, personal data |
| Glossary | 6 | Words only the company's own glossary settles |
| Search | 3 | Rules only a guide holds, asked without the guide's words |
| Dialect traps | 3 | ClickHouse merges, integer division on Postgres, `FILTER` on MySQL |
### Grading [#grading]
Expected values come from reference SQL run on the seeded data at grading time. An answer passes when its cited values match (counts exactly, amounts within 0.5%) **and** its answer gate passed.
**Must-never failures** fail the run regardless of score: a typed number, an external effect without approval, a cross-tenant leak, raw SQL presented without the *Unmodelled* label, or a held-out phrasing leaking into the analyst's context.
## The v0 baseline [#the-v0-baseline]
Recorded on 2026-10-10 and 2026-10-11, with `claude-sonnet-5-5` and the demo company's definitions approved:
| Run | Right | Untraced |
|---|---|---|
| Postgres, 60 questions (×2) | 60/60 | 0 |
| ClickHouse, 60 questions | 60/60 | 0 |
| MySQL 8.4, 66 with the glossary | 66/66 | 0 |
| Postgres, 69 with the glossary, guides and vectors | 69/69 | 0 |
| Postgres, 66 **held-out** wordings | 65/66 | 0 |
The one held-out miss was a gap in the knowledge, not the wording: two columns could answer "paid seats", and no metric settled which. A governed metric was added, and both wordings now take the metric path. That question's held-out wording no longer counts as blind.
**What it doesn't show yet:** one dataset of three, one held-out wording per question, and no nightly run (CI has no model key). The `dash-plg` and `dash-commerce` datasets, about 200 questions, more held-out wordings and the nightly job come next. The full record, every run, is in `docs/evals/DASHBENCH.md` in the repository.
### By model [#by-model]
The 21-question golden set, with definitions and the glossary, on each Anthropic model the registry lists. OpenAI's and Google's models aren't measured yet.
| Model | Right | Cost for the set |
|---|---|---|
| Claude Sonnet 5.5 | 21/21 | $0.30 |
| Claude Haiku 5.5 | 21/21 | $0.02 |
| Claude Opus 5.5 | 21/21 | $0.67 |
| Claude Fable 5.1 | 21/21 | $1.91 |
The golden set doesn't separate them on correctness; cost and speed do. A harder set is what will show where the stronger models earn their price.
## Run it [#run-it]
```bash
pnpm demo:seed # the dataset
pnpm golden # 21 questions, about 90 model calls
pnpm evals # all 72, on a fresh database
```
Useful flags for `pnpm evals`:
| Flag | Runs |
|---|---|
| `--subset pr` | 10 stable, cheap questions |
| `--subset glossary`, `--subset search`, `--subset traps` | One group |
| `--dialect clickhouse` | Against ClickHouse (or `mysql`) |
| `--wording holdout` | The held-out wordings (`--wording n` for the n-th other wording) |
| `--without metrics` | Schema only, no definitions |
| `--without glossary,guides,vectors` | Without one or more kinds of knowledge, to measure their lift |
| `--model id` | Another model (the default is Claude Haiku) |
| `--only id,id` | Specific questions |
"Today" is pinned to 2026-10-10, so "last month" means September 2026 on any date. Reports go to `packages/evals/reports/`.
If your pull request changes prompts, tools, retrieval, the compiler or the answer gate, run `pnpm golden` or `pnpm evals` and include the score change.
## What will be published [#what-will-be-published]
The generators and seeds, the questions and phrasings, the reference SQL, the graders and the harness, and results per release. Code under Apache 2.0, data under CC BY 4.0. Third parties can submit runs with transcripts. Only a rotating holdout stays private, so published scores stay meaningful.
---
# Local development
Source: https://opendash.cloud/docs/open-source/development
> Run OpenDash from source on your machine, seed sample companies to ask about, and the commands you'll use every day.
## Prerequisites [#prerequisites]
| Tool | Version | Notes |
|---|---|---|
| Node.js | 24 LTS (`.nvmrc`) | `nvm use` |
| pnpm | pinned in `packageManager` | Run `corepack enable` once |
| Docker | Compose v2 | Postgres 17 with pgvector on `127.0.0.1:5444` (5432 is often taken) |
| git | any recent | Commits are signed off (`git commit -s`) |
## First run [#first-run]
```bash
corepack enable && pnpm install
cp .env.example .env.local # set BETTER_AUTH_SECRET and OPENDASH_KEK: openssl rand -base64 32 for each
pnpm dx
```
`pnpm dx` checks your setup, starts Postgres, creates the database roles, runs migrations (which also install the job queues), and starts the web app and the worker. Every step is safe to re-run.
Open [localhost:3000/sign-up](http://localhost:3000/sign-up), sign up, and open the link. Without an email provider, development prints each link in the web server's log. Then create an organization.
The analyst needs a model: put a key in `.env.local` (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY` or `AI_GATEWAY_API_KEY`), or add one for the workspace under **Settings → AI**.
## Sample data [#sample-data]
| Command | What you get |
|---|---|
| `pnpm demo:seed` | **Acme**, a SaaS company (the DashBench dataset), as database `opendash_demo` with read-only user `opendash_demo_reader` |
| `pnpm demo:seed --clickhouse` / `--mysql` | The same company in ClickHouse or MySQL (start them with `pnpm clickhouse:up` / `pnpm mysql:up`) |
| `pnpm demo:seed --commerce` | **Lumen**, a home-lighting brand: about 125,000 orders, returns, campaigns, stock and support tickets in four currencies |
| Data → Connect source → **Use the playground** | ClickHouse's public playground: house prices, GitHub events, taxi trips and more |
The seed command prints the connection details. Connect them under **Data → Connect source** like any other database.
## Everyday commands [#everyday-commands]
| Command | What it does |
|---|---|
| `pnpm dev` | Web app and worker in watch mode |
| `pnpm lint` / `pnpm lint:fix` | Biome lint and format |
| `pnpm typecheck` | Strict TypeScript |
| `pnpm test` | Vitest unit and integration tests (needs `pnpm db:up`) |
| `pnpm build` | Every package and the web app |
| `pnpm db:up` / `pnpm db:down` | Start or stop the development databases |
| `pnpm db:migrate` | Apply migrations and install the job queues |
| `pnpm dev:doctor` | Check Node, pnpm, Docker, ports and settings, with a fix hint for each |
| `pnpm ask "question"` | Ask the analyst from the terminal and watch the run: thinking, SQL, results, the gate, the answer |
| `pnpm golden` | 21 questions about the sample company, graded against answers computed from the data |
| `pnpm evals` | The full [DashBench](/docs/open-source/dashbench) run |
| `pnpm slack:manifest` / `pnpm slack:tunnel` | The Slack app manifest for your address, or a local tunnel |
## Conventions [#conventions]
- TypeScript strict, ESM, Node 24. Files in kebab-case, React components in PascalCase. Biome only.
- **Only `withTenant(ctx, fn)` touches tenant data.** Importing the raw database handle is lint-banned. Never hold a transaction open across a model call or a warehouse query.
- **New tables** use the `(org_id, id)` primary key, composite foreign keys and row-level security policies; the tenancy suite checks it.
- **Migrations** are forward-only and must work with the previous version running.
- **Secrets** are never logged, never put in prompts, and never returned to the client.
## Troubleshooting [#troubleshooting]
| Symptom | Fix |
|---|---|
| Port 3000 in use | `PORT=3010 pnpm dev` |
| Streams never update | Use a direct connection for `DATABASE_DIRECT_URL` |
| "No worker has picked up the check yet" | Run `pnpm dev` (web and worker), not only the web app |
| `relation "pgboss.job" does not exist` | `pnpm db:migrate` |
| A workspace is stuck without its data key | `pnpm auth:repair` |
---
# License and open core
Source: https://opendash.cloud/docs/open-source/licensing
> OpenDash is Apache 2.0, except the ee/ directory, which is source-available. What each license allows, what lives where, and the promise about what never moves.
OpenDash is **open core**. Everything is **Apache 2.0** except the `ee/` directory, which is under the **Open Core Ventures Source Available License (OCVSAL)**. It is one repository, and the same images serve every deployment.
## What each license allows [#what-each-license-allows]
| | Apache 2.0 core | OCVSAL `ee/` |
|---|---|---|
| Read and modify the source | Yes | Yes |
| Test, and publish modifications | Yes | Yes, for non-production use |
| Use in production | Yes | Only with a commercial agreement |
| Redistribute | Yes, keeping LICENSE and NOTICE and marking changed files | Keeping the license on every copy |
| Patent license from contributors | Yes | No |
| Your contributions | Stay yours, under Apache 2.0 | The licensor gets a license to use them |
## What's open and what's paid [#whats-open-and-whats-paid]
**Features an operator uses are open; admin, governance and scale features are paid.** Asking, tracing, the semantic layer, knowledge, the learning loop, dashboards, routines, Slack, email, every connector and every model provider are in the Apache 2.0 core, and so is self-hosting all of it.
In `ee/` today:
- the license gate;
- the audit log's hash chain, Verify, long retention and exports (the audit log itself is in the core);
- single sign-on (OIDC and SAML 2.0);
- directory sync (SCIM 2.0).
**A core feature is never moved into `ee/`.** A feature that turns out to matter to individual operators moves out of `ee/` into the Apache 2.0 core, never the other way.
## How the boundary is enforced [#how-the-boundary-is-enforced]
- **The core never imports from `ee/`.** Only two files do, one in each app, and lint refuses any other import. A build without `ee/` deletes the folder and has those two files return the community edition.
- **Licensing is checked offline.** See [Enterprise features](/docs/self-hosting/enterprise#license-key).
- **`ee/` is maintainer-only.** Outside contributions go to the Apache 2.0 core.
## Dependencies [#dependencies]
Everything outside `ee/` must be **OSI-licensed** and **installable without tokens or accounts**. `pnpm check:licenses` checks the resolved dependency tree against an allowlist on every pull request.
- **Allowed:** MIT, Apache-2.0, BSD-2/3-Clause, ISC, 0BSD, Unlicense, CC0, Zlib and similar permissive licenses.
- **Not allowed:** SSPL, BSL/BUSL, ELv2, Commons Clause and other source-available licenses; GPL and AGPL in anything linked or bundled; anything that needs a token or account to install.
- **Exceptions** are few, each listed with its reason in `scripts/check-licenses.mjs` (for example MPL-2.0 libraries used unmodified, and the fonts in the PDF renderer under the SIL Open Font License).
## Files in the repository [#files-in-the-repository]
| File | What it is |
|---|---|
| `LICENSE` | Apache 2.0, noting that `ee/` is not covered |
| `ee/LICENSE` | The OCVSAL 1.0 text |
| `NOTICE` | Copyright and third-party material, kept by anyone who redistributes the code |
| `TRADEMARKS.md` | What the OpenDash name and logo may be used for. See [Trademarks](/docs/open-source/trademarks) |
For a commercial agreement, write to [hello@sureshkumar.dev](mailto:hello@sureshkumar.dev).
---
# Security and telemetry
Source: https://opendash.cloud/docs/open-source/security
> How to report a vulnerability, what's in scope, the guarantees the code is built around, and what OpenDash sends home (nothing).
## Report a vulnerability [#report-a-vulnerability]
Please report it **privately**, never in a public issue or discussion:
- on GitHub, open the repository's **Security** tab and choose **Report a vulnerability**, or
- email [hello@sureshkumar.dev](mailto:hello@sureshkumar.dev).
Include what you found, how to reproduce it, and what it affects. We'll acknowledge the report as soon as we can, work on a fix, and credit you in the release notes if you'd like.
**Supported versions.** OpenDash is pre-1.0. Security fixes go into `main` and the latest release.
## In scope [#in-scope]
The code in the repository and the images built from it: tenant isolation, authentication and API keys, the query gateway and its read-only guarantees, the answer gate, stored secrets, and the Slack and email integrations.
## Guarantees the code is built around [#guarantees-the-code-is-built-around]
| Guarantee | How it's enforced |
|---|---|
| **Workspaces can't see each other's data** | Every tenant table is keyed by `(org_id, id)` with row-level security. The application role can't bypass it, and code reaches tenant data only through `withTenant`. A test suite checks every table has its policies and that cross-workspace access is denied. |
| **Your databases are never written to** | Only workers connect, through read-only sessions with server-side time limits, as the read-only user you created. |
| **Numbers can't be made up** | The model cites query cells; deterministic code recomputes every one. |
| **Secrets stay secret** | Connection passwords and model keys are encrypted with your key (`OPENDASH_KEK`), never logged, never put in prompts, never returned to the browser. |
| **Closed by default** | Self-hosted instances are invite-only, and sign-in requires HTTPS. |
| **No SSRF through tools** | Outbound calls go through an SSRF guard; inbound webhooks are verified by signature. |
| **Personal data stays out of answers** | Personal-data columns can be counted and filtered, but their values are never returned. |
For the settings you control as an operator, see [Networking and security](/docs/self-hosting/security).
## Telemetry [#telemetry]
**Self-hosted builds send no telemetry.** If anonymous usage statistics are ever added, they will be opt-in, documented, and easy to turn off.
- Tracing to **your own** OpenTelemetry collector is opt-in (`OTEL_EXPORTER_OTLP_ENDPOINT`), and spans never carry a question, its SQL or an answer.
- Telemetry in third-party dependencies is audited and disabled.
---
# Trademarks
Source: https://opendash.cloud/docs/open-source/trademarks
> The code is open; the OpenDash name and logo are not covered by its licenses. What you may and may not do with them.
The **OpenDash** name and logo identify this project and the services built on it. The Apache License 2.0 and the OCVSAL cover the code, not the name or logo.
## You may [#you-may]
- say that your product is built on, works with, or is compatible with OpenDash, in plain text;
- use the name to refer to the project, for example in an article, a talk, or a link to the repository;
- run and modify the code for your own use under its license.
## Please don't [#please-dont]
- name a fork, a product or a company in a way that suggests it is OpenDash or endorsed by the project. **A fork that changes the code and is distributed to others must use a different name and logo**;
- use the OpenDash logo as your own, or in a way that suggests an affiliation that doesn't exist.
## Asking [#asking]
If you're not sure whether a use is fine, or you'd like permission for one, write to [hello@sureshkumar.dev](mailto:hello@sureshkumar.dev) or open an issue.
---
# Quickstart
Source: https://opendash.cloud/docs/quickstart
> Run OpenDash on your machine with a sample company, ask your first question, and open the trace behind the answer.
This gets OpenDash running locally with sample data in about ten minutes. To deploy it for a team, follow [Self-host](/docs/self-hosting) instead.
**You need:** Node.js 24, pnpm (through `corepack`), Docker, and a model provider key (Anthropic, OpenAI, Google or a Vercel AI Gateway key).
### Clone and install [#clone-and-install]
```bash
git clone https://github.com/getopendash/opendash.git && cd opendash
corepack enable && pnpm install
```
### Configure [#configure]
```bash
cp .env.example .env.local
```
In `.env.local`, set two secrets (run `openssl rand -base64 32` for each) and one model key:
```bash
BETTER_AUTH_SECRET=...
OPENDASH_KEK=...
ANTHROPIC_API_KEY=... # or OPENAI_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY, AI_GATEWAY_API_KEY
```
### Start everything [#start-everything]
```bash
pnpm dx
```
This checks your setup, starts Postgres in Docker, creates the database roles, runs migrations, and starts the web app and the worker.
### Seed a sample company [#seed-a-sample-company]
In a second terminal:
```bash
pnpm demo:seed
```
This creates **Acme**, a SaaS company with accounts, subscriptions, invoices and support tickets, in its own database with a read-only user. The command prints the connection details.
### Sign up and connect [#sign-up-and-connect]
Open [localhost:3000/sign-up](http://localhost:3000/sign-up) and sign up. Without an email provider, the sign-in link is printed in the web server's log. Create a workspace, then go to **Data → Connect source** and enter the details `demo:seed` printed. The connection check recognises it and marks it **Sample data**.
Approve the **starter pack** it proposes: a set of metrics and glossary terms for the sample company.
### Ask a question [#ask-a-question]
Open **Ask** (or press `N` anywhere) and try:
- *What was MRR last month, by plan?*
- *How many customers churned last quarter, and why?*
- *Which urgent tickets are still open?*
### Build a dashboard [#build-a-dashboard]
Open **Dashboards** and pick **Revenue review**. The analyst opens beside the page with the request begun: finish it and send it. It replies with a plan; press **Build it** and watch the dashboard build. See [Dashboards](/docs/dashboards).
## Read the answer [#read-the-answer]
Every number in the answer is a link. Open one to see the query it came from and the rows behind it. The label on the answer tells you which path it took:
- **Metric**: built from definitions an admin approved.
- **Unmodelled**: SQL written over the tables, cross-checked, and labelled so you know.
Open the **Sources** panel for the interpretation, the context the analyst used, every query, and the checks the answer gate ran. [Ask and trace](/docs/ask) explains each part.
## Next steps [#next-steps]
Create a read-only user and connect it.
Add glossary terms and guides.
A weekly question, answered in Slack or email.
Run it for your team.
Under **Data → Connect source**, choose **Use the playground** to connect ClickHouse's public playground (house prices, GitHub events, taxi trips and more). It needs internet access.
---
# Routines and insights
Source: https://opendash.cloud/docs/routines
> Make things happen on their own. Ask a question every Monday, get what OpenDash found, or watch your metrics and get told what moved and why.
A routine is anything that should happen without someone asking. It has a **trigger**, an **action**, and **who it reaches**. Create one under **Routines**, describe it in a sentence with **Describe it**, or choose **Repeat…** on an answer.
## On a schedule [#on-a-schedule]
Every day, every weekday, every week or every month, at a time you pick, in the workspace's time zone. The action is one of:
| Action | What happens |
|---|---|
| **Ask a question** | Asked fresh each time. The answer is checked like any other and kept in its conversation in Ask. |
| **Send what OpenDash found** | What's open in Insights and each person's open tasks, each with why. Nothing found, nothing sent. |
## When something is found [#when-something-is-found]
Watch up to 50 **verified metrics** with a weekly or monthly grain. OpenDash checks each one as its period's data lands, and first right after you save the routine. It starts the routine when:
| Condition | Example |
|---|---|
| **It's unusual** | Signups dropped far outside their normal range. Sensitivity: lower, medium or higher. |
| **It crosses a line** | MRR falls below a value you set. |
| **A goal is at risk** | The forecast misses a [goal](/docs/knowledge#goals). |
| **Its data is missing** | A table stopped updating. |
Choose **At once** or a **Daily roundup**, and **Investigate first** to have the analyst look into what changed before it tells anyone.
**Watch** on a metric answer adds that metric to the workspace's watching routine. **Insights → Watching** lists everything that's watched.
## Delivery [#delivery]
- **Email** to the people you choose. Every email has a one-click unsubscribe.
- **Slack** to the channels you choose. See [Slack and email](/docs/slack).
Anyone can make a routine that only reaches themselves; a viewer's routine can only send what OpenDash found, since asking is for members. Routines that reach other people or channels are for owners and admins.
A routine that fails four runs in a row pauses itself, so a broken source doesn't flood anyone's inbox.
## Insights and tasks [#insights-and-tasks]
What a routine finds lands in **Insights**: anomalies, trends, crossed thresholds, goals at risk and data-quality problems.
- **Investigate** asks the analyst to explain it. The verdict reads **Confirmed**, **Not confirmed**, **Explains it** or **Part of it**, with the queries behind it.
- **Create a task** turns an insight into work: what to do, an optional due date, and how long to judge it over (one to six months). When it's done, OpenDash compares the outcome with where the trend was heading, in code, with no model involved.
- Owners and admins can dismiss an insight, with a reason.
Investigations and routines are paid from the workspace's [background budget](/docs/models#spend-limits).
---
# Configuration
Source: https://opendash.cloud/docs/self-hosting/configuration
> Every environment variable a self-hosted OpenDash reads, grouped by what it controls. Both images read the same settings.
OpenDash is configured entirely through environment variables. With Docker Compose they live in `.env` next to `docker-compose.yml` (start from `infra/selfhost.env.example`). Never commit that file.
`web` and `worker` read the same settings. The worker calls the model providers and sends email; the web app needs the same keys to offer only the models that can run and to build links.
## Required [#required]
| Variable | Description |
|---|---|
| `OPENDASH_KEK` | Master key-encryption key for stored connection passwords and model keys. 32 bytes, base64 (`openssl rand -base64 32`). **Back it up offline**: without it, stored secrets can't be recovered. |
| `BETTER_AUTH_SECRET` | Signs sessions, email links and dashboard frame links (`openssl rand -base64 32`). Changing it ends every directory sync token. |
| `BETTER_AUTH_URL` | The HTTPS address people open OpenDash at. Also used for links in emails and for every identity provider's setup. |
| `BETTER_AUTH_TRUSTED_ORIGINS` | Comma-separated exact HTTPS origins allowed to sign in. Usually the same as `BETTER_AUTH_URL`. |
| `EMAIL_FROM` | Sender address, e.g. `OpenDash `, on a domain your provider lets you send from. |
| `RESEND_API_KEY` or `SMTP_URL` | One email provider. Resend wins when both are set. See [Email](#email). |
| `OPENDASH_FRAMES_URL` | The origin dashboards are served from: another domain pointed at this server, such as `https://frames.example.com`. Without it, dashboards don't open in production. See [Dashboards](#dashboards). |
With Docker Compose you also set `POSTGRES_PASSWORD` and one password per database role (`OPENDASH_DB_OWNER_PASSWORD`, `…_APP_…`, `…_SYSTEM_…`, `…_AUTH_…`, `…_QUEUE_…`). Use URL-safe values such as `openssl rand -hex 24`: they go into connection URLs.
## Access [#access]
| Variable | Default | Description |
|---|---|---|
| `OPENDASH_INVITE_ONLY` | `1` | `1`: only invited people (plus the bootstrap admin, once) can sign up. `0`: anyone who can reach the address can sign up and create workspaces. |
| `OPENDASH_BOOTSTRAP_ADMIN_EMAIL` | | The first admin. Can sign up once while nobody has. A new invite-only instance refuses to start without it. |
| `OPENDASH_TERMS_URL`, `OPENDASH_PRIVACY_URL`, `OPENDASH_SECURITY_URL` | | Optional links in the sign-in footer and sign-up terms line. Empty hides them. |
With `OPENDASH_INVITE_ONLY=0`, anyone who can reach the server can run the analyst on your model keys and connect sources that reach your network. Use it only on a private instance.
## Email [#email]
Sign-up, sign-in and password reset need email. In production the web app refuses to start without it.
| Variable | Description |
|---|---|
| `RESEND_API_KEY` | A Resend API key, with the sender's domain verified in Resend. |
| `SMTP_URL` | Any SMTP server: `smtp://user:pass@host:587` (STARTTLS) or `smtps://user:pass@host:465`. TLS is required unless the URL ends in `?requireTLS=false`, since sign-in links travel in these emails. |
SMTP has no idempotency key, so a retry after an unacknowledged send can deliver twice. The Message-ID is the same, so mail clients show one.
## Models [#models]
| Variable | Description |
|---|---|
| `AI_GATEWAY_API_KEY` | Vercel AI Gateway. When set, every allowed model runs through it. |
| `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY` | Without a gateway key, each maker's key runs its own models. |
These are the deployment's own provider. Workspaces can connect their own instead, under **Settings → AI**. `OPENAI_API_KEY` also turns on embeddings for search by meaning; see [Models and providers](/docs/models).
## Database [#database]
| Variable | Description |
|---|---|
| `DATABASE_URL` | App queries. A transaction pooler is fine. |
| `DATABASE_DIRECT_URL` | Direct or session-mode connection, for `LISTEN`. One connection per process. |
| `DATABASE_QUEUE_URL` | Direct or session-mode connection as `opendash_queue`, for the job queue. |
| `DATABASE_AUTH_URL` | As `opendash_auth`, for sign-in. |
| `DATABASE_SYSTEM_URL` | As `opendash_system`, for the routine dispatcher and maintenance. |
| `OPENDASH_EXTRA_CA_CERTS` | A certificate authority as PEM text, for a Postgres that signs with its own CA. Or mount a file and set `NODE_EXTRA_CA_CERTS`. |
The bundled compose file builds these URLs for you. The [PostgreSQL page](/docs/self-hosting/postgres) covers managed Postgres.
## Dashboards [#dashboards]
A dashboard's code runs in a sandboxed frame served from a second domain pointed at the same server, so it never runs where an OpenDash session does. Set it in `OPENDASH_FRAMES_URL`, for example `https://frames.opendash.example.com`. It is written into the web image's security headers when the image is **built**, and read again when it runs, so it must be set at both times. The bundled `docker-compose.yml`, the Caddy profile and the published images don't pass it yet: until they do, dashboards don't open on a Docker Compose install. Everything else works.
In development you don't need it: the frames origin is the other loopback name of the same server (`http://127.0.0.1:3000` when you open `http://localhost:3000`).
## Connected services [#connected-services]
| Variable | Default | Description |
|---|---|---|
| `OPENDASH_MCP` | on | `0` turns off connected services (MCP servers) on this deployment: Settings hides them, the analyst isn't offered them, and nothing calls a server. |
## Workers and scaling [#workers-and-scaling]
| Variable | Default | Description |
|---|---|---|
| `WORKER_POOLS` | `all` | Comma-separated pools this worker runs: `query` (connection checks, dashboard queries, metric checks, routine runs and sends), `sync` (learning sources, testing definitions), `interactive` (agent runs and what they send, dashboard summaries). Every install needs each pool running somewhere. |
| `OPENDASH_EDITION` | `community` | `cloud` makes workers refuse private addresses, for hosting OpenDash for others. |
| `OPENDASH_EGRESS_IPS` | | The workers' fixed outbound IPs, shown on the connect form so people know what to allowlist. |
## Networking [#networking]
| Variable | Default | Description |
|---|---|---|
| `OPENDASH_BIND`, `OPENDASH_PORT` | `127.0.0.1`, `3000` | Where `web` listens on the host. |
| `OPENDASH_DOMAIN` | | With the Caddy profile: the domain to get a certificate for, or `localhost`. |
| `OPENDASH_HTTP_PORT`, `OPENDASH_HTTPS_PORT` | | Caddy's ports, when not 80 and 443. |
| `OPENDASH_TRUSTED_PROXIES` | | Your proxy's addresses or CIDR ranges, so per-IP rate limits count per client. |
| `OPENDASH_CLIENT_IP_HEADERS` | | Other headers to read the client IP from, e.g. `x-real-ip`. |
## Slack [#slack]
| Variable | Description |
|---|---|
| `SLACK_CLIENT_ID`, `SLACK_CLIENT_SECRET`, `SLACK_SIGNING_SECRET` | From the Slack app's Basic Information page. |
| `SLACK_APP_TOKEN` | An app-level token (`xapp-…`) with `connections:write`, for Socket Mode. |
| `SLACK_PUBLIC_URL` | Only when Slack must return to another HTTPS address than `BETTER_AUTH_URL`. |
See [Slack and email](/docs/slack) for creating the app.
## Enterprise [#enterprise]
These settings apply to the source-available `ee/` features.
| Variable | Default | Description |
|---|---|---|
| `OPENDASH_LICENSE_KEY` | | Unlocks the `ee/` features in production. Checked offline. |
| `OPENDASH_AUDIT_RETENTION_DAYS` | `90` | Audit log retention. Up to 2562 (seven years) with a license that covers the audit chain. |
| `OPENDASH_SSO_MAX_AUTH_AGE_HOURS` | `12` | How often people at a domain that requires SSO sign in through their provider again. |
| `OPENDASH_SSO_TRUSTED_IDP_ORIGINS` | | Identity provider origins on your own network, comma-separated. |
## Optional [#optional]
| Variable | Description |
|---|---|
| `OPENDASH_SEED_DEMO`, `OPENDASH_DEMO_READER_PASSWORD` | `true` seeds the sample company once, with a read-only user on this password. |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Send OpenTelemetry traces to your collector over OTLP/HTTP. Spans carry ids, routes, timings and usage, never a question, its SQL or an answer. |
| `OTEL_SERVICE_NAME` | The service name on those traces. |
| `OPENDASH_WEB_IMAGE`, `OPENDASH_WORKER_IMAGE` | Published images to run instead of building from the clone. |
---
# Deploy with Docker Compose
Source: https://opendash.cloud/docs/self-hosting/docker-compose
> Run the whole stack on one machine with the docker-compose.yml at the root of the repository, with optional automatic HTTPS through Caddy.
The root `docker-compose.yml` runs everything OpenDash needs on a single machine. It is the recommended way to evaluate OpenDash and to run it for a small team. CI runs this exact stack end to end on every change (`infra/selfhost-smoke.sh`).
## Deploy [#deploy]
### Clone the repository [#clone-the-repository]
```bash
git clone https://github.com/getopendash/opendash.git
cd opendash
```
### Create your settings [#create-your-settings]
```bash
cp infra/selfhost.env.example .env
```
Fill in `.env`. The file explains each value; the ones you must set are:
| Variable | What to put there |
|---|---|
| `POSTGRES_PASSWORD`, `OPENDASH_DB_*_PASSWORD` | A URL-safe password for Postgres and each OpenDash role: `openssl rand -hex 24` |
| `OPENDASH_KEK` | The master encryption key: `openssl rand -base64 32`. **Back it up.** |
| `BETTER_AUTH_SECRET` | Signs sessions and email links: `openssl rand -base64 32` |
| `BETTER_AUTH_URL`, `BETTER_AUTH_TRUSTED_ORIGINS` | The HTTPS address people open, e.g. `https://opendash.example.com` for both |
| `OPENDASH_BOOTSTRAP_ADMIN_EMAIL` | The first admin's email. Required on a new, invite-only instance |
| `EMAIL_FROM` and `RESEND_API_KEY` or `SMTP_URL` | How OpenDash sends sign-in emails |
| `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY` or `AI_GATEWAY_API_KEY` | At least one, unless every workspace brings its own provider |
The [configuration reference](/docs/self-hosting/configuration) lists everything else.
A dashboard's code runs in a sandboxed frame served from a second domain pointed at the same server, so it never runs where an OpenDash session does. Set it in `OPENDASH_FRAMES_URL`, for example `https://frames.opendash.example.com`. It is written into the web image's security headers when the image is **built**, and read again when it runs, so it must be set at both times. The bundled `docker-compose.yml`, the Caddy profile and the published images don't pass it yet: until they do, dashboards don't open on a Docker Compose install. Everything else works.
### Start the stack [#start-the-stack]
```bash
docker compose up -d
```
To let Caddy get a Let's Encrypt certificate for you, set `OPENDASH_DOMAIN` (its DNS pointing at this machine) and add the profile:
```bash
docker compose --profile caddy up -d
```
### Sign in [#sign-in]
Open your `BETTER_AUTH_URL` and sign up with the bootstrap admin's email. That address can sign up once, while nobody else has; everyone else joins by invitation. Then create a workspace and [connect a source](/docs/sources).
Set `OPENDASH_SEED_DEMO=true` and `OPENDASH_DEMO_READER_PASSWORD` before the first start. Setup seeds a sample SaaS company once, as its own database `opendash_demo` with a read-only user `opendash_demo_reader`. Connect it under **Data → Connect source** with host `postgres`.
## What runs [#what-runs]
The compose project is called `opendash-selfhost`. Its services start in this order:
| Service | What it does |
|---|---|
| `postgres` | PostgreSQL with pgvector. Data lives in the `pgdata` volume; the port is not published. |
| `setup` | One-shot: creates roles, schemas and extensions, runs migrations under an advisory lock and installs the job queues. `web` and `worker` wait for it. |
| `web` | The UI and API on `127.0.0.1:3000` (change with `OPENDASH_BIND` and `OPENDASH_PORT`). Its health check holds the deploy until the database answers. |
| `worker` | All worker pools (`WORKER_POOLS=all`). |
| `caddy` | Only with `--profile caddy`: TLS in front of `web`. |
`web` binds to localhost on purpose. Put a TLS proxy in front of it (yours, or the Caddy profile), and never expose it directly: see [Networking and security](/docs/self-hosting/security).
## Use published images [#use-published-images]
To run released images instead of building from the clone, set them in `.env`:
```bash
OPENDASH_WEB_IMAGE=ghcr.io/getopendash/opendash-web:v1.2.3
OPENDASH_WORKER_IMAGE=ghcr.io/getopendash/opendash-worker:v1.2.3
```
Pin a version tag rather than a moving one, so an upgrade is always a decision you make. See [Upgrades and versioning](/docs/self-hosting/upgrades).
---
# Enterprise features
Source: https://opendash.cloud/docs/self-hosting/enterprise
> Single sign-on, directory sync and the tamper-evident audit log, from the source-available ee/ directory. How licensing works and how to set each one up.
Admin, governance and scale features live in the `ee/` directory under the source-available OCVSAL license. Everything an operator uses day to day is in the Apache 2.0 core. See [License and open core](/docs/open-source/licensing) for the split.
| Feature | Edition |
|---|---|
| Audit log: recording, and the last 90 days in **Settings → Audit log** | |
| Audit chain: hash chain, Verify, exports, retention up to seven years | |
| Single sign-on: OIDC and SAML 2.0, required per domain | |
| Directory sync: SCIM 2.0, roles from groups | |
## License key [#license-key]
- **Outside production** (`NODE_ENV` isn't `production`), every enterprise feature can be set up without a key, as the license allows for development and testing.
- **In production**, a feature can be set up only when `OPENDASH_LICENSE_KEY` covers it. The key is checked **offline** against the licensor's public keys, so air-gapped instances work. Owners see what it covers in **Settings → License**.
- **A lapsed key never switches security off.** What's already set up keeps running (SSO sign-in, requiring it, directory sync, audit recording). Only changes wait for a valid key. Disabling a provider, issuing a directory token and disconnecting a directory always work, because they only take access away.
To get a key, write to [hello@sureshkumar.dev](mailto:hello@sureshkumar.dev).
## Single sign-on [#single-sign-on]
OIDC and SAML 2.0 identity providers, per workspace, under **Settings → Single sign-on** (owners and admins).
- **Two proofs.** A DNS TXT record, `_opendash-verification-.`, proves the workspace may claim the domain. A validated ID token or SAML assertion proves the person. Only both together create or link an account, and only at exactly that domain.
- **Lifecycle:** draft, verified, active (a test sign-in passed after its last change), required for its domain, disabled.
- **Requiring it** applies to everyone with an email at the domain, on the whole instance: their other sessions end, their API keys are revoked, and password and email-link sign-in are refused. Sessions must be younger than `OPENDASH_SSO_MAX_AUTH_AGE_HOURS` (12 by default).
- **Newcomers** join as viewers, or with the role a pending invitation gave them.
What to paste into your identity provider is built from `BETTER_AUTH_URL`:
| Protocol | Value |
|---|---|
| OIDC redirect URI | `/api/auth/sso/callback/` |
| SAML ACS URL | `/api/auth/sso/saml2/sp/acs/` |
| SAML entity ID | `/api/auth` |
Changing `BETTER_AUTH_URL` breaks every identity provider and directory configured against it.
An identity provider's issuer and metadata must be HTTPS on a public address. To trust one on your own network, list its origin in `OPENDASH_SSO_TRUSTED_IDP_ORIGINS`.
### Break-glass [#break-glass]
If a required provider fails and nobody can sign in, disable it from the server:
```bash
pnpm sso:disable --provider
```
Its sessions end, the requirement lifts, and people at its domain can sign in by email again. The audit log records it.
## Directory sync [#directory-sync]
SCIM 2.0, one connection per workspace, under **Settings → Directory sync**. Your directory calls `/api/auth/scim/v2` with a token that is shown once and lasts a year.
- **Only at verified domains**, so a directory can't claim strangers.
- **Roles from groups.** Each group can map to admin, member or viewer; a person gets the highest. Owner is never assigned by the directory.
- **Deprovisioning.** A deactivated or deleted person leaves the workspace and loses their sessions. A workspace's last owner is always kept.
- Okta and Microsoft Entra request shapes are covered.
Tokens are stored only as digests under a key derived from `BETTER_AUTH_SECRET`. Changing that secret ends every directory's token.
## Audit chain [#audit-chain]
The Apache 2.0 core records the audit log on every instance. With a license that covers `audit`:
- **Hash chain.** Each row's hash covers the previous hash and the row, so changing, removing or reordering a sealed row breaks every link after it.
- **Verify** walks the chain, from **Settings → Audit log** or from the server: `pnpm audit:verify --org `.
- **Exports** as CSV or JSON Lines, with each row's place and hash.
- **Retention** up to seven years via `OPENDASH_AUDIT_RETENTION_DAYS`. A lapsed key never shortens it.
---
# Self-host OpenDash
Source: https://opendash.cloud/docs/self-hosting
> Run OpenDash on your own infrastructure. The same two images serve a laptop, a single VM and a scaled deployment, with PostgreSQL as the only stateful dependency.
OpenDash is built to run where your data already lives. Self-hosting gives you the full product: the same images, the same answer gate, and no telemetry sent anywhere. Your warehouse keeps the analytical data; OpenDash keeps only what it needs to run (conversations, definitions, results and jobs) in its own Postgres.
OpenDash is in beta. We’re continuing to improve the product with user feedback.
Read the release notes before every upgrade, and keep backups of Postgres and your encryption key.
## Deployment shapes [#deployment-shapes]
| Shape | Compute | Postgres | Best for |
|---|---|---|---|
| **Single node** | `docker compose`: `web` and `worker`, all worker pools in one process | bundled `postgres` (pgvector image) | evaluating, small teams |
| **Scaled** | several `web` replicas, workers split by `WORKER_POOLS` | external managed Postgres | larger installs |
Start with a single node. Moving to the scaled shape later is a configuration change, not a migration: point the database URLs at a managed Postgres, add `web` replicas and split the workers.
## Architecture [#architecture]
- **`web`** serves the UI, the API, sign-in and webhooks. It never runs migrations and never connects to your databases.
- **`worker`** runs the analyst, the query gateway, routines, syncs and deliveries. It is the only process that reaches your databases, the model providers, Slack and email. Connected services (MCP servers) are reached from both.
- **PostgreSQL** holds everything stateful: data under row-level security, the job queue, full-text and vector search, and change notifications. There is no Redis, queue or object store to run.
The [architecture page](/docs/open-source/architecture) explains why it is shaped this way.
## What you need [#what-you-need]
- A machine with **Docker** and Compose v2, or a container platform.
- **PostgreSQL 16, 17 or 18** with `vector`, `pg_trgm` and `btree_gin`, if you don't use the bundled one.
- A **domain with HTTPS**. Production sign-in refuses plain HTTP; the bundled Caddy profile can get a certificate for you.
- A **second HTTPS domain** pointed at the same server, for dashboards (`OPENDASH_FRAMES_URL`). See [Configuration](/docs/self-hosting/configuration#dashboards).
- An **email provider** (Resend or any SMTP server). Sign-up, sign-in and password reset send email, and the web app won't start without it in production.
- A **model provider key** for the analyst: Anthropic, OpenAI, Google or the Vercel AI Gateway. Workspaces can also bring their own.
## Next steps [#next-steps]
From clone to first sign-in on one machine.
Every environment variable, grouped by what it does.
Managed Postgres, poolers, roles and TLS.
Who can sign up, proxies, rate limits and secrets.
---
# Monitoring and backups
Source: https://opendash.cloud/docs/self-hosting/operations
> What to log, watch and back up once OpenDash is running, and how to scale it out.
## Logs and traces [#logs-and-traces]
Both processes log **JSON lines to stdout**, so any log collector that reads container output works.
To send traces to an OpenTelemetry collector, set `OTEL_EXPORTER_OTLP_ENDPOINT` (OTLP over HTTP, e.g. `http://127.0.0.1:4318`) and optionally `OTEL_SERVICE_NAME`. Spans carry ids, routes, timings and usage. They never carry a question, its SQL, an answer, or a URL's query string.
## What to watch [#what-to-watch]
| Signal | Why it matters |
|---|---|
| Queue depth and dead-letter queue size | Runs and deliveries are jobs. A growing queue means workers can't keep up. |
| Runs still active past their time budget | A stuck run, a slow source or a slow provider. |
| **Missing future partitions** of the high-volume tables | Correctness-critical. Alert on it. |
| `pg_notification_queue_usage()` above 10% | Change notifications are backing up. |
| Postgres connection counts | Each process holds one `LISTEN` connection plus its pools. |
| Query failures per source | Credentials, network or a source under load. |
## Backups [#backups]
Back up two things, separately:
1. **PostgreSQL.** Managed point-in-time recovery, or `pg_dump` plus WAL archiving (for example WAL-G).
2. **`OPENDASH_KEK`**, offline. It is the only way to decrypt the connection passwords and model keys stored in Postgres. Losing it means re-entering every one of them.
Your analytical data stays in your own databases, so it isn't part of OpenDash's backup.
## Scaling [#scaling]
The same images scale out without a migration:
### Move to a managed Postgres [#move-to-a-managed-postgres]
Point `DATABASE_URL`, `DATABASE_DIRECT_URL` and `DATABASE_QUEUE_URL` (and the auth and system URLs) at it. See [PostgreSQL](/docs/self-hosting/postgres) for which connection may use a pooler.
### Add web replicas [#add-web-replicas]
`web` is stateless. Each replica holds one `LISTEN` connection.
### Split the workers [#split-the-workers]
Run the worker image several times with different `WORKER_POOLS`:
```bash
WORKER_POOLS=interactive # agent runs and what they send, such as Slack replies; dashboard summaries
WORKER_POOLS=query # connection checks, dashboard queries, metric checks, routine runs and sends
WORKER_POOLS=sync # learning sources, testing definitions
```
Scale `interactive` with the number of people asking questions.
---
# PostgreSQL
Source: https://opendash.cloud/docs/self-hosting/postgres
> OpenDash keeps all of its state in one PostgreSQL. What version and extensions it needs, which connection goes where, and notes for Neon, Supabase, Amazon RDS and ClickHouse Managed Postgres.
PostgreSQL is OpenDash's only stateful dependency: application data, sign-in, the job queue (pg-boss), search (full text, trigram and vectors) and change notifications all live in it. The bundled compose file runs one for you; for anything larger, use a managed Postgres.
## Requirements [#requirements]
- **PostgreSQL 16, 17 or 18.**
- The extensions **`vector`** (pgvector 0.7 or later), **`pg_trgm`** and **`btree_gin`**. The bootstrap names any your server doesn't ship, and migrations refuse a database without them.
- **Point-in-time recovery and daily backups** for anything you care about.
## Connection URLs [#connection-urls]
OpenDash uses three main connections, because a transaction pooler can't do everything:
| Variable | Mode | Used for |
|---|---|---|
| `DATABASE_URL` | Transaction pooler is fine | App queries. Each sets its tenant for one transaction. With Supavisor, add `prepare: false`. |
| `DATABASE_DIRECT_URL` | Direct or session mode | `LISTEN`, one connection per web or worker process, so answers stream as they're written. |
| `DATABASE_QUEUE_URL` | Direct or session mode, as `opendash_queue` | The job queue, on its own pool. Workers run jobs; the web app only enqueues. |
Two more connect as their own roles: `DATABASE_AUTH_URL` (`opendash_auth`) and `DATABASE_SYSTEM_URL` (`opendash_system`). The bundled compose file sets all five for you.
Without a `LISTEN`-capable URL, the web app falls back to polling for new events every 500 ms. It works, but answers feel less live.
## Roles [#roles]
Setup creates five roles, and OpenDash never needs `BYPASSRLS` (which managed providers often won't grant):
| Role | Purpose |
|---|---|
| `opendash_owner` | Runs migrations only. |
| `opendash_app` | The application. Has no `BYPASSRLS`, so row-level security always applies. |
| `opendash_auth` | Sign-in and sessions. It can reach only the auth schema. |
| `opendash_queue` | Owns the job queue schema. |
| `opendash_system` | The routine dispatcher and maintenance. |
## Managed providers [#managed-providers]
### Neon [#neon]
Use the **non-pooler** endpoint for `DATABASE_DIRECT_URL`: the `-pooler` host is PgBouncer in transaction mode and has no `LISTEN`. In production, **turn autosuspend off**: a suspended compute drops `LISTEN` sessions.
### Supabase [#supabase]
Supavisor's **transaction mode (port 6543)** supports neither `LISTEN` nor prepared statements. Use **session mode (5432)** or a direct connection. Direct connections are IPv6 unless you buy the IPv4 add-on.
### Amazon RDS and other private CAs [#amazon-rds-and-other-private-cas]
When the server's certificate comes from the provider's own certificate authority, add `sslmode=verify-full` to every URL and give both images the CA: as PEM text in `OPENDASH_EXTRA_CA_CERTS` (for platforms without file mounts, such as Railway), or as a mounted file named by `NODE_EXTRA_CA_CERTS`. With `sslmode=require` the connection is encrypted, but the server's identity isn't checked.
### ClickHouse Managed Postgres [#clickhouse-managed-postgres]
Port **5432** is direct (use it for setup, `DATABASE_DIRECT_URL` and `DATABASE_QUEUE_URL`); **6432** is PgBouncer in transaction mode (`DATABASE_URL` may use it). Create the `opendash` database first; the provider's superuser runs the bootstrap. It also signs with its own CA, so follow the section above.
## Migrations [#migrations]
Migrations run in the one-shot `setup` service, under an advisory lock, before `web` and `worker` start. The web image never migrates. Migrations are forward-only and written to work while the previous version is still running, so rolling deploys are safe, except where the release notes say otherwise (see [Upgrades](/docs/self-hosting/upgrades)). Long backfills run as background jobs.
---
# Networking and security
Source: https://opendash.cloud/docs/self-hosting/security
> Who can reach and join your instance, how OpenDash talks to your databases, and the settings that matter behind a proxy.
A self-hosted OpenDash holds credentials to your databases and spends your model budget, so the defaults are closed. This page covers what you decide as the operator. For how the code isolates tenants and checks numbers, see [Security and telemetry](/docs/open-source/security).
## Who can join [#who-can-join]
New instances are **invite-only** (`OPENDASH_INVITE_ONLY=1`). The address in `OPENDASH_BOOTSTRAP_ADMIN_EMAIL` can sign up once, while nobody has, and invites everyone else. A new instance nobody has joined refuses to start without it.
Setting `OPENDASH_INVITE_ONLY=0` lets anyone who can reach the address sign up, create workspaces on your model keys, and connect sources that reach your network. Only do that on a private instance.
## HTTPS [#https]
Production sign-in accepts only an HTTPS `BETTER_AUTH_URL` and HTTPS trusted origins. Either:
- put your own TLS proxy (a load balancer, nginx, Traefik) in front of `web`, or
- use the bundled Caddy profile: `docker compose --profile caddy up -d` with `OPENDASH_DOMAIN` set. Caddy gets a Let's Encrypt certificate (its own for `localhost`).
## Behind a proxy [#behind-a-proxy]
Per-IP rate limits need the real client address.
- **Caddy profile:** nothing to set. Caddy overwrites `X-Forwarded-For`.
- **Your own proxy:** set `OPENDASH_TRUSTED_PROXIES` to its addresses or CIDR ranges. Without it, a multi-entry `X-Forwarded-For` isn't trusted and those requests share one strict bucket. If your proxy uses another header, list it in `OPENDASH_CLIENT_IP_HEADERS`.
Never expose `web` directly without a proxy. A client could send its own `X-Forwarded-For` and dodge rate limits.
## Reaching your databases [#reaching-your-databases]
- **Only workers connect** to your databases and warehouses. The web app never does.
- **Every query runs read-only**, in a read-only session with a server-side time limit, as the user you connected. Create a read-only user for each source; the connection check tells you if the user can change data.
- **Private addresses.** The community edition allows them, since that's where most self-hosted databases live. If you host OpenDash for other people, set `OPENDASH_EDITION=cloud` on `web` and workers so workers refuse private addresses, and list their fixed outbound IPs in `OPENDASH_EGRESS_IPS` for people to allowlist.
- **TLS to sources** defaults to `verify-full` for PostgreSQL and MySQL. See [Connect a source](/docs/sources#tls).
- **Trust.** Results, samples and checks are bounded for an honest server. A server built to ignore its own limits can still send more than expected, so connect only databases you trust to behave.
## Secrets [#secrets]
- `OPENDASH_KEK` encrypts every stored connection password and model key. Keep it out of the database backups and **back it up separately, offline**. Losing it means re-entering every secret.
- `BETTER_AUTH_SECRET` signs sessions and email links.
- Secrets live in your environment or `.env`. They are never logged, never put in prompts, and never returned to the browser.
## Outbound and inbound calls [#outbound-and-inbound-calls]
- Outbound calls from tools and webhooks go through an SSRF guard.
- Inbound webhooks are verified by signature.
- Telemetry: none by default. Traces go only to an OpenTelemetry collector you configure, and never carry prompts, SQL or answers.
---
# Troubleshooting
Source: https://opendash.cloud/docs/self-hosting/troubleshooting
> Common problems when running OpenDash, what usually causes them, and how to fix each.
## Startup [#startup]
| Symptom | Likely cause | Fix |
|---|---|---|
| `web` won't start in production | Email, a valid secret, base URL or trusted origins is missing | Set `EMAIL_FROM` with `RESEND_API_KEY` or `SMTP_URL`, `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL` and `BETTER_AUTH_TRUSTED_ORIGINS` |
| A new instance refuses to start | Invite-only with no first admin | Set `OPENDASH_BOOTSTRAP_ADMIN_EMAIL` |
| `extension "vector" does not exist` | The Postgres image lacks pgvector | Use a pgvector image, such as `pgvector/pgvector:pg17`, or enable the extension on your managed Postgres |
| A dashboard says "Dashboards can't open here" | No frames origin | Set `OPENDASH_FRAMES_URL` when the web image is built and when it runs. See [Configuration](/docs/self-hosting/configuration#dashboards) |
| `relation "pgboss.job" does not exist` | The job queues aren't installed | Run the `setup` service again (or `pnpm db:migrate` in development) |
## Sign-in [#sign-in]
| Symptom | Likely cause | Fix |
|---|---|---|
| Sign-in is refused | `BETTER_AUTH_URL` or a trusted origin is plain HTTP | Put a TLS proxy in front, or use the Caddy profile |
| No sign-in email arrives | Email provider rejects the sender | Verify the sender's domain with Resend, or check `SMTP_URL` and TLS |
| Everyone shares one rate limit | A proxy appends to `X-Forwarded-For` and isn't trusted | Set `OPENDASH_TRUSTED_PROXIES` |
## Answers and sources [#answers-and-sources]
| Symptom | Likely cause | Fix |
|---|---|---|
| Answers never update while they're written | `LISTEN` is going through a transaction pooler | Point `DATABASE_DIRECT_URL` at a direct or session-mode connection |
| "No worker has picked up the check yet" when connecting a source | Only `web` is running | Start the `worker` service |
| A source fails its TLS check | The certificate isn't from a public CA, or doesn't name the host you typed | Paste your CA's certificate on the connect form; type the host the certificate names |
| A ClickHouse source refuses outer joins | The server has `join_use_nulls = 0` and the user is `readonly = 1` | Give the user `readonly = 2`, or set `join_use_nulls = 1` on the server |
| No models to choose from | No provider key | Set a provider key on both images, or add one under **Settings → AI** |
## Still stuck? [#still-stuck]
- Search the [GitHub issues](https://github.com/getopendash/opendash/issues), or open one with your version, how you deploy, and the relevant log lines (both processes log JSON to stdout).
- Security problems go through the private process in [Security and telemetry](/docs/open-source/security#report-a-vulnerability), never a public issue.
---
# Upgrades and versioning
Source: https://opendash.cloud/docs/self-hosting/upgrades
> How to upgrade a self-hosted instance, what happens to the database on the way, and what to expect from releases before 1.0.
## Upgrade [#upgrade]
### Read the release notes [#read-the-release-notes]
Look for new migrations, new required settings and breaking changes. Before 1.0, breaking changes can happen in any release.
### Back up [#back-up]
Take a Postgres snapshot (or confirm point-in-time recovery is on) and make sure your `OPENDASH_KEK` backup is current.
### Pull and restart [#pull-and-restart]
With published images, change the tags in `OPENDASH_WEB_IMAGE` and `OPENDASH_WORKER_IMAGE`, then:
```bash
docker compose pull && docker compose up -d
```
From a clone:
```bash
git pull && docker compose up -d --build
```
The `setup` service applies new migrations first, under an advisory lock, and `web` and `worker` start only after it succeeds.
Migration 0090 replaces the old dashboards with the new ones and retires reports and public links. It drops tables the previous version reads, so this one upgrade can't roll: stop `web` and `worker` first (`docker compose stop web worker`), then pull and start as above.
It also deletes what used the old engine: old dashboards and reports, public links, routines that sent a dashboard (with their runs and sends), and dashboard attachments in conversations. Take the backup in the first step.
## Why upgrades are safe to roll [#why-upgrades-are-safe-to-roll]
- **Migrations are forward-only** and written to work while the previous version is still running, so a rolling deploy never has old code reading a schema it doesn't understand. The release notes say when one can't, as 0090 couldn't.
- **Long backfills run as background jobs**, not inside the migration, so an upgrade doesn't wait on them.
- **Work survives a restart.** The transcript in Postgres is canonical, jobs are fenced by attempt, and side effects (emails, Slack messages) go through an idempotent outbox, so a run interrupted by a deploy resumes rather than repeating what it already sent.
## Versions and images [#versions-and-images]
- Releases are tagged `v*`. Images are published to GitHub Container Registry as `ghcr.io/getopendash/opendash-web` and `ghcr.io/getopendash/opendash-worker` for every `v*` tag and for `main`.
- **Pin a version tag** in production. Running `main` gets you every change as it lands.
- **Support:** OpenDash is pre-1.0. Security fixes go into `main` and the latest release.
---
# Datasets and metrics
Source: https://opendash.cloud/docs/semantic-layer
> OpenDash's semantic layer. Datasets describe your tables in small YAML files, metrics name the numbers that matter, and both compile to safe SQL.
Datasets and metrics are how you tell OpenDash what your numbers mean, once, so every answer agrees. A question that a metric covers takes the **Metric** path: it is built from definitions an admin approved, not from SQL the model wrote.
Find them under **Knowledge → Datasets** and **Knowledge → Metrics**.
## Datasets [#datasets]
A dataset is a table or a query with a declared shape: what one row is, which columns exist, and what you can sum, count or filter.
```yaml
ref: mrr_monthly
label: MRR snapshot by month
grain: one row per subscription item active at the end of each month
primary_key: [item_id, month]
time_column: month
sql: |
select ...
columns:
- { name: month, type: time, grain: month, description: The month (its first day) }
- { name: plan_id, type: string, dimension: true }
- { name: mrr_usd, type: number, format: usd }
- { name: is_test, type: boolean, dimension: true }
measures:
- { name: mrr, expr: "round(sum(mrr_usd), 2)", format: usd, description: MRR in USD }
- { name: paying_customers, expr: "count(distinct account_id)" }
segments:
- { name: exclude_test, where: "not is_test", default: true }
relationships:
- { to: plans, type: "n:1", on: { plan_id: id } }
snapshot: { at: month }
```
| Field | Description |
|---|---|
| `ref` | Identifier, `lower_snake_case`. |
| `label`, `description` | How people and the analyst refer to it. |
| `sql` | The query, in the source's own dialect. |
| `grain` | What one row is, in words. Tested to be unique. |
| `primary_key`, `time_column` | The key columns and the column periods filter on. |
| `columns` | Each with a `type` (`string`, `number`, `boolean`, `time`), and optionally `dimension`, `synonyms`, `grain` and `format` (`number`, `usd`, `percent`). |
| `measures` | Aggregations: `name` and `expr`, optionally `format`. |
| `segments` | Named filters. A `default: true` segment always applies unless a question excludes it. |
| `relationships` | Joins to other datasets: `n:1`, `1:1` or `1:n`, with `on` columns. |
| `snapshot` | For month-end style tables, the column that marks each snapshot. |
| `usage_guidance`, `ai_context` | Notes and examples for the analyst. |
Joining to the "many" side of a relationship silently multiplies rows, and every sum after it is wrong. OpenDash's compiler only joins many-to-one, so a fan-out can't happen in a metric query.
## Metrics [#metrics]
A metric names a measure and how it should be read:
```yaml
name: mrr
label: Monthly recurring revenue
description: MRR at the end of each month
dataset: mrr_monthly
measure: mrr
default_grain: month
format: usd
direction: higher_is_better
synonyms: [recurring revenue, run-rate revenue, MRR]
```
| Field | Description |
|---|---|
| `name`, `label`, `description` | Identifier and how it's shown. |
| `dataset`, `measure` | Where the number comes from. |
| `segments` | Filters always applied to this metric. |
| `time_column`, `default_grain` | How it's bucketed over time (`none` for a point-in-time metric). |
| `format` | `number`, `usd` or `percent`. |
| `direction` | `higher_is_better`, `lower_is_better` or `neutral`. Used by insights and goals. |
| `synonyms` | Other words people use for it. |
The analyst asks for metrics with up to five metrics, four dimensions and ten filters at a time, over ranges such as `last_month`, `this_quarter`, `year_to_date` or `last_12_months`, with an optional comparison to the previous period.
## Create and change definitions [#create-and-change-definitions]
- **Write one** in the editor: YAML on the left with live checks, notes on the right.
- **Draft them from tables.** On a source's **Overview**, **Draft definitions** has helpers draft datasets and metrics from the tables you pick, each tested against your data. This uses the [background budget](/docs/models#spend-limits).
- **Make this a metric** on an answer's query proposes a metric from it.
- **Starter pack.** The sample company comes with a proposed set of definitions and glossary terms to approve.
## Tests and approval [#tests-and-approval]
Every definition is tested against your data before it's used:
- a dataset must run, return the columns it declares, have a unique grain, land its `n:1` joins on unique keys, and fill its time column;
- a metric must compile and run.
Results show as **Tests passed**, **Needs a look** or **Tests failed**.
Only **owners and admins** save, approve and release definitions. Editing a definition creates a new version: the **Verified** badge clears until it's approved again, and Ask keeps using the approved version meanwhile. Every version keeps its change note, so you can see who changed what and why.
---
# Slack and email
Source: https://opendash.cloud/docs/slack
> Ask OpenDash from Slack with the same checked answers as the web app, and receive routines by Slack or email.
## Set up Slack [#set-up-slack]
Owners and admins connect Slack under **Settings → Slack**. Each OpenDash workspace connects one Slack workspace.
### Create the app from OpenDash's manifest [#create-the-app-from-opendashs-manifest]
On a self-hosted instance, print a manifest for your address:
```bash
pnpm slack:manifest https://opendash.example.com --socket
```
Create a Slack app from it. With `--socket` it uses Socket Mode, so Slack needs no public address to send events to.
### Put its keys in OpenDash's settings [#put-its-keys-in-opendashs-settings]
From the app's **Basic Information**, set `SLACK_CLIENT_ID`, `SLACK_CLIENT_SECRET` and `SLACK_SIGNING_SECRET`. For Socket Mode, also create an app-level token with `connections:write` and set it as `SLACK_APP_TOKEN`.
### Restart OpenDash [#restart-opendash]
Both `web` and `worker` read the keys at start.
### Add to Slack [#add-to-slack]
Back in **Settings → Slack**, choose **Add to Slack**.
## Ask from Slack [#ask-from-slack]
Ask in a **direct message**, in the **Agents** tab, or by **@mentioning** the bot in a channel. In a channel thread, mention the bot again for follow-ups. A message sent while it's working is added to what it's working on.
The first time someone asks, they get a private link to connect their Slack account to OpenDash. It works once, for 10 minutes, and their Slack email must match their OpenDash account. They can unlink under **Settings → Security**.
## Replies [#replies]
Replies carry the same checks as the web app, in their footer:
- **Verified from definitions an admin approved**: the metric path.
- **Every number checked against its query**: the gate passed.
- **Unverified: …**: what couldn't be checked.
Answers with numbers attach a PDF and the cited rows as CSV. Feedback, **Investigate** and **Dismiss** on findings, and learning approvals all work right in Slack.
You can attach text or Markdown files (up to three, 1 MB each) for context.
In Slack the analyst uses only [connected services](/docs/connections) shared with everyone; a call that needs your sign-in or approval asks you to allow it in OpenDash. Dashboards are built in OpenDash, not from Slack.
## Email [#email]
OpenDash sends two kinds of email:
- **Sign-in and account email** (sign-up, sign-in links, password reset), which every instance needs. Configure Resend or any SMTP server; see [Configuration](/docs/self-hosting/configuration#email).
- **Routine deliveries**: a scheduled question's answer, what OpenDash found, a finding told at once or the daily roundup, and a notice to a routine's owner when it paused itself, to the people a routine names. Every one has a one-click unsubscribe.
---
# Connect a source
Source: https://opendash.cloud/docs/sources
> Connect PostgreSQL, MySQL or ClickHouse through a read-only user, choose what OpenDash learns, and keep the connection safe.
A source is a database OpenDash reads. Owners and admins connect sources under **Data → Connect source**.
| Database | Supported versions |
|---|---|
| PostgreSQL | 12 and later, including Neon, Supabase, Amazon RDS and Cloud SQL |
| MySQL | 8.4 and later |
| ClickHouse | 24.3 and later |
Snowflake and BigQuery are on the way.
## Connect [#connect]
### Create a read-only user [#create-a-read-only-user]
OpenDash only needs to read. Run this on your database as an admin (replace the password and database name):
```sql
-- PostgreSQL
CREATE ROLE opendash_reader LOGIN PASSWORD '…';
GRANT CONNECT ON DATABASE your_database TO opendash_reader;
GRANT USAGE ON SCHEMA public TO opendash_reader;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO opendash_reader;
ALTER DEFAULT PRIVILEGES IN SCHEMA public
GRANT SELECT ON TABLES TO opendash_reader;
```
```sql
-- MySQL
CREATE USER 'opendash_reader'@'%' IDENTIFIED BY '…';
GRANT SELECT ON your_database.* TO 'opendash_reader'@'%';
```
```sql
-- ClickHouse
CREATE USER opendash_reader IDENTIFIED BY '…'
SETTINGS readonly = 2;
GRANT SELECT ON your_database.* TO opendash_reader;
```
The connect form shows the same SQL with your database name filled in.
### Let OpenDash reach the database [#let-opendash-reach-the-database]
Only OpenDash's **workers** connect to your databases. Allow their address through your firewall. Self-hosted instances can reach private addresses; on a hosted instance, the connect form lists the outbound IPs to allowlist.
### Test the connection [#test-the-connection]
Fill in the form and choose **Test connection**. The check connects as your user and tells you what it can do:
- **This user can change data**: you can still **Connect anyway**, but a read-only user is safer. Every query runs in a read-only session regardless.
- **This user can't be connected**: it reaches beyond the data, and there is no override.
### Choose what OpenDash learns [#choose-what-opendash-learns]
Pick the tables that matter (ten are ticked to start). Picked tables are profiled on every sync. The others are known by name and profiled the first time a question reads them.
## Syncs [#syncs]
A sync reads the schema, profiles the tables you picked, and reads how your team queries the database. Choose **Daily**, **Every 6 hours**, or **Off** (sync on demand with **Sync now**) on the source's **Settings** tab.
Under **Query limits** you can set how many queries run in parallel, the statement timeout, and the maximum rows a query may read.
## TLS [#tls]
New sources verify the server's certificate (`verify-full`) by default: it must chain to a trusted CA and name the host you typed.
| Mode | What it does |
|---|---|
| `verify-full` | Encrypted, and proves which server answered. If your own CA signed the certificate, paste it on the form; OpenDash trusts only it for that source. |
| `require` | Encrypted, but any server answering at this address is accepted. Use only on a private network. |
| `disable` | Everything in clear text. Use only on a private network. |
ClickHouse connects over HTTPS on port 8443 by default.
## ClickHouse notes [#clickhouse-notes]
- Prefer **`readonly = 2`** for OpenDash's user: it can't write, but can take the per-query limits OpenDash sets.
- A user with `readonly = 1` can't take any per-query setting, so OpenDash accepts it only when the server already enforces what OpenDash would: a time limit of at most 60 seconds that throws, the analyzer on, and UTC. If the server has `join_use_nulls = 0`, outer joins are refused on that source.
## Personal data [#personal-data]
Columns OpenDash recognises as personal data can be counted and filtered, but their values are never returned: not in answers, and not in the records behind a number.
## Sample data [#sample-data]
- **Sample company:** seed it with `OPENDASH_SEED_DEMO=true` (self-hosted) or `pnpm demo:seed` (development), then connect it like any database. It shows a **Sample data** chip, and **Remove sample data** takes it away.
- **Playground:** **Use the playground** on the connect form connects ClickHouse's public playground (`play.clickhouse.com`, user `explorer`, no password).
---
# Workspaces and roles
Source: https://opendash.cloud/docs/workspaces
> Workspaces, projects, invitations and the four roles, with what each role can do.
## Workspaces [#workspaces]
A workspace is an organization in OpenDash: its members, sources, knowledge, dashboards and routines. Data never crosses between workspaces; every table is separated by row-level security in Postgres. A person can belong to several and switch with **Switch workspace**.
New workspaces get a **Finish setting up** checklist: connect your data, approve your starter pack, ask your first question, invite your team.
## Invitations [#invitations]
Owners and admins invite people under **Settings → Members**. An invitation expires after 7 days. Self-hosted instances are invite-only by default, so an invitation is the only way in, apart from [single sign-on](/docs/self-hosting/enterprise#single-sign-on).
## Roles [#roles]
| Role | Can |
|---|---|
| **Owner** | Everything an admin does, and makes other owners. Manages the license. |
| **Admin** | Manages members and sources, writes and approves knowledge and definitions, reviews feedback, sets up Slack, routines for others, and usage limits. |
| **Member** | Asks questions, builds dashboards, shares conversations, and suggests learnings. |
| **Viewer** | Reads the conversations and dashboards shared with them. Can't ask or build. |
| | Owner | Admin | Member | Viewer |
|---|---|---|---|---|
| Ask questions | ✓ | ✓ | ✓ | |
| Build dashboards | ✓ | ✓ | ✓ | |
| Routines that only reach yourself | ✓ | ✓ | ✓ | ✓ (sends what OpenDash found) |
| Routines that reach others | ✓ | ✓ | | |
| Connect and change sources | ✓ | ✓ | | |
| Write and approve knowledge and definitions | ✓ | ✓ | | |
| Suggest a learning for the team | ✓ | ✓ | ✓ | |
| Connect services (Settings → Connections) | ✓ | ✓ | | |
| Settings: Usage, AI, Slack, Health, Activity, Audit log, Single sign-on, Directory sync | ✓ | ✓ | | |
| License, and making owners | ✓ | | | |
## Projects [#projects]
Projects group conversations and dashboards for some people rather than the whole workspace. Project roles are **Manager**, **Editor** and **Viewer**; a workspace viewer is at most a project viewer. Anything you make can be visible to only you, a project, or the whole workspace. A dashboard can also be shared with specific people, each to view or to edit; for a workspace viewer, an edit share acts as view.
## Audit log [#audit-log]
Every instance records an audit log of what changed and who changed it, under **Settings → Audit log**, kept for 90 days. A tamper-evident chain, exports and longer retention are [enterprise features](/docs/self-hosting/enterprise#audit-chain).