Run Byaan locally or deploy the Team Version
The Mac app is free for individuals and runs entirely on your machine. The team version is one-line Docker — multi-user auth, RBAC, Slack, Google OAuth, and automatic HTTPS, all in your VPC.
Quick start
Download Byaan for macOS.
Connect a database or upload CSV, Excel, Parquet, or JSON files.
Let Byaan inspect schemas and learn your business definitions.
Ask questions in natural language and turn answers into dashboards.
Core capabilities
Connect to your data
PostgreSQL, MongoDB, MySQL, MariaDB, SQLite, MSSQL, DuckDB, plus CSV, Excel, Parquet, and JSON files.
Ask in plain English
Byaan converts business questions into read-only analysis and preserves your metric definitions and table context.
Build dashboards
Generate interactive dashboards with filters, charts, and reusable analysis patterns from notebooks.
Use MCP
Expose Byaan as an MCP server for Claude Code, Cursor, Codex, and other MCP-compatible clients.
Read-only by design
DDL and DML are blocked. Production databases stay safe — Byaan can only inspect, never write.
Export and share
Export standalone HTML dashboards, share notebook links, or generate PDFs for stakeholders.
Team Version
Full README →One container ships PostgreSQL, the FastAPI backend, the React frontend, and Caddy. Live on port 8080 in five minutes. AGPL licensed.
Drops start.sh and .env into a byaan directory. Set admin email, password, and org name in .env, then run ./start.sh.
Requirements
- Linux server (Ubuntu 20.04+, Debian 11+, or any Docker-compatible OS)
- 2 GB RAM minimum (4 GB recommended), 10 GB disk
- Ports 80 and 443 (or 8080 for local)
- Docker installed
Required environment variables
| Variable | Description |
|---|---|
| APP_SECRET | JWT signing + encryption key (auto-generated by installer) |
| MASTER_USER_EMAIL | Admin user email |
| MASTER_USER_PASSWORD | Admin password (min 8 characters) |
| ORG_NAME | Your organization name |
Optional
| Variable | Description |
|---|---|
| ENCRYPTION_KEY | Separate 32-byte hex key for credential encryption (recommended) |
| DOMAIN | Custom domain (e.g. app.yourcompany.com) — enables Let's Encrypt HTTPS |
| ACME_EMAIL | Email for Let's Encrypt cert notifications |
| GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET | Google OAuth (optional SSO) |
| SMTP_HOST / SMTP_USERNAME / SMTP_PASSWORD | SMTP for team invites (optional) |
Commands
./start.shStart Byaan./start.sh stopStop Byaan./start.sh updateUpdate to latest version./start.sh logsView all logs./start.sh logs backendView backend logs only./start.sh logs caddyView web server logs./start.sh logs postgresView database logs./start.sh statusCheck if running./start.sh removeRemove container, keep data./start.sh remove --dataRemove container and all data
Backups
Data lives in the byaan_data Docker volume. Snapshot via pg_dump or volume tar.
Team invites
Configure SMTP to email invitations automatically. Or skip SMTP — invitations are still created and the admin copies the generated link from the Members page to share manually.
Updates & logs
Keep your Team Version current with a single command. Data and configuration are preserved across updates. Use the log commands to monitor or debug any service.
Zero-downtime updates
./start.sh update pulls the latest image, recreates the container, and mounts the same byaan_data volume — no data loss.
Targeted log tailing
Pass a service name to scope output: backend, caddy, or postgres. Omit it to follow all services at once.
Security model
The Mac app keeps database credentials, queries, and result data on your computer. You choose the model provider and keys, and Byaan connects from your environment.
The team version runs in your VPC. Byaan-hosted infrastructure is never in the data path — credentials, queries, and results stay where you put them.
Both versions are read-only by design: DDL and DML are blocked, so production databases can be inspected without risk of accidental writes.
Have a question?
Open an issue or jump into discussions on GitHub.