Get started with BoardPulse AI in under 10 minutes

BoardPulse AI ships as a set of Docker services that you can have running on a single machine in minutes. This guide walks you through configuring your environment, pulling the AI model, and sending your first query against the built-in demo dataset.

Prerequisites (NVIDIA GPU — local models only)

If you plan to run AI inference locally with Ollama, your host machine needs NVIDIA GPU support configured for Docker. Skip this step if you are using the cloud or mock provider instead.

sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Cloud and mock providers work on any machine with Docker installed — no GPU required.

Copy and configure your environment file

Copy the example environment file, then open it and set the variables that control your data source and AI provider.

cp .env.example .env

Key variables to review before starting:

Variable	Default	Description
`DEFAULT_SOURCE_DATABASE_URL`	local PostgreSQL	Connection URL for the database BoardPulse AI will query
`DEFAULT_SOURCE_INCLUDE_TABLES`	`sales_orders,invoices,inventory_items`	Comma-separated allowlist of tables the AI can read
`DEFAULT_MODEL_PROVIDER`	`mock`	AI provider: `mock`, `cloud`, or `local`
`OLLAMA_MODEL`	`qwen3:8b`	Model name used when `DEFAULT_MODEL_PROVIDER=local`
`OPENAI_API_KEY`	(empty)	Required when `DEFAULT_MODEL_PROVIDER=cloud`
`SEED_DEMO_DATA`	`true`	Seeds `sales_orders`, `invoices`, and `inventory_items` on startup

Leave SEED_DEMO_DATA=true and DEFAULT_SOURCE_INCLUDE_TABLES at their defaults to use the built-in demo dataset — no external database needed.

Start all services

Use the local-models Docker Compose profile to include the Ollama service alongside the API, admin panel, PostgreSQL, Redis, and Open WebUI.

docker compose --profile local-models up --build -d

If you are using the cloud or mock provider and do not need Ollama, omit the profile flag:

docker compose up --build -d

Always use up -d rather than restart when changing .env. The restart command does not reload environment variables.

Pull the AI model

After the Ollama container is running, download the model. This step is required before the API will return real AI responses when using the local provider.

docker compose exec ollama ollama pull qwen3:8b

The download is several gigabytes. Wait for it to complete before sending queries.

Access the interfaces

Once all containers are healthy, three interfaces are available:

Interface	URL	Purpose
Open WebUI	http://localhost:3002	Conversational chat — select the `boardpulse-executive` model
Admin panel	http://localhost:3001	Workspace configuration and schema inspection
API docs	http://localhost:8000/docs	Interactive Swagger UI for all endpoints

In Open WebUI, select the boardpulse-executive model from the model selector to route queries through the BoardPulse AI backend.

Run your first query

The demo dataset is seeded automatically on startup and contains three tables: sales_orders, invoices, and inventory_items. Send a query using curl or any HTTP client:

curl -s -X POST http://localhost:8000/api/v1/chat/query \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are the top 10 sales orders by total amount?",
    "workspace_id": "default",
    "include_sql": true
  }'

A successful response looks like this:

{
  "answer": "Here are the top 10 sales orders by total amount...",
  "sql": "SELECT id, customer_name, total_amount FROM sales_orders ORDER BY total_amount DESC LIMIT 10",
  "executed_sql": "SELECT id, customer_name, total_amount FROM sales_orders ORDER BY total_amount DESC LIMIT 10",
  "provider": "mock",
  "table": {
    "columns": ["id", "customer_name", "total_amount"],
    "rows": [{"id": 1001, "customer_name": "Acme Corp", "total_amount": 48200.00}],
    "row_count": 1
  },
  "exports": [
    { "format": "csv", "filename": "top-10-sales-orders-1714123456.csv", "url": "/api/v1/exports/top-10-sales-orders-1714123456.csv" },
    { "format": "xlsx", "filename": "top-10-sales-orders-1714123456.xlsx", "url": "/api/v1/exports/top-10-sales-orders-1714123456.xlsx" }
  ],
  "warnings": [],
  "meta": {
    "source_dialect": "postgresql",
    "approved_tables": ["sales_orders", "invoices", "inventory_items"],
    "row_count": 10
  }
}

The sql field shows exactly what was executed — nothing runs without passing the SQL guardrail layer first.

Next steps

Connect your database

Replace the demo dataset with your own Supabase, RDS, or on-premise PostgreSQL instance

Configure model providers

Switch from mock to OpenAI or a local Ollama model for real AI responses

SQL guardrails

Understand how BoardPulse AI validates every query before execution

API reference

Full request and response schema for the chat endpoint

Get Started

Configuration

Core Features

Deployment

Get started with BoardPulse AI in under 10 minutes

Next steps

Connect your database

Configure model providers

SQL guardrails

API reference

​Next steps

Connect your database

Configure model providers

SQL guardrails

API reference

Next steps