Run Upsolve locally

Upsolve Local runs the Upsolve analytics agent on your own computer, a Mac, a Linux machine or a Windows PC (inside WSL 2), against a PostgreSQL server you already have. You ask questions about your data in plain English, and the agent writes and runs the SQL. There is no account and no login: the app only answers on 127.0.0.1, the loopback address of your computer, so other computers cannot reach it. See Who can reach it, and what leaves your computer before you point it at sensitive data.

npx @upsolve-labs/analytics

Upsolve Local is early. Some screens are still being built, and this page says plainly where that affects you.

What you need

You need	Details
A Mac, a Linux machine or WSL 2	macOS on Apple silicon or Intel, or 64-bit Linux (x64 or arm64) with glibc: Ubuntu, Debian, Fedora, RHEL and most other distributions, but not Alpine. On Windows, Upsolve Local runs inside WSL 2, in Ubuntu: see Windows (WSL 2).
Node.js 22.19 or newer	Or Node.js 24.11 or newer. Check with `node --version`. The installer tells you what to do if yours is older.
PostgreSQL 14 or newer	Running on the same computer, or reachable from it. Upsolve keeps its own data in a database it creates there. See below.
An AI provider key	An API key for Anthropic, OpenAI or OpenRouter, or the address of a server you run yourself that speaks the OpenAI API. You enter it in the app. See Give Upsolve an AI provider.
A database to ask questions about	Upsolve connects to it from inside the app. It can be on the same PostgreSQL server or somewhere else.

PostgreSQL

Upsolve Local stores its workspaces, chat history and settings in PostgreSQL, in a database named upsolve. If you have no server yet, install one of these:

Homebrew
Postgres.app
Debian or Ubuntu
Docker

brew install postgresql@16
brew services start postgresql@16

Download Postgres.app, open it and press Initialize or Start. It listens on localhost:5432, the same place Homebrew does.

sudo apt install postgresql
sudo -u postgres createuser --createdb --pwprompt "$USER"

The second command gives your Linux user a role that may create databases, and asks for its password. The server listens on localhost:5432 and asks for that password, so give it to Upsolve the first time:

npx @upsolve-labs/analytics --database-url "postgres://$USER:PASSWORD@localhost:5432/upsolve"

docker run -d --name upsolve-postgres --restart unless-stopped \
  -e POSTGRES_PASSWORD=choose-a-password -p 127.0.0.1:5432:5432 \
  -v upsolve-postgres:/var/lib/postgresql/data postgres:16
npx @upsolve-labs/analytics --database-url postgres://postgres:choose-a-password@localhost:5432/upsolve

Any Linux distribution with Docker, and a Mac with Docker Desktop. The volume keeps the data when the container is replaced.

Upsolve looks for a server on localhost:5432 as your user name, and creates the upsolve database there. Homebrew and Postgres.app give your macOS user a role that is allowed to create databases, with no password, so on a Mac there is nothing to pass. If your server is somewhere else, or needs a password, point Upsolve at it:

npx @upsolve-labs/analytics --database-url postgres://USER:PASSWORD@HOST:5432/upsolve

If you have DATABASE_URL or PGHOST, PGUSER and similar variables set in your shell for other work, Upsolve takes that server and role (never that database: it always uses one called upsolve). Unset them for the first run if that is not the server you want.

The database Upsolve uses has to be empty or already Upsolve’s. It refuses a database that holds somebody else’s tables, so it never runs its migrations in your application’s database.

Windows (WSL 2)

Upsolve Local has no Windows build of its own. It runs in WSL 2, the Linux that Windows 10 and 11 run beside Windows, where it is an ordinary Linux install: everything on this page applies inside Ubuntu, and what is particular to Windows is below. Run in PowerShell or the Command Prompt, npx @upsolve-labs/analytics only sends you here.

Install WSL 2 with Ubuntu

In PowerShell, opened as administrator:

wsl --install -d Ubuntu

Restart Windows if it asks, then open Ubuntu from the Start menu and choose a Linux user name and password. Check that it runs on WSL 2: wsl -l -v, in PowerShell, lists Ubuntu with 2 under VERSION. If it says 1, run wsl --set-version Ubuntu 2.Every command from here on runs in the Ubuntu terminal, not in PowerShell.

Install Node.js in Ubuntu

Ubuntu’s own nodejs package is often older than the 22.19 Upsolve needs. Install Node.js 24 from NodeSource:

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs

which node prints /usr/bin/node. Install it this way rather than with nvm if you will use Upsolve from Claude Desktop or another assistant on Windows: it starts Upsolve’s MCP server with wsl, which does not read your .bashrc, so it cannot find a Node.js that nvm installed.

Install PostgreSQL in Ubuntu

sudo apt install -y postgresql
sudo -u postgres createuser --createdb --pwprompt "$USER"

The same as the Debian or Ubuntu tab above: the second command gives your Linux user a role that may create databases, and asks for its password. Install it in Ubuntu even if Windows already has a PostgreSQL server. From inside WSL 2 that server is not at localhost, which is where Upsolve looks.If createuser says it cannot connect to the server, your WSL runs without systemd, which starts no services. Start PostgreSQL with sudo service postgresql start, and again after each restart of WSL. Current Ubuntu images run systemd and start it by themselves.

Start Upsolve in Ubuntu

npx @upsolve-labs/analytics --database-url "postgres://$USER:PASSWORD@localhost:5432/upsolve"

Then open the address Upsolve prints, http://127.0.0.1:4400 unless it took another port, in your Windows browser. If it does not load, use localhost in place of 127.0.0.1. WSL 2 forwards localhost to Ubuntu, so Edge or Chrome on Windows reaches the app. Ubuntu usually cannot open the Windows browser for you, so it may not open by itself.Upsolve’s files, ~/.upsolve/config.json included, are in your Ubuntu home directory, which File Explorer shows as \\wsl$\Ubuntu\home\<you>.

To use Upsolve from Claude Desktop on Windows, see Use Upsolve Local from Claude and Codex: Claude Desktop starts the MCP server with wsl npx -y @upsolve-labs/analytics mcp.

Give Upsolve an AI provider

Upsolve needs an AI provider to answer questions. You give it one in the app, not in your terminal: Upsolve asks for it the first time you open it, and the AI provider settings are where you change it later. Pick a provider, paste its key, and Upsolve checks the key with a one-token call before it saves anything.

Provider	What you enter
Anthropic	Your API key.
OpenAI	Your API key.
OpenRouter	Your API key, and optionally the model you want to use.
Other (OpenAI-compatible)	Experimental. The address of a server that speaks the OpenAI chat-completions API (Ollama, vLLM and LM Studio do), a model name, and any placeholder as the key if the server does not check one. Whether such a model can drive the agent’s tool calls depends on the model.

Each provider has a default pair of models, one for the agent’s reasoning and a cheaper one for short background jobs. You can name your own for either.

The key stays on your computer. Upsolve stores it encrypted, in your upsolve database, with the encryptionKey from ~/.upsolve/config.json, and sends it only to the provider you chose. The app shows the last four characters and never the key itself.
Changes apply to your next chat. There is nothing to restart. A chat that is already running finishes on the provider it started with.
Your terminal’s variables are not used. ANTHROPIC_API_KEY, OPENAI_API_KEY, LLM_PROVIDER and the like are ignored: what answers a chat is the provider saved in the app, and nothing else. If none is saved, the chat says so and names the settings to open. See Troubleshooting.

Install and start

Run one command:

npx @upsolve-labs/analytics

The first time, this:

Downloads Upsolve Local (a few hundred megabytes), checks it against a SHA-256 checksum that ships inside the npm package, and unpacks it into ~/.upsolve/versions/<release>. Anything that does not match is thrown away and never run. Later runs of the same release start immediately, with no download.
Creates ~/.upsolve/config.json, readable only by you, with the secrets that encrypt what Upsolve stores (database passwords, for example). Keep this file. Without it, the data in your database cannot be decrypted.
Finds your PostgreSQL, creates the upsolve database if it is missing, and applies Upsolve’s migrations.
Starts the app on port 4400 and the agent on port 4401 (both on 127.0.0.1; if either port is busy, Upsolve takes the next free pair and remembers it).
Opens your browser at http://127.0.0.1:4400.

You see something like this, with your own numbers:

Downloading Upsolve Local <release> (<size> MB)...
Checksum verified. Unpacking...
Created /Users/<you>/.upsolve/config.json with new secrets (readable only by you). ...
PostgreSQL 16 at <you>@localhost:5432/upsolve (database created)
Applying database migrations...
Migrations: <n> applied, 0 already up to date.
Starting the app on http://127.0.0.1:4400 and the agent on http://127.0.0.1:4401 (release ...)...
Upsolve Local is running at http://127.0.0.1:4400

Leave the terminal open: Upsolve runs in the foreground, and Ctrl-C stops it. If something does not go as shown, Troubleshooting has every message Upsolve prints and what to do about it.

Anything you add after the package name goes to Upsolve’s own command line. npx @upsolve-labs/analytics --no-open starts without opening the browser, and npx @upsolve-labs/analytics start --help lists every option. Upsolve’s own messages write commands as upsolve-analytics <command>; run them as npx @upsolve-labs/analytics <command>.

Your first session

You are signed in automatically as the local user, so there is no login or onboarding to get through. A new install opens on a first-run screen, “Choose your AI provider”.

Choose your AI provider

Pick Anthropic, OpenAI, OpenRouter or a local model (experimental), and enter what it needs: an API key, or for a local model the base URL of a server that speaks the OpenAI API, the model name and, if the server wants one, a key. Press Test connection. Upsolve makes a one-token call to the provider and shows either a check mark with how long it took, or the provider’s own error message. Continue stays disabled until a test passes for the values on screen, and editing a field afterwards disables it again.Below the form, Share anonymous usage stats is on. Switch it off if you would rather send nothing; whichever you leave it on is saved when you press Continue, and you can change it later in Organization settings → Usage stats. See anonymous usage data for exactly what it sends.You can change the provider later in Organization settings → AI provider. It shows the provider and your key as •••• and its last four characters, and has Test (checks the saved key), Replace key and Change provider. A new key or provider is saved only after a passing test and applies to new chats.

Connect your database

The next screen, “Connect your database”, opens on PostgreSQL with localhost and port 5432 filled in: that is the PostgreSQL server on your own computer. Enter the user, password and database you want to ask questions about (or change the host and port for a database somewhere else, or press Choose a different type for another kind of database), then press Test & Create Connection. If the database cannot be reached, the form stays as you left it and shows the database’s own message, for example connect ECONNREFUSED 127.0.0.1:5433 for a port nothing listens on, or password authentication failed for user "me". See the database refuses the connection.

Create a workspace

A workspace is the agent together with the data and context it works from. Upsolve creates your first one, “My first workspace”, as soon as the connection works: it reads the list of tables and columns, which can take a moment on a large database, and then opens workspace setup. Setup runs an AI setup step on your configured provider, which is the first place a missing or wrong API key shows up. When that step finishes, what it wrote is published as the workspace’s next version and made live, so the agent answers with it straight away. You can skip the optional steps (connectors and knowledge files). If the database has no tables yet, workspace creation stops with a message saying so and offers Create again once you have added some.

Chat

When setup finishes, Go to workspace opens the workspace’s Playground, with a first question suggested under the message box (the first table’s row count, for example). If it asks you to prepare the agent first, do that once. Then ask a question about your data, for example “How many orders did we get last month, by week?”. The agent shows the SQL it ran and the chart or table it built.

From there you can add context (a knowledge base, system prompts, MCP connections), save charts into canvases and mark favorites. An MCP connection can point at a server on this computer or your own network (localhost, 127.0.0.1, a 10.x or 192.168.x address): Upsolve Cloud blocks those addresses, Upsolve Local does not. The AI Agent Builder guide walks through all of it. You can also work with Upsolve Local from Claude Code, Claude Desktop or Codex, with no sign-in: one command adds it to your assistant, to build workspaces or to ask them questions. See Use Upsolve Local from Claude and Codex.

What is in Upsolve Local, and what is not

Upsolve Local is the single-user part of Upsolve. It has chat with the analyst agent, the AI-guided workspace setup, the knowledge base, MCP connections, canvases and favorites. It does not have what only makes sense with more than one person or on the web: sign-in, organizations and members, invitations, API keys, billing, dashboards, templates and applications, golden questions and the hosted sample database. Those entries do not appear in the app. A few features are in the app but locked. You can see them, and opening one shows Available on Upsolve Cloud with an Upgrade to Cloud button that starts the upgrade:

Deploy, the workspace section that embeds a workspace in your product.
Sharing: the Share chat button, a canvas’s share button, and Project settings → Sharing.
Row-level security: the Data Security tab of a table in the Data Model, and Global Data Security. A data model still saves, and every table you select is readable.

The one share that does work is the link on the agent’s Share this analysis card. It points at your own Upsolve Local, so it opens on this computer and nowhere else. Map charts are not in Upsolve Local either: Mapbox’s terms do not let Upsolve ship its access token in a download, so the app does not include the map library. A chart that asks for a map shows “Map charts are available in Upsolve Cloud” instead. Every other chart type works.

Day to day

Upsolve runs for as long as the terminal does. These work from any terminal:

npx @upsolve-labs/analytics status    # is it running, and does it answer?
npx @upsolve-labs/analytics stop      # let requests in flight finish (up to 60 s), then stop
npx @upsolve-labs/analytics logs      # the end of the app's log (add -f to follow it)
npx @upsolve-labs/analytics logs dashstra   # the agent's log
npx @upsolve-labs/analytics mcp --help      # the MCP server for Claude and Codex

Start it again with npx @upsolve-labs/analytics. Your data is in your PostgreSQL, so it is all there.

Where things live

Path	What
`~/.upsolve/config.json`	Your install’s secrets, ports and database URL. Back it up with your data.
`~/.upsolve/versions/<release>`	The release that runs. Each release has its own directory.
`~/.upsolve/logs/`	`api.log`, `dashstra.log` (the agent) and `supervisor.log`.
Your PostgreSQL, database `upsolve`	Everything else: workspaces, chat history, canvases, settings.

Set UPSOLVE_HOME to keep all of this somewhere other than ~/.upsolve.

Options of `start`

Option	What it does
`--database-url <url>`	Use this database. It is created if missing, and must be empty or already Upsolve’s. Remembered for next time.
`--port <n>`	Port of the app (default 4400, or the next free pair). Used exactly as given.
`--agent-port <n>`	Port of the agent (default 4401).
`--no-open`	Do not open the browser.
`--start-timeout <sec>`	How long to wait for the app and the agent to answer (default 300).

npx @upsolve-labs/analytics config shows your configuration with the secrets hidden, and config set <key> <value> changes port, agentPort, databaseUrl or telemetryEnabled for the next start.

Upgrading Upsolve Local

Each time you start Upsolve, it checks whether a newer release is available. If one is, it says so in your terminal, right after the line with the address of the app:

A newer version of Upsolve Local is available: 6.25.0 (this is 6.24.9).
To update, stop Upsolve and run:  npx @upsolve-labs/analytics@latest
What's new, and how updates and backups work: https://docs.upsolve.ai/local/quickstart#upgrading-upsolve-local

The check never updates anything by itself: it only tells you, and you decide when to update. It asks the public npm registry for the latest version number of Upsolve Local, the same request npx makes, and sends no usage data and nothing about your data. If the registry cannot be reached the check is silent and Upsolve starts as usual. To turn it off, start Upsolve with UPSOLVE_NO_UPDATE_CHECK=1 in the environment:

UPSOLVE_NO_UPDATE_CHECK=1 npx @upsolve-labs/analytics

To move to the newest release, stop Upsolve and run:

npx @upsolve-labs/analytics@latest

It downloads and verifies the new release, and then starts it against your existing data. Releases keep their own directory under ~/.upsolve/versions, so older ones stay on disk until you delete them. Upsolve applies the new release’s database changes when it starts. They only go forward, so before it changes a database that already has your data it takes a backup of it in ~/.upsolve/backups, and npx @upsolve-labs/analytics restore latest puts it back into a new database (Restoring a backup; it needs pg_dump; without it, or with --no-backup, Upsolve says so and takes none). A backup of your own is still worth having, so back up Upsolve’s database before you upgrade, and keep ~/.upsolve/config.json with the backup. The database is the one in databaseUrl, which npx @upsolve-labs/analytics config shows with the password hidden. It is upsolve on localhost:5432 unless you chose another server, role or name, so dump it with the same ones:

pg_dump --host <host> --port <port> --username <role> <database> > upsolve-backup.sql

Upgrade to cloud

Moving a local workspace into Upsolve Cloud is coming, and not available yet. When it ships it will be a copy: your local install keeps working and your data stays in your PostgreSQL until you choose to move it. Nothing you do today stands in its way. Keep ~/.upsolve/config.json and your database as they are.

Who can reach it, and what leaves your computer

Other people on your computer. Upsolve Local has no login. It answers only connections made from the computer itself, and only to the addresses 127.0.0.1 and localhost, which keeps other computers and other websites out. It cannot tell one user account from another, though, so anyone who can log in to the same computer and reach port 4400 can use the app and the connections inside it. On a shared Mac or a shared Linux server, run it only where you would be comfortable with that, or use a database role that can read only what you want shared. Your questions go to your AI provider. The chat sends your messages, and the schema, query results and other context the agent needs to answer, to the AI provider you chose. That is how it works, and it is separate from usage data: anonymous usage data is a short list of counts and never contains any of this. Use a provider and a key whose terms suit the data you ask about.

Next steps

Troubleshooting

Every message Upsolve Local prints, and what to do about it.

Anonymous usage data

Exactly what Upsolve Local sends, and how to turn it off.

Complete setup guide

Data models, system prompts, knowledge base and the rest of the agent builder.

Welcome to Upsolve AI

Get Started

Concepts

Encode Your Context

Deploy & Expose

Observability

Interact with Analytics Agents

Technical Reference

Run Upsolve locally

What you need

PostgreSQL

Windows (WSL 2)

Give Upsolve an AI provider

Install and start

Your first session

What is in Upsolve Local, and what is not

Day to day

Where things live

Options of `start`

Upgrading Upsolve Local

Upgrade to cloud

Who can reach it, and what leaves your computer

Next steps

Troubleshooting

Anonymous usage data

Complete setup guide

​What you need

​PostgreSQL

​Windows (WSL 2)

​Give Upsolve an AI provider

​Install and start

​Your first session

​What is in Upsolve Local, and what is not

​Day to day

​Where things live

​Options of start

​Upgrading Upsolve Local

​Upgrade to cloud

​Who can reach it, and what leaves your computer

​Next steps

Troubleshooting

Anonymous usage data

Complete setup guide

What you need

PostgreSQL

Windows (WSL 2)

Give Upsolve an AI provider

Install and start

Your first session

What is in Upsolve Local, and what is not

Day to day

Where things live

Options of `start`

Upgrading Upsolve Local

Upgrade to cloud

Who can reach it, and what leaves your computer

Next steps