Proxyma Desktop on Linux

What is different about running Proxyma Desktop on Linux.

Read the desktop manual for everything else

AI providers, adding documents, asking questions, licensing and general troubleshooting are covered in the Proxyma Desktop manual.

Installing

Proxyma for Linux is a small .deb package for Ubuntu and Debian. It holds the launcher, its Java runtime and the application window. Proxyma downloads the rest the first time it starts.

From the Proxyma repository (recommended)

apt checks every download from the repository against the Proxyma signing key.

sudo install -d -m 0755 /etc/apt/keyrings
sudo wget -qO /etc/apt/keyrings/proxyma.asc https://proxyma.ai/keys/proxyma-release.asc
echo "deb [signed-by=/etc/apt/keyrings/proxyma.asc] https://github.com/proxyma-ai/proxyma-releases/releases/download/apt/ ./" | sudo tee /etc/apt/sources.list.d/proxyma.list
sudo apt update && sudo apt install proxyma

The key's fingerprint is BE3A B092 AB25 4FA4 5C57 8AF4 F571 F889 94F6 B817. Proxyma still updates itself; sudo apt upgrade keeps the package current too.

From a downloaded file

sudo apt install ./proxyma_<version>_amd64.deb

Keep the ./, or apt searches your repositories instead of installing the file. Proxyma appears in your applications menu; sudo apt remove proxyma removes it.

The first start downloads the rest of Proxyma

Connect to the internet. The first start needs it; later starts do not.
Start Proxyma. It downloads the rest of the application, several hundred megabytes, and shows the progress.
It then sets up its Python environment, which takes about a minute.

If the download stops, start Proxyma again. It continues where it stopped. Every file is checked against the release's signed checksums before it is installed.

Behind a company proxy, Proxyma uses your system proxy settings or HTTPS_PROXY, and the certificate authorities your system trusts.

What it needs

Component	Requirement
Operating system	Ubuntu or Debian, 64-bit (x86-64)
Desktop session	X11 or Wayland. Not a headless service - use Proxyma Home Server for that.
Memory	8 GB, 16 GB if you run a local AI model on the same machine
Disk	3 GB for the application and its runtime, plus room for your index
Internet	For the first start, license activation and re-checks, updates, sources on other servers, and a hosted AI provider if you choose one

Starting Proxyma

Start it from your applications menu. Proxyma opens in its own application window. Starting it again while it runs brings that window back.

Started from a terminal? Closing it stops Proxyma

Running proxyma in a terminal shows the startup messages, which helps diagnose a failure to start. Closing that terminal or pressing Ctrl+C stops Proxyma.

The terminal output is normal startup logging, not errors. It is also written to ~/.local/share/proxyma/logs/proxyma.log.

Quitting

Open the menu at the top right of the Proxyma window and choose Quit Proxyma, then Quit. It stops the application and its background processes, however you started it.

Closing the window does not stop Proxyma. Start it from the menu again, or go to http://localhost:4246, to open it.

Why there may be no tray icon

Proxyma shows a tray icon where the desktop supports one. GNOME without an extension and plain Wayland sessions do not. Quit Proxyma in the app's menu always works.

Updates

Proxyma checks for and installs new versions. Go to Settings → Updates to see your version, check now, or turn automatic checking off. Updates do not touch your index, conversations or settings.

When a new version is found, Proxyma downloads only the parts that changed. Anything that does not match the release's signed checksums is refused.
Choose Restart and install when it suits you. No password is needed.

If the new version fails to start, Proxyma goes back to the previous version by itself.

Where your data lives

What	Where
Index, conversations, settings	`~/.local/share/proxyma/` (or `$XDG_DATA_HOME/proxyma/` if you set it)
Downloaded application parts	`~/.local/share/proxyma/parts/` - downloaded on first run and by updates
Python runtime	`~/.local/share/proxyma/runtime/` - set up on first run
Logs	`~/.local/share/proxyma/logs/`
Skills and conversation files	`~/.proxyma/`
Credentials	Encrypted in the data directory, with the key in a file there - see below.
Your documents	Where they already are - Proxyma does not copy or move them

Back up ~/.local/share/proxyma/ to keep your index and chat history. Losing it costs a reindex, and saved credentials and your activated license become unreadable. Your documents are not lost.

To remove Proxyma completely:

Run sudo apt remove proxyma. This removes the package, but not what Proxyma downloaded into ~/.local/share/proxyma/.
Delete ~/.local/share/proxyma/ and ~/.proxyma/. This also deletes your index, conversations and settings.

To free the space but keep your data, delete only parts/ and runtime/ in ~/.local/share/proxyma/.

Where connector credentials are kept

Connector passwords and tokens are encrypted with a key kept in .secret in the data directory, readable only by your account (0600).

Scanned documents and OCR

Scanned PDFs need OCR. Choose an OCR model in Settings → Conversion, or select the Tesseract engine there. The package installs Tesseract with English and Vietnamese for you; if your system skips recommended packages, run sudo apt install tesseract-ocr tesseract-ocr-eng tesseract-ocr-vie. PDFs with a text layer, Office documents, Markdown, plain text and HTML work without it.

Troubleshooting

For problems that are not Linux-specific, see the desktop manual's troubleshooting section.

It exits immediately, or nothing happens at all

Run proxyma in a terminal to see the error.

It will not start, and the log mentions the vector database

Check chromadb.log in ~/.local/share/proxyma/logs/. The usual cause is a leftover process from a previous run, typically after a forcibly killed session.

The first-run setup fails

Check that the machine can reach GitHub. If the download stopped, start Proxyma again.

~/.local/share/proxyma/ must be writable, with about 3 GB free. If the Python setup failed part way, delete runtime/ there and start Proxyma again.

No window appears, but Proxyma seems to be running

Start Proxyma from the menu again, which opens its window. If that does not work either, go to http://localhost:4246 in a browser.