Your first hour

From nothing to a working Curltale AI: install, describe your data, publish, ask a question, connect an agent and add your first documents.

This is the shortest path from zero to a working system. Each step says what you do, what you should see, and where the detail lives. You need a computer with Docker and about an hour. You do not need a database of your own: step 4 has a sample model, and step 6 generates fictional data from it.

1. Install and sign in#

Follow Install: copy the two example files, fill in the required values in .env, run docker compose up -d, open http://localhost:8080 and sign in with the administrator you set in .env.

You should see the home page with an empty ontology and two ways to start. If the page does not load, see Troubleshooting.

Make one decision now: keep a second administrator. Create it in step 7 of this page or later in Users & access > Users. There is no email reset for passwords.

2. Connect an AI endpoint (optional, recommended)#

Open Settings > AI. Enter the address of any OpenAI-compatible server, an API key if it needs one, and a model, then press Test the endpoint.

You should see a success message. Alfred (the built-in assistant) and most of the knowledge library need it. Without it, the model, search, agents, data and the library's storage and search still work.

3. Choose how to describe your data#

The ontology starts empty. There are three ways to fill it, and you can mix them later:

4. Create the first draft#

4a. The sample model (fastest)#

1. Download the sample model. It describes a fictional subscription business with 23 entities: customers, sales orders, subscriptions and price plans, billing, support cases and monthly usage. It is the same model the screenshots in this guide use.
2. Open Ontology > Changes & versions. In the Excel card, choose the file under Upload.
3. Read the report. It lists problems with sheet, row and column, and what would be created. A file without errors becomes a draft.

4b. Your own workbook#

1. On Changes & versions, download the blank template.
2. Fill it in. Start with the minimal workbook and add detail as you go.
3. Upload it. Fix whatever the report lists, and upload again.

4c. A connector#

1. Open Settings > Connectors and add your database: see Connect your data.
2. Press Test, then Read structure, pick the schemas and tables, and press Generate draft model.
3. Everything generated is marked needs review. It is a starting point: the meaning, filters and calculated fields are for your modellers to add.

You should see a draft: the Ontology version selector on Entities now offers a draft, and the entity list fills in.

5. Validate and publish#

On Ontology > Changes & versions, press Validate. Fix anything it lists (warnings about SQL that does not run on the connected database are advice, not blockers). Then press Publish.

Publishing builds and embeds the search index in the background. You can leave the page; the progress shows when you come back.

You should see the published version listed, and Entities showing it. Agents and Alfred now read this version. How the draft and publishing work: Drafts, versions and publishing.

6. Get data to ask about#

• With a connector: go to Settings > Connectors, press Use for data, and confirm the coverage check. Then open Data > Browse and Model check.
• With the sample model or your own workbook and no database: open Data > Browse and build the demo database. Choose a scale (small is enough), keep the seed, and decide whether to let the AI model propose realistic values. It generates fictional rows that follow your model's keys, links and allowed values. Details: the demo database.

You should see tables with row counts. Open one to browse its rows.

7. Ask a question#

Press ✦ Ask Alfred at the bottom right and ask something about the model or the data, for example "How many active subscriptions do we have?"

You should see Alfred show each tool it calls, then an answer that uses your own definitions (what "active" means), with the entities and fields it used as links. If Alfred is off, check step 2.

While you are in Users & access > Users, add a second administrator and the people who will model, publish and edit. Roles are explained in Users, roles and access.

8. Connect an agent#

1. Open Users & access > Tokens & MCP and create a token. Give it the entitlements the agent needs: new tokens see structure only until you grant data.
2. Copy the connection command shown there. For Claude Code it looks like this:

claude mcp add --transport http curltale https://<your-host>/mcp --header "Authorization: Bearer <token>"

1. Ask the agent a question that needs your model.

You should see the agent call get_access, describe, plan_query and query_data. More in Connect an agent and The tools.

9. Add your first documents (optional)#

1. Open Knowledge > Collections and create a collection. Choose its usage tag: Public (may be shared with customers) or Internal.
2. Make sure the people who will add documents have the editor role and a write grant on the collection (Users & access > Users and the collection's access table).
3. Open Knowledge > Sources and drop a few files in, or press Add a web page.
4. Watch the status change from waiting to ready. When a source is ready, open its page, then Knowledge > Topics to read the topics built from it.
5. Open Knowledge > Review to see what waits for a person.

You should see topic pages with citation chips and, beside them, every claim with its exact quote. How it works: From document to topic.

10. What to do next#