Installation

File Palaces has two parts that must both be running: the Python sidecar (FastAPI server that handles all AI and file processing) and the Tauri desktop app (the UI shell). During development you run them separately; in a production release they are bundled together.

System requirements

Requirement	Minimum
OS	Windows 10/11, macOS 12+, Linux (glibc 2.31+)
RAM	4 GB (8 GB recommended for large document sets)
Disk	1 GB for the app + ~300 MB for the embedding model
Node.js	18+ (for frontend dev)
Python	3.11+
Rust	1.77+ (for Tauri dev only)
uv	Latest (recommended Python package manager)

NOTE

uv is not strictly required — pip install works too — but it is significantly faster and handles virtual environments automatically.

Step 1 — Clone the repository

git clone https://github.com/ellemayo/filepalaces.git
cd filepalaces

Step 2 — Install the Python sidecar

cd sidecar
uv sync          # creates .venv and installs all Python deps

If you prefer pip:

cd sidecar
python -m venv .venv
source .venv/bin/activate    # Windows: .venv\Scripts\activate
pip install -e .

Step 3 — Install the frontend dependencies

cd filepalace
npm install

Step 4 — Install Rust (for Tauri dev)

If you don't have Rust installed:

# Windows (PowerShell)
winget install Rustlang.Rustup

# macOS / Linux
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Then install the Tauri CLI prerequisites for your platform. See the Tauri v2 prerequisites guide.

Running in development mode

You need two terminals open simultaneously.

Terminal 1 — start the sidecar on the fixed dev port:

cd sidecar
uv run python main.py 52731

The sidecar prints PORT=52731 to stdout when it is ready. Leave this running.

Terminal 2 — start the Tauri dev server:

cd filepalace
npm run tauri dev

The app window opens automatically. Hot-reload is active for both the React frontend and the Rust shell.

TIP

VS Code users: open the workspace and run the File Palaces: Dev task (Ctrl+Shift+B). It starts both the sidecar and Tauri dev in sequence automatically.

Troubleshooting

Sidecar not connecting

Check that the sidecar printed PORT=52731 and is still running. The app shows a "Connecting to sidecar…" spinner until it gets a successful /status response.

Port 52731 already in use

Kill the existing process, or change the port in filepalace/src-tauri/src/sidecar.rs (dev port constant) and pass the new port to main.py.

Missing Rust toolchain

Run rustup update stable and ensure ~/.cargo/bin is on your PATH.

Python uv sync fails

Make sure you have Python 3.11+ available. Run python --version to check. On Windows, install Python from python.org and reopen the terminal.