Skip to content
Budvo
Install

Add-ons

Add-ons change how Budvo looks and add small extras to it: a new color theme, a guide for cancelling subscriptions, or a pixel pet whose treats turn into debt payments. They come from the marketplace, where NullDaily reviews and signs every package, or you can build your own and sideload it onto your server.

This section is for people who build add-ons, and for anyone who wants to know exactly what an add-on is allowed to do before turning one on.

Kinds of add-ons

KindRuntimeWhat it does
Themetheme@1Swaps Budvo's colors for light and dark mode. Colors only: no code, no permissions.
Featureapp@1A small web app shown inside Budvo, in the dashboard and in the iOS app. It runs in a sandbox and talks to Budvo through the bridge.
Connectorconnector@1Reserved for connectors that sync accounts and balances. Listed in the catalog, not runnable yet.

The safety model

Add-ons are built so the worst a misbehaving one can do is small and visible.

  • A sandbox. An app@1 add-on runs in an iframe with sandbox="allow-scripts" and an opaque origin, so it can't read Budvo's cookies, call Budvo's API or see the rest of the page. Its content security policy allows only its own files and no network at all. The iOS app shows it in a web view with the same rules. See Runtimes.
  • Permissions you can read. Everything an add-on can ask for is listed in its manifest, and you see that list before you turn it on. With no permissions, an add-on can only show its own pages, toasts and resize itself.
  • No accounts, no transactions. Nothing an add-on can ask for returns account numbers or transactions. The most it can read is a summary: safe to spend, debt balances and goals, and only with the matching permission.
  • Privacy mode is respected. While privacy mode is on, requests for the summary, debts and goals are refused unless you allowed that add-on.
  • Network only where it says. An add-on can fetch from the internet only through Budvo, only with GET, and only from the hostnames in its manifest.
  • Pledges, not payments. No add-on can move money. The most it can do is drop a pledge into your household's piggy bank, the jar, up to a daily limit.
  • Signed, or clearly sideloaded. Marketplace packages are reviewed and signed by NullDaily, and your server checks the signature and SHA-256 before installing. Add-ons you put on your server yourself are marked Sideloaded and start switched off.

Permissions

PermissionLets the add-on
summary:readSee safe to spend, total debt, your debt-free date and next payday
debts:readSee each debt's name, kind, balance, APR and payoff date
goals:readSee savings goals and their progress
jar:readSee the jar's balance, where it goes when smashed and how much has been smashed so far
jar:pledgeAdd pledges to the jar, up to its daily limit
storageSave its own data, up to 64 KB, shared by your household
netFetch text or JSON from the hostnames listed in its manifest
league:sharePlay in leagues with friends on other Budvo servers, sharing only display names, picks and points. Off until the owner switches it on, and each person agrees once

Showing a toast, resizing itself and reading its context (light or dark mode, colors, currency, locale, debt mode and privacy mode) need no permission.

The jar

The jar is how add-ons help with money without ever touching it.

  1. An add-on pledges. Buying your pixel pet a snack pledges $1.50, say. A pledge is a note, not a transfer: nothing leaves any account.
  2. The jar fills, within limits. Each add-on has a daily limit: the smaller of what its manifest asks for and what you set. Anything above the limit is dropped, and the add-on is told so it can say something kind instead of trying again.
  3. You smash it. Only you decide when. A smash goes into a debt, or, with no debt, into savings or investments.
  4. The safety net holds. A smash never takes your checking account below your safety net.

Versions and compatibility

Every add-on says which Budvo versions it works with (compat.budvo) and, for app@1, which SDK it was built for (compat.sdk). Your server checks this when installing, every time it starts, and before it updates itself: the update screen warns about add-ons a new version would switch off. The manifest reference has the details.

Build one

The quickest path from nothing to an add-on running on your server:

terminal
# The SDK and its command line toolnpm install --save-dev https://budvo.nulldaily.com/sdk/budvo-sdk-1.0.0.tgz# A working add-on to start fromnpx budvo-addon init my-addon# Run it in a local stand-in for Budvo, with made-up moneynpx budvo-addon dev my-addon# Check it the way Budvo and the marketplace willnpx budvo-addon validate my-addon

Then copy the folder into your server's add-ons folder and press Rescan. Next steps:

Next Manifest reference