Skip to main content
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 before you point it at sensitive data.
Upsolve Local is early. Some screens are still being built, and this page says plainly where that affects you.

​
What you need

​
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:
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:
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. 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.

​
Install and start

Run one command:
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/<release>. 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:
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”.
1

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 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.
2

Connect your database

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.
3

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. 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.
4

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.

​
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:
Start it again with npx @upsolve-labs/analytics. Your data is in your PostgreSQL, so it is all there.

​
Where things live

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

​
Options of start

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:
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:
To move to the newest release, stop Upsolve and run:
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:

​
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 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.