hledger Mobile Access

A self-hosted wrapper around hledger for easy access across all my devices.

Project overview

hledger is a plain-text, double-entry accounting tool that runs on the command line. It's fast and reliable, but there's no simple way to access it without being at a terminal.

This project builds a secure API layer around hledger, exposes it via Cloudflare Tunnel, and serves a mobile-friendly Single Page Application through Cloudflare Workers. The journal file stays on my home server the entire time. No financial data touches any cloud service (except through caching which I added later).

This is a personal tool built just for me. I also set it up as a PWA, so it installs and runs like a native app on my phone. If you're curious, you can find the source code here.

hledger balance view

Balance

hledger monthly breakdown

Monthly

Architecture

A FastAPI app on my home Linux machine wraps the hledger CLI. It takes an HTTP request, runs the right hledger command, and returns JSON.

Cloudflare Tunnel exposes the FastAPI app to the internet without opening any inbound ports. Cloudflare Access sits in front of the tunnel and the webpage, blocking unauthenticated users or api calls.

A Cloudflare Worker serves the SPA to the browser and proxies API calls to the tunnel, injecting the service token and Bearer token server-side. Neither secret ever reaches the browser.

Technical implementation

API endpoints

  • GET /balance — all account balances
  • GET /is — income statement
  • GET /monthly — monthly breakdown
  • GET /transactions — list of transactions
  • GET /accounts — chart of accounts, used for autocomplete
  • POST /sync — git pull from remote
  • POST /add — appends transaction to journal, commits, tags, and pushes

Security

Since this is my personal finances, I have done my best to keep the data secure at each layer. The journal file lives on my home server and is git pushed to a second self-hosted local repo. The app itself sits behind Cloudflare Access, which gates all requests before they ever reach my machine. Traffic runs through Cloudflare Tunnel so no ports are exposed. And the FastAPI layer adds one more check with a Bearer token on every request.

Stack: Python, FastAPI, uvicorn, systemd, hledger, Cloudflare Tunnel, Access, Workers.

This project is ongoing. Currently testing as of Mar 2026.