Run Fluide on your computer.

Requirements

• Docker Engine 28.3.3 or newer, with Docker Compose v2 (docker compose).
• A Plaid account and its API keys. Each install brings its own keys. Fluide uses Plaid's production environment, with real banks, by default, which needs Plaid to approve your Plaid account. To try it with Plaid's test banks, set PLAID_ENV=sandbox in .env and use your sandbox keys.

Fluide links US banks only. It never moves money: the only Plaid product it asks for is Transactions.

Install

$ mkdir fluide && cd fluide
$ curl -fsSLO https://github.com/Neautrino/fluide/releases/latest/download/docker-compose.yml
$ docker compose up -d

That one file is the whole install: it downloads Fluide and its database, and keeps your data in Docker volumes. To use Plaid's test banks, run echo PLAID_ENV=sandbox > .env before docker compose up -d.

To build from source instead: git clone https://github.com/Neautrino/fluide.git, cd fluide, then docker compose up -d --build.

Open http://localhost:8080, then:

1. Go to Settings → Provider keys and enter your Plaid client id and secret.
2. Click Connect US bank and link an account through Plaid. You sign in to your bank in Plaid's own window.
3. Optional: in Settings → Assistant, pick a categorization model (TypeSafe, OpenCode Zen, OpenRouter or your own compatible host) and a chat model (OpenAI, Claude, Gemini, OpenCode Zen, OpenRouter or any OpenAI-compatible server, such as a local Ollama), and test each connection.

PLAID_ENV in .env picks the Plaid environment, production (the default) or sandbox, and must match the keys you enter.

What happens on first start

1. The database passwords and a 32-byte encryption key are generated, each in its own storage volume. Existing ones are never overwritten.
2. The database is created.
3. The database is brought up to date, and the app's own database user is created without admin rights. This runs on every start and does nothing when everything is already current.
4. The app starts and serves Fluide on http://localhost:8080.

You don't create any of these passwords or keys yourself.

Update

$ curl -fsSLO https://github.com/Neautrino/fluide/releases/latest/download/docker-compose.yml
$ docker compose pull && docker compose up -d

Run it in the folder that holds docker-compose.yml. Each release's file names that release's version, so the two always match. The database is brought up to date for the new version before the app starts.

When a newer release is out, Settings → General shows "Update available" with a link to the release notes and this command to copy. Fluide never updates itself.

Stop

$ docker compose down

Your data stays in Docker's volumes and is there again on the next docker compose up -d.

Security model

• The app answers on 127.0.0.1:8080 only, so it's reachable from the computer it runs on, not from your network.
• The database isn't published at all; it sits on a private network inside the install. The app connects to it as a user without admin, create-database or create-user rights. Only the step that brings the database up to date uses the admin account.
• Bank access tokens and provider keys (your Plaid client id and secret) are encrypted at rest with AES-256-GCM. The encryption key lives in its own volume, apart from the database.
• The server refuses requests addressed to any other host name (protection against DNS rebinding) and refuses cross-site write requests.
• The app runs as a regular user, with a read-only filesystem and no special system permissions.
• There is no login yet. Anyone and any program that can reach localhost:8080 on that computer can use Fluide. Don't expose or forward the port.
• Access from your network or from elsewhere isn't supported yet. FLUIDE_ALLOWED_HOSTS (extra host names to accept) is only for advanced setups behind your own reverse proxy that does the sign-in.

What leaves your computer

Backups

A usable backup needs both the database and the encryption key. The database holds bank connections and provider keys only in encrypted form; without the matching key they can't be read, and you would have to enter your Plaid keys again and re-link every bank. Keep the two files apart.

Back up while the database is running (docker compose up -d, or docker compose up -d --wait db):

$ docker compose exec -T db pg_dump -U postgres fluide > fluide.sql
$ docker compose run --rm --no-deps -T --entrypoint cat secrets-init /secrets/vault/key > vault.key

The first command saves the database to fluide.sql; the second saves the encryption key to vault.key.

Restore

On a fresh copy, before a full docker compose up -d:

$ docker compose up -d --wait db
$ docker compose run --rm --no-deps -T --entrypoint sh secrets-init -c 'cat > /secrets/vault/key' < vault.key
$ docker compose exec -T db psql -U postgres -d fluide < fluide.sql
$ docker compose up -d

1. Start only the database. This first creates new passwords, a new encryption key and an empty database.
2. Replace the new encryption key with your backed-up one.
3. Load your backup into the empty database. Errors saying the app's database user doesn't exist are expected; the next step creates it.
4. Start everything. The database is found up to date, and the app's user is created with its new password and permissions.

If this install has already been started, its database isn't empty any more: run docker compose down -v first, which deletes its current data and encryption key.