Run db-agent Locally: Text-to-SQL AI Agent with Ollama (Windows & Mac)

This guide shows you how to run db-agent, an open-source text-to-SQL AI agent, on your own computer. You type a question in plain English, and db-agent writes a read-only SQL query, runs it against SQLite or your own Postgres database, and shows you the results. The AI model runs locally through Ollama (we use the small, free Qwen 2.5 Coder 0.5B model), so there is no cloud account and no API key.

It works on Windows and Mac. Every command is copy-paste ready, with instant fixes for the errors people hit most often.

What you need: Git, Node.js v22.5 or higher, and Ollama. All three are covered in the steps below.

Prefer a hosted setup? If you would rather run db-agent as an app on a free Databricks workspace instead of on your laptop, follow Run a Text-to-SQL AI Agent on Databricks Free Edition.

Step 0: Install the Prerequisites (One-Time Setup)

Before downloading the project, your computer needs two base tools: Git (to download the code) and Node.js v22.5 or higher (to run the app and its built-in SQLite database).

On Mac (open the "Terminal" app)

1. Check/Install Git:

   git --version

   

   (If a pop-up opens asking to install "Command Line Developer Tools", click Install.)

2. Install Node.js (v22+): Go to nodejs.org, download the macOS Installer (.pkg) for v22 (LTS), and click through the installer.

3. Verify Node version:

   node -v

   (Must show v22.5.0 or higher.)

   

On Windows (open "PowerShell")

1. Install Git: Download and run the installer from git-scm.com/download/win (just click Next on all screens).

2. Install Node.js (v22+): Go to nodejs.org, download the Windows Installer (.msi) for v22 (LTS), and install it.

3. CRITICAL: Close your PowerShell window and open a brand new one, then verify:

   git --version
   node -v

Troubleshooting Step 0

• Error: 'node' or 'git' is not recognized as an internal or external command (Windows) or command not found (Mac).
  • Why it happens: Your terminal doesn't know the tool was just installed.
  • Fix: Completely close your Terminal/PowerShell window and open a fresh one. If it still fails on Windows, restart your computer so the system PATH updates.
• Error: Error: Cannot find module 'node:sqlite' (happens later when starting the app).
  • Why it happens: Your Node.js version is older than v22.5.0 (for example v18 or v20), which lacks the built-in SQLite engine.
  • Fix: Download and install the latest v22 LTS from nodejs.org right over your existing installation.

Step 1: Install Ollama and Download the Qwen 2.5 Coder (0.5B) Model

Ollama is the local AI engine on your computer. It runs models completely offline without cloud subscriptions or API keys. Choose either the one-line terminal installer or the graphical installer below.

1. Install the Ollama app

Method A: One-line automated command (fastest)

Run the official script directly in your terminal to download, configure and register Ollama automatically.

On Mac (open Terminal):

curl -fsSL https://ollama.com/install.sh | sh

(Behind the scenes: it fetches Ollama's official setup script and links the CLI tools to your Mac. If it asks for your password, type it and press Enter. No characters will appear on screen.)

Type the password after this step, and then you will see the progress as shown below.

On Windows (open PowerShell as Administrator):

irm https://ollama.com/install.ps1 | iex

(Behind the scenes: irm downloads the official Windows installer script, and iex runs the silent setup without any browser wizard.)

Method B: Graphical installer (standard setup wizard)

If you prefer clicking through an installer window instead of using scripts:

On Mac:

1. Visit ollama.com/download and click Download for macOS.
2. Unzip the downloaded archive and drag the Ollama icon into your Applications folder.
3. Open Ollama from Applications once so it can register command-line permissions.

On Windows:

1. Visit ollama.com/download and download OllamaSetup.exe.
2. Run OllamaSetup.exe and complete the on-screen steps.
3. Verify that the Ollama llama icon appears in your taskbar system tray (bottom-right near the clock).

2. Download the AI model

1. Open your terminal (Terminal on macOS or PowerShell on Windows).
2. Run the following command:

ollama run qwen2.5-coder:0.5b-instruct

This command downloads the model if it isn't already available and starts it.

To exit the session, type /bye.

Verification: run the list command to make sure the model is ready:

ollama list

Expected output: you should see qwen2.5-coder:0.5b-instruct listed under NAME.

One important configuration change: to use it in db-agent, update the model name in your .env file too (you will create that file in Step 3):

LLM_MODEL=qwen2.5-coder:0.5b-instruct

Step 1 Troubleshooting Matrix

Step 2: Download the Project Code

Run these commands in your Terminal (Mac) or PowerShell (Windows) to download the project and move into the app folder:

# 1. Download the repository
git clone https://github.com/db-agent/db-agent.git
 
# 2. Enter the main folder
cd db-agent
 
# 3. Enter the application directory
cd app

Troubleshooting Step 2

• Error: fatal: destination path 'db-agent' already exists and is not an empty directory.
  • Why it happens: You already ran git clone earlier in this same folder.
  • Fix: Skip the clone step and just move into the folder: cd db-agent/app.
• Error: cd: no such file or directory: app
  • Why it happens: You are already inside the app folder, or still outside db-agent.
  • Fix: Run pwd (Mac) or cd (Windows) to see where you are. Make sure your folder path ends with /db-agent/app.

Step 3: Create and Edit the .env Configuration File

The app uses a hidden file named .env to know which AI model and database to use. You will copy the template file (.env.example) into a real .env file and update it.

1. Copy the template file

(Make sure your terminal is inside the db-agent/app folder.)

Mac:

cp .env.example .env

Windows (PowerShell):

Copy-Item .env.example .env

(If you are using the old Command Prompt cmd, run copy .env.example .env.)

2. Open .env in VS Code

Choose whichever method is easiest.

Method A: From the terminal (fastest)

code .env

Method B: Graphical / drag-and-drop (no terminal setup needed)

1. Open the Visual Studio Code application.
2. Click File > Open Folder... (or press Cmd + O on Mac / Ctrl + O on Windows).
3. Select the db-agent/app folder and click Open.
4. In the left-hand Explorer sidebar, click .env to open it in the editor.

3. Update the settings

Find these lines in the file (or paste them at the very bottom) so the app uses your local Ollama Qwen 2.5 Coder 0.5B model and the built-in SQLite demo database:

# --- AI Model Settings (Local Ollama) ---
LLM_BASE_URL=http://localhost:11434/v1
LLM_API_KEY=ollama
LLM_MODEL=qwen2.5-coder:0.5b-instruct
 
# --- Database Settings ---
# Keep 'sqlite' to test immediately with the built-in retail demo database (demo.db)
SQL_ENGINE=sqlite
 
# --- Port & Memory ---
PORT=3001
MEMORY_ENABLED=false

Optional: Connect db-agent to Your Own Postgres Database

Use this when you already have a Postgres database, on your Mac or in the cloud. You need its host, port, database name, username and password. db-agent only reads data. It never changes it, but a read-only user is still safest.

O1. Edit .env in VS Code

1. Change SQL_ENGINE=sqlite to SQL_ENGINE=postgres.
2. Add these two lines at the end, filled in with your details:

DB_URL=postgresql://USERNAME:PASSWORD@HOST:5432/DATABASE
PG_SSL=false

Keep PG_SSL=false for a database on your own computer. Delete that line for a cloud database (AWS, Azure, Supabase, Neon), because they need a secure connection. If your tables aren't in the public schema, also add PG_SCHEMA=yourschema.

Notes:

• Enter DB_URL as explained above.
• You must supply the password (look for the connection details in your database properties).

Video: where to find your Postgres connection details

Watch on Loom if the video does not load.

Video: set up a new Postgres server

Watch on Loom if the video does not load.

O2. Save, then start db-agent in the db-agent/app folder:

npm start

You should see SQL engine: postgres. Open http://localhost:3001 and ask about your own tables.

Press Cmd + S (Mac) or Ctrl + S (Windows) to save, then close the editor.

Troubleshooting Step 3

• Error (Windows trap): your changes in .env are completely ignored by the app.
  • Why it happens: Windows Notepad sometimes silently saves the file as .env.txt instead of .env.
  • Fix: Always create the file with the terminal command (Copy-Item .env.example .env) first, and then open it with notepad .env.
• Error: SyntaxError or Invalid URL when starting the app.
  • Why it happens: Spaces around the = sign (for example LLM_MODEL = qwen2.5-coder:0.5b-instruct), or forgetting /v1 at the end of http://localhost:11434/v1.
  • Fix: Remove all spaces around = and make sure LLM_BASE_URL=http://localhost:11434/v1 is exact.

Step 4: Run the Application

Now compile the web interface and start the server.

On Mac (automated one-click script)

Inside the db-agent/app folder, run:

chmod +x run_local.sh
./run_local.sh

(The script checks Ollama, installs packages, builds the React UI, and starts the server.)

On Windows (and the manual Mac method)

Windows PowerShell cannot run .sh (Mac/Linux bash) scripts natively. Instead, run the three commands inside that script directly:

# 1. Install backend and frontend packages (takes 1-2 minutes the first time)
npm install
 
# 2. Build the React web interface
npm run build
 
# 3. Start the db-agent server
npm start

Open the app

Once your terminal says the server is listening, open your web browser (Chrome, Edge, Safari) and go to http://localhost:3001. Sample screens are at the end of this page.

Step 4 Troubleshooting (Common Runtime Errors)

Quick Cheat Sheet: Starting It Next Time

Once you've completed this setup, you never need to reinstall anything. Next time you turn on your computer:

1. Make sure the Ollama app is running.

2. Open Terminal / PowerShell, go to the folder, and start the server:

   cd db-agent/app
   npm start

3. Open http://localhost:3001. Press Ctrl + C in the terminal whenever you want to turn the server off.

Sample Screens

The db-agent home screen:

An example question: for a heavy query, db-agent shows the estimated cost and asks you to approve before it runs:

The example query answered:

Local setup vs Databricks Free Edition

Both options use the same open-source db-agent. Start local to learn how an AI agent turns a question into SQL, then move to Databricks when your data lives there. The hosted route is covered in Run a Text-to-SQL AI Agent on Databricks Free Edition.

Frequently Asked Questions

Do I need an API key or cloud account to run db-agent locally?

No. With Ollama the model runs on your own computer. The LLM_API_KEY=ollama value in .env is just a placeholder the app expects.

Does db-agent work on Windows as well as Mac?

Yes. The steps above cover both. On Windows, run npm install, npm run build and npm start directly, because PowerShell cannot run the run_local.sh script (Git Bash can).

Which Node.js version do I need?

Node.js v22.5.0 or higher, because db-agent uses the built-in node:sqlite module. Older versions fail with Cannot find module 'node:sqlite'.

Can I connect db-agent to my own Postgres database?

Yes. Set SQL_ENGINE=postgres and add a DB_URL in .env. db-agent only reads data and never changes it, but a read-only database user is still the safest choice.

Is the 0.5B Qwen model good enough?

It is fine for simple, single-step questions and for learning how the agent works. For complex joins, use a larger model such as qwen2.5-coder:3b if your computer has 8 GB of RAM or more.

Can I run db-agent on Databricks Free Edition instead of locally?

Yes, there is a separate guide for deploying db-agent as an app on a free Databricks workspace. See the Databricks Free Edition setup guide linked below.

Where to go next

• The source and issue tracker: github.com/db-agent/db-agent
• Prefer a hosted setup on a free Databricks workspace? See Run a Text-to-SQL AI Agent on Databricks Free Edition.
• More tools in the toolkit: becloudready.com/tools/db-agent