budgetzero: envelope budgeting that keeps your data in the browser

Envelope budgeting with the ledger living in the browser

budgetzero is described as a free, open-source, privacy-focused, offline-first budgeting system, and the project is explicit that it is zero-based envelope budgeting. The pitch in the README is short: zero ads, zero trackers, just budgeting.

The distinguishing decision is where the data lives. The README states that budgetzero uses PouchDB to store all data client side in the browser. There is no server component in the default deployment, no account, and no sync unless you set one up.

That is a genuinely different architecture from the hosted budgeting services, and it cuts both ways. On the good side, your transaction history never reaches a company, the application works with the network off, and there is nothing to subscribe to. On the bad side, and the README is direct about it, all data is stored in the browser and may be lost if you clear the browser's data.

That warning is the single most important line in the feature list for anyone evaluating this. A budget is a record of months of decisions about money, and it lives in a browser profile that a cache clear can empty. The project offers CouchDB sync as the answer, which is discussed separately below, and a roadmap item for a hosted sync through budgetzero.io.

The audience is people who already know what zero-based budgeting is. The features list is short: zero-based envelope budgeting, offline-first storage, transaction import in OFX, QFX and CSV formats, carrying negative balances into the next month, and privacy with no trackers and no analytics.

The project carries a clear status warning: budgetzero is under active development and considered an alpha version, and you may encounter significant bugs and breaking changes. The last push was on 2026-10-16 and the repository is not archived, so the work is real and current.

Three ways to use it, and what each one costs you

The getting started section lists three routes.

The first is the hosted app at app.budgetzero.io. The second is the desktop app for Windows or Mac, downloadable from the releases page, and the package scripts show it is an Electron application with electron-builder handling the build and electron-updater handling updates. The third is self-hosting the web app, either with the Docker image or by building the static files and hosting them on your own web server.

The three routes differ in where your data ends up, and that is the question to ask rather than which is most convenient. The hosted app and the desktop app both keep data in the local browser profile of the machine you used, which means the desktop app is not a synchronised client and a machine migration is a data export problem. The self-hosted route is where you can attach a sync server, which is the only way to get multi-device behaviour in the current design.

The repository layout shows a Vue CLI application with a Dockerfile, an nginx_conf directory, a public directory for static assets, a build directory, a cypress config, a jest config, an eslint config and a prettier config. The build directory and the electron scripts show the desktop packaging is a first-class part of the project rather than an afterthought, and the cypress setup indicates end-to-end tests exist alongside the unit tests.

The dependency list reinforces the browser-first design. The PouchDB family appears in several forms, with pouchdb-browser, pouchdb, pouchdb-authentication, pouchdb-erase, pouchdb-find, pouchdb-live-find and pouchdb-load, along with pouch-vue for the Vue bindings. Chart.js handles the charts, moment handles dates, the banking package handles financial formats, and firebase and firebaseui are present for the planned cloud sync path.

Docker deployment: pull an image, run it, and you are done

The Docker route is the shortest path to a self-hosted instance, and the README documents it in three steps.

First, pull the image:

docker pull budgetzero/budgetzero:latest

Then run it. The README gives a generic form with a desired port, and then a concrete example:

docker run -d -p 8080:8080 --name budgetzero budgetzero/budgetzero

The instance is then reachable at the host address on the port you published.

The Dockerfile explains why this works as a single container. The build stage uses a Node LTS Alpine image, copies the package files, installs production dependencies, installs the Vue CLI service separately, copies the source and runs the build. The production stage is an nginx Alpine image that copies the built static files from the build stage into the nginx html directory and copies a configuration file into place. The container exposes port 8080 and runs nginx as its command.

So the container is a static file server. There is no application server, no database, no session store. That is the architecture visible in the Dockerfile, and it explains why the same image works for a single user and for a family, provided each browser keeps its own copy of the data.

The nginx configuration in the nginx_conf directory is worth a look if you plan to put the instance behind a reverse proxy with TLS, since the default configuration is written for plain HTTP on port 8080.

CouchDB sync is the piece that turns a single browser into a household budget

Syncing across browsers and devices requires you to bring your own server, and the README describes the mechanism. Because the data lives in PouchDB, the sync target is CouchDB, which speaks the same replication protocol. You set up a CouchDB instance reachable from the devices you want to sync, point budgetzero at it, and the databases replicate.

The manual setup instructions are in a collapsed section for advanced users. Install CouchDB on a server, either manually or from the official docker couchdb image. The example given is:

    docker run -d --name budgetzero-couchdb-sync -e COUCHDB_USER=admin -e COUCHDB_PASSWORD=password couchdb:latest

and the README is clear that the admin user and password in that line are placeholders to replace with your own.

Then you open the Fauxton web interface at the CouchDB port on the host, go to Configuration and enable CORS for all domains, create a database with whatever name you want, and in budgetzero go to Settings and set the CouchDB URL for each client. The example URLs given are a local instance and one with credentials in the host part, for example a username and password at a private address on the standard CouchDB port.

Two details carry real operational weight. CORS must be enabled for all domains, which means any origin can attempt requests against that CouchDB, so the instance must not be exposed to the public internet without a reverse proxy, TLS and its own authentication story. And the URL, including credentials, is configured per client, so every browser and device needs it set individually. There is no central account system to hold that configuration for you.

The roadmap lists a self-hosted sync server as coming soon, and Cloud Sync through budgetzero.io as coming soon, which suggests the current manual path is expected to be simplified.

Known issues are listed, and two of them matter for planning

The README has a section headed Known Issues, being worked on, and it is worth reading closely because it tells you what has not been solved.

UI inconsistencies are listed, covering pop-up boxes and colours. Transfer transactions work but may be a bit buggy. And performance is not tested for extremely large budgets, with the threshold given as thousands of transactions.

That last one is the significant engineering constraint. The application keeps the whole budget in the browser's storage and renders charts from it, so a budget with many thousands of transactions is untested territory. For most personal budgets that is irrelevant. For a household with a shared business account, several years of history, and heavy category use, it is the thing to check first, and the honest way to check it is to import a realistic export from your own bank and see whether the app stays usable.

The other known issue, transfers being buggy, is a budgeting problem rather than a performance one, and it lands on a common operation. Moving money between envelopes is how envelope budgeting handles savings, so a buggy transfer path affects the core loop.

The roadmap shows what is in flight: reports marked as started, cloud sync through budgetzero.io, a self-hosted sync server, cross-platform desktop applications for Windows, Mac and Linux, a multi-month view, and payee management. The development board is linked for the current state. Two of those roadmap items, payee management and a multi-month view, are things a budgeting app is normally expected to have, so their absence tells you where this project stands in its own roadmap.

Where budgetzero is the wrong tool

The first wrong-tool case is a household that needs shared access today. The sync story is a CouchDB server you operate, with credentials in a URL configured per device, and the built-in sync is still on the roadmap as a coming soon item. If two people need to see the same budget on their phones, that is the hard part of budgeting, and here it is the part you have to build.

The second is anyone who cannot accept browser-only storage for their financial records. The README's own warning is that data is stored in the browser and may be lost if you clear the browser's data. Without a sync server that risk is real, and the failure mode is silent until you need the data.

The third is a business or a household that needs reporting, reconciliation, scheduled transactions, attachments, rule-based categorisation or multi-currency handling. The feature list in the README is short and does not include any of those, and reports are marked as started rather than delivered.

The fourth is a mobile-only user. The README lists the desktop apps for Windows and Mac, and the roadmap lists cross-platform desktop applications for Windows, Mac and Linux as still to come. There is no native mobile app in the described state of the project.

The fifth is a team with a compliance or audit requirement. The privacy story is strong, zero trackers and zero analytics, but a self-hosted instance with CORS enabled for all domains and credentials embedded in a URL is a configuration you have to get right yourself, and there is no documented hardening guide in the README.

The alternative worth naming is the hosted service on app.budgetzero.io, which is the same application without the deployment work. You give up the self-hosting and you keep the browser-local data model. The other alternative is a conventional budgeting application with a server-side database, which gives you multi-device access and backups as the default, at the cost of handing your transaction history to whoever operates the server.

Editorial conclusion

budgetzero fits a self-hoster who wants envelope budgeting with no account, no ads and no analytics, and who is prepared to run a CouchDB instance or accept browser-only storage. It is the wrong choice for a household that needs shared multi-device access today, since a sync server is still on the roadmap, and the wrong choice for anyone who cannot risk data living only in browser storage, because clearing browser data destroys the budget. Before adopting it, read the data storage warning in the README, and if you want sync, set up CouchDB with the Fauxton interface first and confirm the CORS configuration and the database URL work from your clients before you import any transactions.

Frequently asked questions

Official sources

1. budgetzero/budgetzero on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases