A self-hosted household budget tracking application, available as a Home Assistant add-on or as a standalone Docker deployment.
Otter helps you manage your family's monthly budget by organizing spending into categories, tracking transactions against budget entries, and visualizing where your money goes.
- Monthly budget tracking — Create monthly budgets with categories and planned amounts. New months automatically copy budget entries from the previous month.
- Transaction recording — Log payments against budget entries with dates and notes.
- Spending summaries and charts — Visualize spending vs. budgeted amounts per category and month.
- Multi-language support — English and Polish interfaces via vue-i18n.
- Configurable currency — Set your currency code, minor unit name, and decimal places (defaults to PLN).
- Mobile-first design — Built with Vuetify (Material Design) and optimized for mobile use.
- Home Assistant 2024.1.0 or newer
- Home Assistant Supervisor (the add-on system requires a supervised installation — Home Assistant OS or Home Assistant Supervised)
- In Home Assistant, navigate to Settings > Add-ons > Add-on Store.
- Click the three-dot menu in the top right and select Repositories.
- Add the following repository URL:
https://github.com/kamilczerw/otter - Click Add and then Close.
- Find Otter Budget Tracker in the add-on store (you may need to refresh the page).
- Click on it and then click Install.
Before starting the add-on, configure the currency settings under the Configuration tab:
| Option | Description | Default |
|---|---|---|
currency_code |
ISO 4217 currency code (e.g., PLN, EUR, USD) |
PLN |
currency_minor_unit_name |
Name of the smallest currency unit (e.g., grosz, cent) |
grosz |
currency_decimal_places |
Number of decimal places for currency display | 2 |
- Click Start to launch the add-on.
- Once running, Otter appears in the Home Assistant sidebar with a cash register icon.
- Click the sidebar entry to open the application. Authentication is handled automatically through Home Assistant's Ingress system.
The SQLite database is stored at /data/budget.db using Home Assistant's persistent storage. Your data is preserved across add-on restarts and updates.
To back up your data, use Home Assistant's built-in backup feature, which includes add-on data.
amd64aarch64
If you want to run Otter outside of Home Assistant, you can use Docker Compose.
- Docker and Docker Compose
docker compose up -dThe application will be available at http://localhost:3000.
The SQLite database is persisted in a Docker volume (budget-data).
The standalone deployment uses environment variables with the APP__ prefix (double underscores as separators):
# Example overrides
APP__CURRENCY__CODE=EUR
APP__CURRENCY__MINOR_UNIT_NAME=cent
APP__CURRENCY__DECIMAL_PLACES=2
APP__DATABASE__URL=sqlite:///data/budget.dbAdd these to the environment section of docker-compose.yml as needed.
cd backend
cargo build # Build all workspace members
cargo test # Run all tests
cargo run --bin api # Start the API server on port 3000cd frontend
npm install
npm run dev # Start Vite dev server on port 5173
npm run build # Type-check and build for productionThe backend follows hexagonal (ports & adapters) architecture as a Rust workspace:
domain— Pure business logic, domain types, and repository traits. No framework dependencies.db— SQLite adapter implementing domain repository traits via SQLx.api— HTTP/REST layer using Axum, with request/response types separate from domain entities.
The frontend is a Vue 3 single-page application using the Composition API, Vuetify for UI components, and Chart.js for data visualization.
See the repository for license details.