Proxyma Desktop on Linux

Everything that is different about running Proxyma Desktop on Linux. The application is the same one - this page covers only where Linux differs.

Read the desktop manual for everything else

Choosing an AI provider, adding documents, asking questions, licensing and troubleshooting are identical on both platforms and are covered in the Proxyma Desktop manual. Only installation, file locations and updating differ, and those are here. Nothing on this page repeats what is there.

Installing

Proxyma ships as an AppImage: one file that contains the whole application, including its own Java runtime. There is nothing to install, no package manager involved, and no root access needed.

Download proxyma-x64-v<version>.AppImage from the releases page.
Make it executable: chmod +x proxyma-x64-v<version>.AppImage
Run it. Proxyma opens in your default browser.

Put it wherever you keep such things - ~/Applications and ~/bin are both fine. The file does not need to stay in one place, and moving it later breaks nothing.

If double-clicking does nothing

Almost always the executable bit. Some browsers and file managers strip it on download. Check with ls -l - you are looking for x in the permissions - and run the chmod above. Failing that, run it from a terminal, where any real error is printed rather than swallowed.

The first run takes a few minutes

Proxyma sets up a bundled Python environment on first launch, which is what the vector database and document conversion run on. A progress window shows what it is doing. It happens once; later starts go straight to the application.

Nothing is downloaded during this - the packages ship inside the AppImage - so it works offline.

What it needs

Component	Requirement
Operating system	Any 64-bit glibc distribution - Ubuntu, Debian, Fedora, Arch and their derivatives all work. Not musl-based distributions such as Alpine.
Desktop session	X11 or Wayland. Proxyma opens a browser window and is not a headless service - that is what Proxyma Server is for.
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	Only for licence activation, updates, and a hosted AI provider if you choose one

Quitting

Use the power icon in the top-right of the Proxyma window. It stops the application and every background process it started.

Why there may be no tray icon

Proxyma installs a system tray icon where the desktop environment supports one. GNOME does not show tray icons without an extension, and neither does a plain Wayland session, so on many Linux desktops there will not be one. The power icon in the application always works and does the same thing.

Updates

Proxyma tells you when a new version is available, but does not update itself on Linux. Download the new AppImage, make it executable, and run it - your index, conversations and settings are untouched, because they live outside the AppImage (see below).

You can delete the old file once the new one starts.

Why not in place

An AppImage is a single read-only file rather than a folder of files to replace, so "download the new one" is the update mechanism rather than a workaround for a missing one. The Windows build updates in place because it is installed as a directory.

Where your data lives

What	Where
Index, conversations, settings	`~/.local/share/proxyma/` (or `$XDG_DATA_HOME/proxyma/` if you set it)
Bundled Python runtime	`~/.local/share/proxyma/runtime/` - set up on first run
Logs	`~/.local/share/proxyma/logs/`
Credentials	The kernel keyring, via `keyctl`. Where that is unavailable, an encrypted file inside the data directory.
Your documents	Wherever 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 you a reindex, not your documents.

To remove Proxyma completely: delete the AppImage and that directory. Nothing is written anywhere else.

Scanned documents and OCR

Reading text out of scanned PDFs needs the Tesseract engine, which is a system package rather than something Proxyma can bundle. Install it if you have scanned documents to index:

Distribution	Command
Debian, Ubuntu	`sudo apt install tesseract-ocr`
Fedora	`sudo dnf install tesseract`
Arch	`sudo pacman -S tesseract tesseract-data-eng`

Everything else - PDFs with a text layer, Office documents, Markdown, plain text, HTML - works without it. This is the same on Windows, where Tesseract is also a separate install.

Adding Proxyma to your applications menu

Optional. The AppImage runs perfectly well without it.

Install AppImageLauncher and it will offer to integrate the AppImage the first time you run it, which puts Proxyma in your launcher and handles moving the file for you.

Troubleshooting

The desktop manual's troubleshooting section covers the problems that are not platform-specific - no AI provider, slow indexing, search missing something, licence keys. Below are the ones particular to Linux.

It exits immediately, or nothing happens at all

Run it from a terminal. An AppImage launched from a file manager has nowhere to print an error to, so a fatal problem looks like nothing happening.

The most common cause is the missing executable bit, covered above. The next most common is a FUSE issue on older distributions - if the error mentions fuse or libfuse.so.2, either install FUSE 2 (sudo apt install libfuse2 on Debian and Ubuntu) or run the AppImage with --appimage-extract-and-run, which unpacks it instead of mounting it.

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

Proxyma runs a bundled vector database alongside itself on a local port. Check ~/.local/share/proxyma/logs/ - chromadb.log holds its own output. A leftover process from a previous run is the usual cause; Proxyma tries to clear those on start, but a forcibly killed session can leave one behind.

The first-run setup fails

It writes to ~/.local/share/proxyma/runtime/, so it needs that path to be writable and needs enough free space - the runtime and its packages are around 1.5 GB. If it failed part way through, delete that directory and start Proxyma again; it will set it up from scratch.

No window appears, but Proxyma seems to be running

Proxyma's interface is a browser page, and it opens your default browser to reach it. If no default is configured, nothing opens. Go to http://localhost:4246 yourself.