Install on macOS¶

Upsight publishes a macOS .dmg on every GitHub release. This is the path for anyone who is not building the app from source with Nix. See Install on NixOS if you are on NixOS instead.

Download and install¶

Download Upsight.dmg from the latest release.
Open it and drag Upsight into Applications.
Launch it from Launchpad or Spotlight.

Getting past Gatekeeper¶

The build is unsigned. There is no Apple Developer ID certificate behind it, so macOS Gatekeeper blocks a plain double-click on first launch with an "Upsight can't be opened because Apple cannot check it for malicious software" (or "is damaged and can't be opened") message. Two ways past it, once:

Right-click (or Control-click) Upsight.app in Applications and choose Open. Confirm in the dialog that appears. This is the standard macOS path for unsigned software and only needs doing once per machine.
Or, from a terminal:
```
xattr -cr /Applications/Upsight.app
```
This clears the quarantine attribute Gatekeeper checks. Use it if the right-click path does not offer an Open option.

Using the CLI¶

The .dmg installs only the GUI app, so upsight isn't on your PATH yet — the GUI and the CLI are the same binary, just invoked differently. To run upsight doctor, upsight summarize, or any other CLI command from a terminal, symlink it once:

mkdir -p ~/.local/bin
ln -sf /Applications/Upsight.app/Contents/MacOS/upsight ~/.local/bin/upsight

Make sure ~/.local/bin is on your PATH (add export PATH="$HOME/.local/bin:$PATH" to your shell's rc file if it isn't already). Re-run the ln -sf command after installing a newer release so the symlink keeps pointing at real code.

Runtime dependencies¶

The app itself needs nothing beyond the .dmg. A handful of features shell out to external CLIs and need those on PATH separately. Install only what you use, the app runs fine without the rest, and a feature missing its CLI just no-ops (upsight doctor, see below, tells you exactly what is missing).

Feature	Dependency	Install
Win-wire PDF text extraction	`pdftotext` (poppler)	`brew install poppler`
AI features (meeting summaries, CX indicators, agenda enhancement, "Investigate" on a failed write-back)	the `claude` CLI	`curl -fsSL https://claude.ai/install.sh \\| bash`, then `claude login`
Salesforce integration (account/case sync, optional write-back)	the `sf` CLI	`npm install -g @salesforce/cli`, then `sf org login web`
Tableau dashboards surfaced to AI generation (optional, only if configured in Settings)	`npx` running `@tableau/mcp-server`	`brew install node` (gives you `npx`), then `npm install -g @tableau/mcp-server@2.21.1` to seed the cache

A few notes on those:

Clipboard copy and desktop notifications need nothing. macOS's built-in pbcopy/pbpaste and osascript are used automatically.
The Salesforce CLI is deliberately installed via npm, not Homebrew. Homebrew's salesforce-cli cask is deprecated upstream and fails the Gatekeeper check; npm is Salesforce's own documented install path (and the one sf update expects). If you don't already have Node, get it first: brew install node.
The AI binary is configurable. claude is the default, but any CLI that reads a prompt on stdin and writes to stdout works. See Settings and the [ai] section of config.toml (binary / args) to point at a different one (for example the Gemini CLI).
Tableau MCP is seeded, not just installed. The app invokes it as npx -y --prefer-offline @tableau/mcp-server@2.21.1 at AI-generation time. --prefer-offline means it resolves from npm's local cache rather than hitting the network on every AI call, so the one-time global install above is what makes that fast and avoids a network round-trip, rather than strictly required. npx would still fetch it fresh each time without it.
After installing what you need, run upsight doctor from a terminal (or the Doctor panel in Settings) to confirm everything the app can see is wired up correctly, including an optional --ai check that runs one real generation through your configured AI binary.

What the app expects at runtime¶

Database and config locations¶

Upsight stores its data in a single SQLite file. The database path is the same on every platform:

~/.local/share/upsight/upsight.db

config.toml, however, follows the macOS convention rather than Linux's:

~/Library/Application Support/upsight/config.toml

Set the UPSIGHT_DB environment variable before launching to point the app at a different database file, useful if you keep it on a synced volume:

export UPSIGHT_DB="$HOME/sync/upsight/upsight.db"

Upsight is a local, single-user app. To use it on more than one machine, keep the database file in a directory that Syncthing replicates (brew install syncthing if you want it, or grab the cask). The app opens the database in WAL mode with a single writer, so only run one instance at a time against a given file; Syncthing also replicates the -wal and -shm sidecar files, so let a sync settle before opening the app on another machine. See Multi-machine sync.

Credential storage¶

Integration credentials (Salesforce, Aha, Clari, Todoist, and similar) are stored in the macOS Keychain, not in config.toml. The first time you save one in Settings, macOS may prompt you to allow Upsight to access the keychain. Approve it, or the app can't read the credential back on the next launch.

Salesforce write-back¶

Editing posture and other fields always saves locally and queues the change. Pushing those changes back to Salesforce is off by default, because it writes to your live org. Turn it on in Settings under Integrations, Salesforce, "Push field edits back to Salesforce", then relaunch the app. With it off, your edits are kept and queued but nothing is sent to Salesforce.