> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upsolve.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Run Upsolve locally
> Install Upsolve Local on your Mac with one command and chat with your own PostgreSQL data, with no account to create.
Upsolve Local runs the Upsolve analytics agent on your Mac, 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 Mac, so other computers cannot reach it. See [Who can reach it, and what leaves your Mac](#who-can-reach-it-and-what-leaves-your-mac) before you point it at sensitive data.
```bash theme={null}
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** | Apple silicon or Intel, running macOS. Linux and Windows are not supported yet. |
| **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 your Mac, 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](https://console.anthropic.com), [OpenAI](https://platform.openai.com) or [OpenRouter](https://openrouter.ai), 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](#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:
```bash theme={null}
brew install postgresql@16
brew services start postgresql@16
```
Download [Postgres.app](https://postgresapp.com), open it and press **Initialize** or **Start**. It listens on `localhost:5432`, the same place Homebrew does.
Upsolve looks for a server on `localhost:5432` as your macOS user, and creates the `upsolve` database there. Both installs above give your macOS user a role that is allowed to create databases. If your server is somewhere else, or needs a password, point Upsolve at it:
```bash theme={null}
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.
## 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 Mac.** 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](/local/troubleshooting#the-agent-does-not-answer-or-says-no-ai-provider-is-configured).
## Install and start
Run one command:
```bash theme={null}
npx @upsolve-labs/analytics
```
The first time, this:
1. **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/`. Anything that does not match is thrown away and never run. Later runs of the same release start immediately, with no download.
2. **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.
3. **Finds your PostgreSQL**, creates the `upsolve` database if it is missing, and applies Upsolve's migrations.
4. **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).
5. **Opens your browser** at `http://127.0.0.1:4400`.
You see something like this, with your own numbers:
```text theme={null}
Downloading Upsolve Local ( MB)...
Checksum verified. Unpacking...
Created /Users//.upsolve/config.json with new secrets (readable only by you). ...
PostgreSQL 16 at @localhost:5432/upsolve (database created)
Applying database migrations...
Migrations: 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](/local/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 `; run them as `npx @upsolve-labs/analytics `.
## 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".
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 off. Turning it on is your choice and is saved when you press **Continue**; you can change it later in **Organization settings → Usage stats**. See [anonymous usage data](/local/telemetry) 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.
The next screen, "Connect your database", opens on PostgreSQL with `localhost` and port `5432` filled in: on a Mac that is your own PostgreSQL server. 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](/local/troubleshooting#the-database-refuses-the-connection).
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. 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.
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](/ai-agent-builder/setup-guide) walks through all of it.
### 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 Mac 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:
```bash theme={null}
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
```
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/` | 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 ` | Use this database. It is created if missing, and must be empty or already Upsolve's. Remembered for next time. |
| `--port ` | Port of the app (default 4400, or the next free pair). Used exactly as given. |
| `--agent-port ` | Port of the agent (default 4401). |
| `--no-open` | Do not open the browser. |
| `--start-timeout ` | 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 ` 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:
```text theme={null}
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:
```bash theme={null}
UPSOLVE_NO_UPDATE_CHECK=1 npx @upsolve-labs/analytics
```
To move to the newest release, stop Upsolve and run:
```bash theme={null}
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](/local/troubleshooting#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:
```bash theme={null}
pg_dump --host --port --username > 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 Mac
**Other people on your Mac.** Upsolve Local has no login. It answers only connections made from the Mac itself, and only to the addresses `127.0.0.1` and `localhost`, which keeps other computers and other websites out. It cannot tell one macOS user from another, though, so **anyone who can log in to the same Mac and reach port 4400 can use the app and the connections inside it**. On a shared Mac, 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](/local/telemetry) 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
Every message Upsolve Local prints, and what to do about it.
Exactly what Upsolve Local sends, and how to turn it off.
Data models, system prompts, knowledge base and the rest of the agent builder.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.