How to Install Aurelio Finance on macOS and Linux

How to Install Aurelio Finance on macOS and Linux

Aurelio Finance has no app store listing and no packaged installer. It is an open-source project that runs from its source code, which means installing it on macOS or Linux takes a terminal, three free prerequisites, and one start script. If you have used a terminal before, this will feel easy. If you have not, this guide assumes nothing and explains every command before you run it. By the end, you will have the app open in your browser at http://localhost:8000, running in demo mode with sample data.

What you are about to do, in one paragraph

You will install Git (to download the code), Node.js 22 or newer (to run the frontend), and uv (to manage the Python backend). Then you will clone the Aurelio Finance repository from GitHub, move into the folder, and run ./start.sh --demo. The script sets up everything else and serves the app locally. Your data lives in backend/data.db inside the project folder. Nothing you enter ever leaves your machine.

Step 1: Install Git

Git is probably already on your machine. Open a terminal and check:

git --version

  • On macOS: if Git is missing, running that command triggers a prompt to install Apple’s Command Line Tools. Accept it and wait for it to finish. Homebrew users can also run brew install git.
  • On Debian or Ubuntu: install it with sudo apt update && sudo apt install git.
  • On Fedora: use sudo dnf install git.

Run the version check again afterward. If a version number prints, you are set.

Step 2: Install Node.js 22 or newer

Aurelio Finance requires Node.js version 22 or newer. Check what you have with node --version. If it prints v22 or higher, skip this step. Otherwise:

  • On macOS with Homebrew: brew install node@22 followed by brew link --overwrite node@22 if Homebrew asks.
  • On Linux: the package in your distribution’s default repositories may be older than 22, so the reliable route is the official NodeSource setup or a version manager like nvm. With nvm, run nvm install 22 and then nvm use 22.
  • On either system: you can also download the current LTS installer from nodejs.org and follow its prompts.

Verify with node --version before moving on. A wrong Node version is the single most common cause of failed first runs, so this ten-second check saves real frustration.

Step 3: Install uv

uv is a fast Python package manager from the Astral team, and the Aurelio Finance backend uses it to build its environment and install dependencies. The official install script works on both macOS and Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

When it finishes, close and reopen your terminal, or run the command the installer prints to update your shell’s PATH. Then confirm with uv --version. If the version prints, all three prerequisites are done.

Step 4: Clone the repository

Now get the app itself. In your terminal:

  1. Move to a folder where projects can live, for example cd ~ for your home directory.
  2. Clone the repository: git clone https://github.com/LosaLosSantos/aurelio-finance.git
  3. Move into the new folder: cd aurelio-finance

The clone pulls the complete project from github.com/LosaLosSantos/aurelio-finance, the public home of the project under its MIT license. Using Git instead of a zip has a lasting benefit: when the project updates, git pull brings you the latest code in seconds.

Step 5: Run the start script in demo mode

From inside the aurelio-finance folder, make the script executable (you only need to do this once) and run it with the demo flag:

chmod +x start.sh

./start.sh --demo

The first run takes a few minutes. The script builds the backend environment with uv, installs frontend dependencies with Node, and starts the app. Subsequent runs skip most of that work and start in seconds.

When it is ready, open http://localhost:8000 in your browser. You will see Aurelio Finance loaded with invented demo data: a sample net worth, sample investments, sample cash flow. Explore every section. Look at the portfolio look-through views, which break holdings down by country, sector, company, and currency. Check the savings goals page. None of it is real, so you cannot mess anything up.

To stop the app, return to the terminal and press Ctrl+C. The server shuts down and your terminal prompt comes back.

Demo mode vs. real mode

Demo mode exists so you can learn the app without risk, and it is worth spending real time there. Twenty or thirty minutes of clicking around with fake numbers teaches you the layout far better than reading documentation.

When you are ready for your own finances, run the exact same script without the flag:

./start.sh

The app starts empty, and everything you enter is saved to backend/data.db in the project folder. Two things follow from that. First, the app automatically saves a backup copy next to that file before any update that changes the data format, which protects you during upgrades. Second, the file is entirely your responsibility: there is no cloud copy anywhere, so add it to whatever backup routine you already trust. An external drive, a synced folder, or a periodic manual copy all work.

The optional AI advisor

Once the app is running, you can optionally connect an AI advisor through OpenRouter with your own API key. It is off unless you set it up, and you can ignore it completely if you prefer. One design detail matters if you do try it: the advisor never writes to your records directly. Every suggestion appears as a confirmation card that you approve or reject, so your data only changes when you say so.

Troubleshooting the first run

Most first-run failures on macOS and Linux come from three causes. Check them in this order:

  • Wrong Node version. Run node --version. Anything below 22 will fail in confusing ways. Install version 22 or newer and try again. If you use nvm, remember to run nvm use 22 in the same terminal window before starting the app.
  • uv not found. The installer adds uv to a directory your shell may not know about yet. Close and reopen the terminal, then re-run uv --version.
  • Permission denied on start.sh. The script is not marked executable. Run chmod +x start.sh once and try again.
  • Port 8000 already in use. Something else on your machine, often an earlier Aurelio Finance run in another terminal tab, already holds the port. Find that terminal, press Ctrl+C there, and relaunch.

If the script still fails, read the last few lines of its output carefully. Open-source start scripts print the real error near the end, and pasting that exact message into a search almost always finds someone who hit the same problem.

Keeping the app updated

Because the project is young and active, updates arrive often. To update, stop the app, run git pull inside the project folder, and start the script again. Your data.db file is untouched by the pull, and the built-in backup copy covers the rare updates that change the data format. That is the full maintenance routine: pull, restart, done.

Step back for a second and appreciate the setup you now have. No account, no subscription, no company server holding your financial life hostage. Your money data sits in one file, in one folder, on your machine, and the tool that reads it is open source under the MIT license. That is a genuinely different deal from mainstream finance apps, and it is worth the fifteen minutes this install took.

Read next

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top