Documentation

How to use DataAgent

Install it, run your first analysis, find your data, get a local model, and back it up — plus the API reference for the backend that powers the interface.

Install

DataAgent for Windows ships as one installer, roughly 439 MB. Download DataAgent-Setup.exe from the download page, run it, and launch DataAgent from the Start Menu. The Python runtime, the DuckDB engine, the FastAPI backend and the interface are all inside the installer, so there is nothing to prepare and no developer tooling involved. The one optional extra download is the local model used for AI chat — see Get a local model below; SQL, the spreadsheet workbench, dashboards and exports need no model at all.

Installer DataAgent-Setup.exe (roughly 439 MB) Installs to C:\Program Files\DataAgent Shortcuts Start Menu — DataAgent, DataAgent (web), Uninstall DataAgent Portable build DataAgent.exe — runs from any folder, no install Your data %LOCALAPPDATA%\DataAgent — see "Where your data lives" First account You register it in the app; there is no built-in default

This release is not code-signed yet, so SmartScreen shows an “Unknown publisher” warning: choose More info, then Run anyway. There is also a portable DataAgent.exe that runs from any folder and needs no installation.

What it does

DataAgent is a desktop analytics app for Windows. It puts a warehouse, a SQL editor, a dashboard builder, a spreadsheet workbench and a question-and-answer assistant in one window, all pointed at the same local data.

  • Ask questions — plain English in, an answer with charts and the query that produced it out. Without a model configured, the app falls back to rule-based analysis and says so.
  • Write SQL — a workbench with syntax highlighting, autocomplete, saved queries and a history you can re-run.
  • Load data — CSV, TSV, TXT, JSON, JSONL, NDJSON, Parquet, XLSX and XLS are ingested into a local DuckDB warehouse; SQLite, PostgreSQL and MySQL can be connected live.
  • Build dashboards — a drag-and-drop canvas with 30+ chart types, and a real Power BI .pbix export that carries your data, star schema and DAX measures. Existing .pbix and .pbit files can be imported and rebuilt locally.
  • Export — Excel, PowerPoint, HTML, Markdown, CSV, Parquet and .pbix are fully formatted. The PDF export in this build is a plain text summary, not a laid-out report.

The whole thing runs as one Python process on your machine. There is no hosted DataAgent service in this release, and nothing you upload is sent anywhere unless you configure a model provider yourself.

Your first analysis

Four steps, none of which needs an account anywhere but in the app itself:

  1. Launch DataAgent from the Start Menu and register the first user. On a fresh install that first account is the local administrator; there is no bootstrap token and no cloud sign-up.
  2. Load a file from the Upload screen, or point the Connections screen at a SQLite, PostgreSQL or MySQL database. The schema is inferred on import and the table appears in the warehouse browser straight away.
  3. Ask a question in Chat. The assistant writes the SQL, runs it against the warehouse and returns the answer with a chart. The query travels with the answer and is recorded in the audit log.
  4. Save it — pin the chart to a dashboard, then export the dashboard to .pbix, Excel or PowerPoint.

If you would rather not use the assistant at all, the SQL workbench answers the same question by hand, and every chart in the app can be built from a query you wrote yourself.

Get a local model

AI answers need a model. DataAgent can run one on your own machine, which is the only way to keep your questions and your schema off the network.

  1. Open Settings → AI Provider. The app checks whether Ollama is installed and reachable, and offers a one-click install if it is not.
  2. Pull a model — the onboarding step suggests qwen2.5:7b, which is about 4.7 GB on disk.
  3. Select Ollama as the provider. Detected automatically; no API key needed.
Install Ollama https://ollama.ai/download (or let the app do it) Pull a model ollama pull qwen2.5:7b Select provider Settings — AI Provider — Ollama

With a local model the app keeps working with the network unplugged. Without any model at all, SQL, the spreadsheet workbench, dashboards and exports still work — the assistant simply falls back to rule-based answers and tells you it did.

Where your data lives

The installer writes the application to Program Files; your data goes to a per-user folder so a non-administrator account can use the app and a reinstall cannot wipe it.

%LOCALAPPDATA%\DataAgent\data\ the DuckDB warehouse, your uploads, key material %LOCALAPPDATA%\DataAgent\logs\ app.log, audit.log, runtime-stdout.log %LOCALAPPDATA%\DataAgent\config\ your settings %LOCALAPPDATA%\DataAgent\outputs\ files you export The warehouse itself data\curated\warehouse.duckdb — one file, one writer

The portable build keeps the same layout in a data folder next to the executable. On macOS and Linux the equivalent location is $XDG_DATA_HOME/DataAgent.

Backup and restore

A backup is a copy of that folder — but close the app first. DuckDB allows a single writer per file, so a warehouse copied while DataAgent is running can be inconsistent.

  1. Quit DataAgent (the tray icon → Quit, or close the window).
  2. Copy %LOCALAPPDATA%\DataAgent to your backup location.
  3. To restore, put the folder back and start DataAgent. Your tables, dashboards and plan come back with it.

Two files in that folder are secrets: data\.jwt_secret and data\.grant_key. They are what keeps you signed in and what proves a paid plan, so keep them with the backup — and never post them in a support request.

Uninstall

Open Settings → Apps → Installed apps → DataAgent → Uninstall, or use the Uninstall DataAgent shortcut in the Start Menu. The application is removed; your data folder is left alone. Delete %LOCALAPPDATA%\DataAgent yourself once you are sure you do not need it.

AI providers

Ten providers are supported. Pick one in Settings and switch whenever you like — the choice is a setting, not a migration.

  • Ollama — local models including Qwen 2.5, LLaMA 3, Mistral and Phi-3. Detected automatically once running; no key required.
  • LM Studio — a desktop model server for local inference. Detected automatically once running.
  • OpenAI — GPT-4o and GPT-4o-mini. Needs an API key.
  • Anthropic — Claude 3.5 Sonnet and Claude 3 Haiku. Needs an API key.
  • Google Gemini — Gemini 1.5 Pro and Gemini Flash. Needs an API key.
  • DeepSeek — DeepSeek Chat and DeepSeek Coder. Needs an API key.
  • Groq — LLaMA 3 on Groq hardware for low-latency inference. Needs an API key.
  • xAI — Grok-2. Needs an API key.
  • OpenRouter — one key for many hosted models. Needs an API key.
  • OpenCode — the free hosted tier, for trying the app before you set up a local model.

Whichever you choose, nothing is sent until you ask a question. With Ollama or LM Studio the prompt never leaves the machine.

API reference

The interface is a client of the same FastAPI backend, so anything the screen can do, a script can do. The backend listens on 127.0.0.1:8002 in the desktop build.

# Authentication POST /auth/register # create an account POST /auth/login # sign in, returns a token POST /auth/logout # end the session GET /auth/me # the current user # Assistant POST /ask # ask a question; returns the answer, charts and the SQL POST /ask-sql # SQL-only analysis — no model required POST /llm/chat/stream # the same answer, streamed as server-sent events # SQL and the warehouse POST /sql # run a query GET /queries/history # recent and saved queries GET /tables # the tables in the warehouse GET /tables/{table} # one table's schema GET /profile/{table} # column profiling # Data POST /upload # upload a CSV, Excel, Parquet or JSON file GET /tables/{table}/sample # a sample of the rows # Dashboards GET /dashboards # list dashboards POST /dashboards # create one GET /dashboards/{id} # one dashboard PUT /dashboards/{id} # update one GET /dashboards/{id}/export/pbit # Power BI .pbix with your data POST /dashboards/{id}/export/{fmt} # pdf | pptx | xlsx — returns a job id GET /dashboards/export/{jobId} # job status GET /dashboards/export/download/{jobId} # the finished file # Export a table GET /export/csv/{table} GET /export/xlsx/{table} GET /export/pptx/{table} GET /export/html/{table} GET /export/markdown/{table} GET /export/parquet/{table} GET /export/pdf/{table} # plain text summary in this build # Plan GET /subscriptions/plans # the three plans and their limits GET /subscriptions/me # the plan on this account

Authenticate with the token from /auth/login as a bearer token. Every route that returns data answers with JSON; the export routes return files.

Troubleshooting

  • “No model” answers. Check Settings → AI Provider. With no model configured the assistant answers from rules and says so; install Ollama and pull a model to switch it on.
  • “File is already open” from DuckDB. Only one process may write to the warehouse. Close a second DataAgent instance, or the DuckDB MCP server, and retry.
  • The app will not start. On Windows the desktop window needs the Microsoft Edge WebView2 runtime. The preflight check names it if it is missing.
  • SmartScreen blocked the installer. The release is not code-signed yet. Choose More info → Run anyway, or run the portable build instead.
  • Your plan disappeared. A plan is tied to the account and to the key material in your data folder. If data\.grant_key is missing, the app cannot verify a paid plan and falls back to free.
  • Something else. The logs are in %LOCALAPPDATA%\DataAgent\logs. See the contact page for exactly which three files to send.

Security

What the build actually enforces, and what it does not:

  • Authentication — token-based sessions with hashed passwords. The signing key is generated on first run and stored outside the repository.
  • Role-based access — Admin, Editor, Analyst and Viewer roles, enforced by default on every mutating route.
  • Audit logging — sign-ins, queries, exports and settings changes are recorded and exportable.
  • Safe SQL — user input is never concatenated into SQL, and analysis runs against a read-only connection.
  • Upload checking — a file's contents are sniffed against its extension, so a renamed archive cannot slip through.
  • No telemetry from the app — the desktop build sends no telemetry, no analytics and no crash reports. The only outbound calls are the update check, the model provider you configure, and the entitlement service a paid plan uses.
  • Single sign-on and row-level security — both are implemented but ship disabled by default (config/settings.yaml). Turn them on deliberately; they are not active in a fresh install.
  • API keys and organisation structure — available on the Pro and Lifetime plans, not on the free tier.

The full network disclosure is on the security page; the source is open under the GNU AGPL v3 licence, so every one of these claims is checkable.

Looking for quick answers?

Read the FAQ See what's new