Most personal finance tools start with the same seductive promise: connect your bank, watch the magic happen, stop thinking about money. Firefly III refuses that premise entirely. It is a self-hosted, AGPL-3.0 personal finance manager that assumes you would rather type a transaction than grant a third party read access to your checking account. That single design stance — money data is yours, it lives on hardware you control, and the application has no reason to phone home — is the entire reason this 24,000-star PHP project exists.
This is not a budgeting app in the YNAB sense and it is not a dashboard that ingests your statements and judges you. It is an accounting system. The word "accounting" scares people off, and Firefly III leans into it on purpose: it uses double-entry bookkeeping, the same method businesses have used for centuries, because single-entry "I spent $40 at the grocery store" tracking is exactly what leaves people confused about where their money actually went. If you have ever stared at a spreadsheet wondering why your categories do not add up to your bank balance, the answer is usually that single-entry tracking cannot tell you. Double-entry can.
The trade you make for that rigor is real. There is no official mobile app. There is no "connect to 10,000 banks" integration. You import with a separate Data Importer tool, or you type things in, or you script against a thorough REST API. Firefly III is a system for people who want the truth about their finances more than they want convenience. For a sovereign operator — someone who already runs a homelab, self-hosts their email, or simply refuses to hand spending data to an ad-supported aggregator — that trade is the whole point.
This review does not walk you through the install wizard. It explains what Firefly III actually is architecturally, what double-entry changes about your relationship with your money, what it costs to run honestly, where the limitations bite, and the privacy story that most "open source finance app" write-ups flatten into a single sentence. By the end you should know whether this is the tool that finally gets your finances off someone else's server — or whether the friction is more than your use case wants.
1. What Double-Entry Bookkeeping Actually Buys You
Firefly III is built on double-entry bookkeeping, and understanding that model is the difference between loving the tool and abandoning it after a week. In single-entry tracking, you record "I spent $40 at the grocery store" as one line. In double-entry, every transaction moves value between two accounts: your "Groceries" asset (or an expense account) decreases by $40 and your "Checking" asset decreases by $40. Every entry has two sides, and the system enforces that they balance.
This sounds like pointless ceremony until you have used it for three months. The first thing it exposes is money that simply vanishes in single-entry systems. If you transfer $200 from Checking to Savings and only record it once as "spending," your categories and your balance disagree forever. In Firefly III a transfer is explicitly a movement between two of your own accounts — it never touches an expense category, so your net worth math stays honest. The application will not let you post an unbalanced transaction. That constraint is the feature.
The second thing double-entry reveals is the difference between an asset, a liability, and an income or expense. Firefly III models all of these. A credit card is a liability account; paying it down moves money from an asset (checking) to reduce that liability. A paycheck is income landing in an asset. A subscription is an expense leaving an asset. When everything is modeled this way, your "net worth" is a real number you can compute: sum of assets minus sum of liabilities. Most single-entry budgeting apps cannot show you net worth without you maintaining a separate net-worth tracker, because they were never designed to represent liabilities as first-class objects.
The third, subtler benefit is auditability. Because every transaction has a source and a destination, and because Firefly III keeps full history, you can reconstruct why your cash position moved at any point. Combined with its rule engine (covered later), this turns "I have no idea what happened to my money in March" into a queryable, reproducible record. For anyone who has ever needed to produce a spending report for taxes, a reimbursement, or just their own peace of mind, that audit trail is worth more than any pretty chart.
2. The Data Model: Accounts, Transactions, and the Things Around Them
Under the hood, Firefly III organizes your financial life into a small set of primitives that map cleanly onto accounting reality. The central object is the account. Firefly III distinguishes asset accounts (checking, savings, cash), liability accounts (credit cards, loans, mortgages), and what it calls "external" accounts — ghost representations of places money comes from or goes to that you do not actually track (a employer, a utility company). You do not need to reconcile the external side; it exists so a transaction has somewhere to point.
Transactions are the movements. Each one connects a source account to a destination account, carries an amount, a date, a description, and optionally a currency, a category, tags, and attachments (a receipt photo, a PDF). A transfer is just a transaction where both ends are your own asset or liability accounts. A deposit is a transaction from an external income source into an asset. A payment is a transaction from an asset to an external expense. The uniformity is deliberate: there is one transaction type, and the account roles define the meaning.
Around transactions sit the organizing objects. Categories group spending ("Groceries," "Utilities"). Tags are free-form labels you can layer on top, useful for cross-cutting concerns like "tax-deductible" or "trip-2026." Budgets let you set expected spending per category per period — monthly, or a custom range — and Firefly III will show you spent-versus-budgeted in real time. Recurring transactions model subscriptions and salaries so the system can auto-generate or at least pre-fill them. Bills track obligations with due dates and warn you when one is approaching or overdue.
Currencies are first-class. Firefly III supports multiple currencies per installation, with exchange-rate awareness, so if you hold accounts in euros and dollars it will convert for net-worth display. The exchange-rate data comes from an optional, configurable provider (the project runs a public rates service, but you can point it elsewhere or disable auto-updates). This multi-currency support is genuinely rare in self-hosted personal finance tools and is one of the reasons expats and digital nomads gravitate to it.
3. Installation: The Docker Stack You Will Actually Run
Firefly III is a Laravel PHP application backed by a database (MySQL/MariaDB or PostgreSQL) and a cache. The supported, sane deployment is the official Docker image plus a database container, optionally with the separate Data Importer container. The project maintains a
firefly-iii/base-image and publishes tagged releases, and there is a community Kubernetes chart if you run k8s. For the vast majority of homelab operators, Docker Compose is the path.
A minimal realistic stack is three containers: the Firefly III app, a MariaDB (or Postgres) database, and a Redis for session/cache if you want snappier behavior (not strictly required but recommended at scale). You set a handful of environment variables: the database connection, an
APP_KEY (a 32-byte base64 string you generate once and never lose), the site URL, and a few behavior toggles. The APP_KEY deserves a paragraph on its own: it encrypts sensitive fields at rest in the database. If you lose it, your encrypted data is unrecoverable. If someone steals your database but not the key, the sensitive values are ciphertext. Generate it, back it up with the database, and store it somewhere other than the same volume.
The first boot runs database migrations automatically. You then create your user through the web UI or a console command, and you are in. The app itself is light — a small VPS with 1 GB RAM and one shared vCPU runs it comfortably for a single household. The database is the heavier neighbor, but for personal finance volumes it is tiny; a few hundred megabytes covers years of transactions. This is not a memory-hungry Java monolith like some wiki platforms; it is a focused PHP app, and resource expectations should be set accordingly.
4. What It Honestly Costs to Run
Here is the part the "free and open source" label obscures if you are not careful. Firefly III the software costs $0 and is AGPL-3.0, so you can run it forever with no license fee and no per-seat pricing. The real cost is infrastructure and your time, and it is worth naming precisely.
Infrastructure: a small VPS (1 vCPU, 1 GB RAM, 10 GB disk) runs the whole thing for roughly $4–6/month at most budget providers, or $0 if it lives on hardware you already own (a spare mini-PC, a Pi-class device, an existing homelab node). Reverse-proxy it behind your existing Caddy or Traefik, add TLS, and the marginal cost is effectively zero. Compare that to YNAB at ~$15/month or a managed finance SaaS, and the per-year savings are real — but only if you were already paying for those, and only if you value the sovereignty enough to maintain the box.
The time cost is the honest one. You will spend an evening getting it running. You will spend occasional evenings when a major version bumps and you want to read the upgrade notes. You are responsible for backups, for OS patching on the host, and for the database encryption key. Nobody is on the other end of a support contract when something breaks at 2 a.m. For a solo operator who already maintains a server, this is background noise. For someone who has never touched Docker, it is a genuine, recurring tax that the "free" label does not prepay.
There is also the data-entry cost, which is a feature disguised as a bug. Firefly III does not quietly scrape your bank. You import deliberately, or you type. That means your data is accurate because you engaged with it, not because an algorithm guessed. But it also means if you ignore it for two months, your records are two months stale, and unlike a connected app there is no red badge shaming you back. The cost of Firefly III is the cost of attention.
5. Budgets, Rules, and the Automation That Makes It Bearable
The reason Firefly III is usable rather than a chore is its rule engine. Rules watch incoming transactions and transform them: rename a cryptic "SQ*9281 DELTA" to "Delta Airlines," assign it to the "Travel" category, tag it "tax-deductible," and move on. You build rules once and they fire on every matching transaction after that. For anyone whose bank exports hieroglyphic descriptions, rules are the difference between a maintained ledger and an abandoned one.
Budgets sit on top. You define a period (most people use a month) and assign expected amounts to categories. Firefly III shows spent-versus-budgeted live, with overspend highlighting. Unlike some tools, it does not force a specific budgeting philosophy on you — you can run zero-based budgeting, envelope-style saving, or loose "don't exceed $X on dining" limits. The flexibility is a double-edged sword: beginners sometimes want to be told how to budget, and Firefly III declines to parent you.
Recurring transactions handle the predictable. A salary lands, a mortgage draws, a streaming subscription renews — you model these as recurring and Firefly III can create them automatically or surface them as "ready to book" so you confirm before they hit the ledger. Bills track due dates independent of recurrence, which matters for irregular but mandatory obligations (quarterly taxes, annual insurance). The combination means the boring 80% of personal finance — the stuff that recurs — can be largely automated, leaving you to engage only with the genuinely novel spend.
The rule engine is also where Firefly III connects to the rest of a sovereign stack. Because rules can be as specific as you need, you can, for example, auto-tag every transaction at a certain merchant as business-related, then query that tag at tax time. The system is a financial data layer, not just a viewer, and the automation is what makes that layer worth operating.
6. Importing Your History: The Data Importer
Firefly III proper does not talk to your bank. The companion tool, the Firefly III Data Importer, does the messy work of reading a CSV (or, with configuration, a direct bank API via GoCardless-style connectors in some regions) and mapping it into Firefly III transactions. This separation is intentional: the core app stays a clean accounting system, and the inherently fragile, bank-specific ingestion lives in a tool you can run once, configure carefully, and then ignore.
The importer walks you through column mapping: which column is the date, which is the amount, which is the description, and how to detect the sign. It handles the classic CSV nightmares — amounts with currency symbols, negative-in-parentheses, thousands separators, ambiguous dates — and it de-duplicates against transactions already in the system so a re-run does not double-count. For most people, the initial import of a few years of history is a one-afternoon task, after which day-to-day entry is a few minutes a week.
There is a harder, more powerful path: some regions support connecting the importer to a real bank feed through an aggregator. This reintroduces a third party into your otherwise sovereign setup, and it is worth being deliberate about. If your goal is "my financial data never leaves my infrastructure," then CSV export from your bank's portal, manually dropped into the importer, is the sovereign choice. If your goal is "I want automation and accept a vetted intermediary for the fetch step," the feed option exists. Firefly III itself never sees your bank credentials; the importer does, briefly, during configuration. Name that trade explicitly before you enable it.
7. The REST API: Where Firefly III Becomes a Platform
Firefly III ships a thorough JSON REST API, and this is where it stops being "a finance app" and becomes "the financial data layer of your homelab." Every meaningful operation — create a transaction, read an account balance, pull chart data, manage categories and tags — is available over HTTPS with a personal access token. For an operator who already scripts their life, this is the feature that justifies the self-hosting effort.
Concrete patterns people actually build: a cron job that reads a specific account's balance each morning and pushes it to a dashboard (or a Home Assistant sensor, tying your finances into the same panel as your power usage). A script that watches for transactions tagged "business" and forwards them to a ledger or a tax-prep folder. A webhook-style flow where a recurring bill, once booked, notifies you in chat. Because the API is complete, you are limited by your imagination and your token scope, not by the UI's feature set.
The API also means Firefly III can be the source of truth that other tools read from, rather than a silo. If you run a small business and want invoicing, or a net-worth tracker, or a custom report the built-in ones do not cover, you read from Firefly III rather than maintaining a second copy of your accounts. The AGPL license is relevant here: if you ever wrap Firefly III behind a network service you offer to others, the AGPL's network clause means your modifications must be available to those users. For pure self-hosting, none of that applies — you owe nothing and pay nothing.
8. Mobile: The Gap Everyone Hits First
The single most common complaint about Firefly III is the absence of an official mobile app. There is no first-party iOS or Android client. You can use the responsive web UI in a mobile browser, and it is usable, but it is a web view of a desktop-oriented accounting tool, not a crafted mobile experience. For someone who wants to snap a receipt and log it from the checkout line, that friction is real.
The ecosystem partially fills the gap. Several third-party mobile apps exist — both open-source and commercial — that speak the Firefly III API. Quality and maintenance vary, and you are trusting a third party with your API token, so the sovereignty story gets nuanced on mobile: the server is yours, but the client you install on your phone may not be. For many operators the compromise is acceptable (a read-only token on the phone, full write only from the desktop), but it is a compromise, and pretending otherwise would be dishonest.
The deeper point is philosophical. Firefly III assumes finances are something you sit down with, not something you thumb through on a bus. The web UI is where the real work happens; mobile is a viewer. If your mental model requires constant mobile capture, you will fight the tool. If you can batch your entry weekly from a laptop, the missing app never matters. Which camp you are in determines whether this gap is a dealbreaker or a non-issue.
9. Limitations: What Firefly III Deliberately Does Not Do
No honest review ships a tool without naming its edges, and Firefly III has sharp ones. First, it is not an investment tracker. It models cash and liabilities; it does not track brokerage holdings, stock prices, or portfolio performance. You can fake a brokerage account as an asset with manual balance updates, but there is no market-data integration, no cost-basis math, no realized-gain reporting. If "see my net worth including my index funds" is the goal, Firefly III is the wrong tool or at best half of one.
Second, multi-user is thin. Firefly III is designed for a single household on one login. There is no robust multi-tenant model where three roommates each see only their own books. You can share the instance, but everyone shares the same data scope. For a family that wants one joint ledger, fine. For a group that needs partitioned access, look elsewhere or accept the limitation.
Third, the learning curve is front-loaded. Double-entry, accounts, rules, currencies, the importer — a newcomer faces a wall of concepts before the first "aha." The docs are good, but they assume you are willing to learn accounting basics. People who want a magic link that fixes their finances will bounce. The tool rewards the curious and punishes the impatient.
Fourth, reports are solid but not gorgeous. Firefly III produces real, exportable reports — by category, by tag, by period, audit lists — but the visualization layer is functional, not a Tableau competitor. If presentation polish matters more than data integrity, you may find it plain. For a sovereign operator, plain-but-correct usually wins; name your priority.
10. Security and the AGPL Story
Firefly III is AGPL-3.0, and the security posture follows from both the license and the architecture. Because you self-host, there is no vendor database holding your finances — the data lives on your server, encrypted at the field level with the
APP_KEY you control. The application has no built-in reason to contact the internet; in a default, CSV-import configuration, your financial data never leaves your infrastructure. That is the sovereignty headline, and it is true.
The AGPL matters if you ever think about offering Firefly III as a service to others. The Affero clause extends copyleft to network use: if you modify Firefly III and let users interact with it over a network, you must offer them your modified source. For personal self-hosting this is irrelevant — you are the user. But it is the reason a competitor cannot take Firefly III, add proprietary features, and sell it as a closed hosted product without releasing their changes. That protection is part of why the project stays genuinely free; it is worth understanding if you ever contemplate building on top of it.
Operationally, you harden Firefly III the way you harden any web app: TLS at the proxy, a strong unique password, MFA if you put it behind an SSO layer (pair it with Authelia or Authentik, both covered in this series), restricted admin network access, and regular patching. The app itself is a mainstream Laravel stack with a normal security track record; the bigger risk is almost always your deployment hygiene, not the code. Keep the image updated, keep the key backed up, and the surface is small.
11. Firefly III vs Actual Budget vs GnuCash vs YNAB
This is the comparison operators actually make, so it deserves specifics. Actual Budget (covered earlier in this series) is the closest sibling: also self-hosted, also free, focused on zero-based budgeting with a slicker mobile experience and a different data model (it syncs via a server you run). Actual wins on mobile and on the "tell me where every dollar goes this month" philosophy; Firefly III wins on double-entry correctness, multi-currency, and the API-as-a-platform story. They are not enemies; some people run both for different purposes.
GnuCash is the desktop, non-hosted veteran. It is double-entry too, more powerful for complex books, but it is a desktop app with no modern web UI and no API to speak of. If you want a server you can reach from anywhere, GnuCash is the wrong shape. Firefly III trades some GnuCash depth for accessibility and reachability.
YNAB is the commercial gold standard for behavior-change budgeting. It is polished, mobile-first, and excellent at what it does — for a subscription. You trade money and data custody for that polish. Firefly III is what you run when you decide the custody and the $15/month are not worth the polish, and when you want the data model to be correct rather than persuasive.
Ledger and Beancount are plain-text, command-line double-entry systems. They are the sovereign extreme: your ledger is a text file in git. Firefly III is the middle path — double-entry rigor with a web UI and API, without forcing you into a terminal. Pick your layer on the convenience-versus-control spectrum; Firefly III sits at a deliberately pragmatic point on it.
12. Backups and Disaster Recovery
Because Firefly III is the system of record for your money, backups are not optional, and the encryption key is part of the backup. The correct unit of backup is: the database dump + the
APP_KEY + the upload attachments volume (receipts, statements). Lose any one and you have a problem; lose the key and the encrypted fields are gone permanently even with the database.
A sane routine: a nightly database dump (the project's container can be scripted to
mysqldump or pg_dump), copied off-box to wherever your other backups live, alongside a separately-stored copy of the APP_KEY (a password manager, not the same server). Test a restore quarterly — spin up a throwaway container, load the dump, confirm balances match. The "restore works" check is the only backup that counts; an untested dump is a hope.
Version history is your friend here. Firefly III tracks transaction history, so a mistaken edit is recoverable within the app. But a dropped database is not, which is why the dump is the real safety net. Treat the financial ledger like the irreplaceable record it is, because it is — there is no "reset password" that recovers a deleted year of transactions.
13. Upgrading Without Losing Your Ledger
Firefly III ships frequent releases, and upgrades are generally smooth because the app runs migrations on boot. The discipline that prevents pain: read the release notes before you pull a new image, especially across major versions. The project occasionally changes environment variable names or requires a new
APP_KEY format transition, and the upgrade that breaks silently is usually the one where you skipped the notes.
The safe pattern is the safe pattern everywhere: take a database dump immediately before upgrading, then pull the new image and recreate the container. If something is wrong, you restore the dump and roll the image tag back. Because the data lives in the database, not the app container, a rollback is a container swap plus a restore, not a catastrophe. Pin your image tags in production (do not run
:latest blindly) so an unexpected upstream release cannot ambush you at 3 a.m.
For the Data Importer, upgrade it in lockstep when you upgrade the core, since the two negotiate a protocol. Mismatched versions usually still work but occasionally surface import quirks; keeping them aligned removes a class of weird bugs. As with everything in this series, the operator who treats upgrades as a planned event rather than a reflex has a boring, reliable life.
14. A Real Deployment Scenario: The Cross-Border Remote Worker
Consider a concrete operator: a remote worker paid in USD, living in the eurozone, with a local checking account, a US credit card, and a savings account in a third currency. Single-entry apps choke on this; Firefly III handles it natively. They model three asset accounts (USD checking, EUR checking, savings) and one liability (the credit card). Each payday is a transaction from an external income source into USD checking. Each eurozone bill is a transfer or payment in EUR. Exchange rates convert for the net-worth view.
Their weekly ritual: export the credit card CSV, drop it in the Data Importer, watch rules auto-categorize 90% of lines, fix the two weird ones, done in ten minutes. Their tax prep: query the "tax-deductible" tag, export, send to their accountant. Their net worth: a real number across three currencies, updated whenever they book a transaction. No bank credential was ever shared. No SaaS knows their income. The server sits on a Pi in their apartment behind their existing reverse proxy. This is the Firefly III sweet spot, and it is a genuine sovereignty win, not a marketing one.
15. Where Your Data Goes (and Does Not)
State it plainly, because it is the reason most readers are here. In a default Firefly III deployment with CSV import, your financial data goes nowhere except your own database. The application does not phone home. The only outbound traffic is optional: if you enable automatic exchange-rate updates, it fetches rates from a configurable provider; if you enable a bank feed in the importer, it talks to that aggregator during import. Both are off by default and both are configurable or disableable.
Contrast this with any connected commercial app, where your transaction graph — who you pay, when, how much, your location inferred from merchant data — is processed by a vendor whose business model may include analytics, and whose jurisdiction (often US) exposes that data to laws like the CLOUD Act. Self-hosting Firefly III does not make you匿名; your bank still knows your transactions. But it removes the intermediary that would otherwise aggregate and potentially monetize the pattern. For a sovereignty-minded operator, that removal is the product.
The honest caveat: sovereignty is only as strong as your deployment. If you expose Firefly III to the public internet with a weak password and no MFA, you have built a nicer target than a vendor's hardened service. Put it behind your SSO (Authelia/Authentik from this series), restrict admin to a VPN or your LAN, and the data stays yours in the only sense that survives a subpoena to a third party: there is no third party.
16. Who Should Run It, and Who Should Not
Run Firefly III if: you want double-entry correctness without a desktop-only tool; you operate in multiple currencies; you already self-host and can absorb the small maintenance tax; you value data custody over convenience; you are willing to engage with your finances weekly rather than be nudged by an app. It rewards precisely the operator this blog is written for.
Do not run Firefly III if: you need investment tracking (use a brokerage-linked tool); you require a polished first-party mobile app (use Actual Budget or a commercial app); you will not touch it for months at a time (the unconnected model means staleness is on you); you want to be told how to budget rather than given a flexible system (try YNAB or Actual's philosophy); or you have never run a container and have no interest in learning (the setup cost will sour you).
The decision is not "open source good, SaaS bad." It is "do I want to own the ledger, and am I willing to operate the thing that owns it?" If yes, Firefly III is one of the most mature, actively maintained options in its class. If no, no amount of stars should talk you into a tool whose core feature is the very responsibility you are trying to avoid.
17. The Sovereignty Verdict
Firefly III is what self-hosted personal finance looks like when the builders refuse to compromise on the one thing that matters: the data never has to leave your hardware. AGPL-3.0 keeps it honestly free and keeps any hosted competitor honest about their modifications. Double-entry keeps your math true. The API keeps it useful as a platform rather than a silo. The gaps — mobile, investments, multi-tenant — are real but bounded, and most are gaps by philosophy, not by neglect.
For the operator who already runs a homelab, Firefly III slots in beside your other sovereign tools as the financial ledger: backed by your database, fronted by your proxy, guarded by your SSO, owned by you. The cost is an evening to set up and a weekly ten minutes to maintain, plus the discipline to back up the key. The return is a financial record no vendor can read, sell, or shut down. In a category where "free" usually means "you are the product," Firefly III is free because you are the operator — and that is the deal worth taking.
Related
For the rest of a sovereign, self-hosted stack, these pieces from our series travel with Firefly III:
- Actual Budget: The Zero-Based Budgeting Alternative You Host — the closest sibling, stronger on mobile and method, weaker on double-entry and multi-currency.
- Authelia: SSO and 2FA for Everything Behind Your Reverse Proxy — the layer to put Firefly III behind so the ledger is never exposed without MFA.
- Caddy: The Web Server That Encrypts for You — the reverse proxy to publish Firefly III over TLS without touching Certbot.
- Keycloak: The Open-Source Identity Platform With No Open-Core Trap — a heavier IdP option if you want SAML/OIDC in front of your finance tools.
- BookStack: Documentation You Control — pair it to keep your finance-operations runbook and recovery procedure next to the ledger.
Comments (0)
No comments yet. Be the first to comment!