Getting started

Your first diagram

From a fresh account to a checked diagram in a few minutes. AI is entirely optional — everything below works with no key configured.

1. Create an account

On a hosted or self-hosted instance, open the app and choose Get started to sign up, or Sign in if you already have an account.

2. Choose a space

You land in your Personal space — a solo area with your own BYOK AI (no shared catalog). To collaborate, create an Organization: invite members (owner / admin / member) and group work into Workspaces with their own roles (admin / editor / viewer), a shared Asset Catalog, and shared AI. Switch between spaces any time with the context switcher.

3. Draw a diagram

From the dashboard, create a new diagram and pick a kind — BPMN, Sequence, or C4. The canvas is keyboard-first; press ⌘K for the command palette to reach any action quickly. Build your flow with events, tasks, and gateways (for BPMN), wiring elements together with sequence flows. Every change is versioned automatically; you can also name a version, diff revisions, and restore.

4. Run the inspector

The deterministic logic inspector runs continuously as you edit. It flags structural problems — deadlocks, unreachable steps, missing start/end events, gateway split/join mismatches, and soundness violations — as findings pinned to the offending element.

Each finding has a severity: error, warning, or info.
Click a finding to fly the camera to the element it concerns.
Where a quick-fix exists, apply it with one click.

The inspector is computed, not generated — its findings are the same whether you run them in the editor, the CLI, or over MCP.

5. (Optional) Connect an AI provider

AI is progressive enhancement. To enable the AI co-editor — generate BPMN from a prompt, chat grounded on findings and the Asset Catalog, AI-proposed edits you review (approve, roll back, or keep refining), and Markdown doc-gen — connect a provider with your own key in your current space.

Open settings for your personal space or organization and find the AI providers / connections section.
Choose a provider (Anthropic, OpenAI, Google, Mistral, Ollama, or OpenRouter) and paste your API key. Keys are encrypted at rest and never leave your instance.
Your first connection becomes the default automatically. In the workbench, use the model switcher to pick any connected model per session. For local inference, point at Ollama — no key required, just a reachable endpoint.

Once connected, a quiet AI: connected pill appears and ✦ affordances light up where AI can help. See AI providers for the full list and how keys are stored.

6. Comment & @mention (organizations)

In an organization, leave threaded comments anchored to a specific element or to the whole diagram, and @mention teammates to pull them in. Mentions and replies surface in the in-app notification bell. Collaboration is async — no realtime cursors — so it works across time zones. (Comments are available in personal space too, just without teammates to mention.)

7. Export

From the workbench top bar, download the source .bpmn or export the diagram as PNG or PDF to drop into docs, tickets, or reviews.

Running it yourself

To stand up your own instance, clone the repository, start Postgres, apply the schema, and run the app:

local development

pnpm install

# 1. Start Postgres (or point DATABASE_URL at your own)
docker compose -f deploy/docker-compose.yml up -d

# 2. Configure env (the app and migrations both read it)
cp .env.example apps/web/.env.local
#    then set BETTER_AUTH_SECRET — e.g. openssl rand -base64 32

# 3. Apply the schema
pnpm --filter @claril/db db:migrate

# 4. Run the app  ->  http://localhost:3000
pnpm dev

For a one-command production stack, see Self-hosting.