TaxHacker: what self-hosting an AI receipt reader actually involves
Self-hosted AI accounting app. LLM analyzer for receipts, invoices, transactions with custom prompts and categories
At a glance
- What is it?
- TaxHacker reads receipt photos, invoice PDFs and bank statements through an LLM of your choice and stores the extracted fields in a filterable database. The interesting part for an engineer is the plumbing: three containers, Postgres 17, a cron sidecar, and a plain .env file that decides which model does the reading.
- Who is it for?
- TaxHacker fits a freelancer who wants their documents to stay on their own hardware and is willing to run a Postgres database and pick an LLM. It does not fit anyone who needs filed tax returns, audited figures or a guarantee that a receipt was read correctly.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 3 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 13, 2026, and from our analysis. They are not legal advice.
Star history
- vas3k/TaxHacker6,824 ★ · +132
| Repository | 2026-09-10 | 2026-11-13 |
|---|---|---|
| vas3k/TaxHacker | 6.7k | 6.8k |
132 Stars in the last 64 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Three containers, two volumes, one exposed port
The whole deployment is one compose file, and it is worth reading before you clone anything. The `app` service pulls `ghcr.io/vas3k/taxhacker:latest`, publishes `7331:7331`, mounts `./data` at `/app/data` and waits on `postgres`. A second service named `cron` runs the same image with a different command and an extra read-only mount for its crontab. The database is `postgres:17-alpine` with its own `./pgdata` volume. All three set `restart: unless-stopped` and `security_opt` of `no-new-privileges:true`, and all three cap their logs at three 100M files using the local logging driver.
services:
app:
image: ghcr.io/vas3k/taxhacker:latest
ports:
- "7331:7331"The .env decides which model reads your receipts
Almost nothing about extraction is hardcoded. `.env.example` ships three provider blocks, each a model name next to an empty key: `OPENAI_MODEL_NAME="gpt-4o-mini"`, `GOOGLE_MODEL_NAME="gemini-2.5-flash"` and `MISTRAL_MODEL_NAME="mistral-medium-latest"`. The comment says you can put the key there or the app will ask you to enter it. Two settings change the shape of the deployment rather than the model: `SELF_HOSTED_MODE=true` unlocks the local model option, and `DISABLE_SIGNUP=true` closes registration. `UPLOAD_PATH` decides where documents land on disk.
PORT=7331
SELF_HOSTED_MODE=true
DISABLE_SIGNUP=true
UPLOAD_PATH="./data/uploads"`BETTER_AUTH_SECRET` deserves attention. The example file carries a long random string placeholder, and the comment says self-hosted Docker can generate and persist one if you omit it. Stripe and Resend keys sit in the same file, which tells you billing and email are optional subsystems rather than core features.
A local model through an OpenAI-compatible endpoint
Run your own inference and TaxHacker points at it instead of a vendor. The named targets are Ollama, LM Studio, vLLM and LocalAI, all reached through an OpenAI compatible API endpoint. The catch is stated in one blunt sentence: make sure the local model is good in OCR tasks, results are not guaranteed. That sentence is the honest description of the whole feature. A receipt photo has to be read into text before any field extraction happens, and a weak vision model produces confident nonsense rather than an obvious error. The README's feature list also puts the privacy boundary on you: you are the one responsible for the quality and privacy of your data, whether the model runs on your machine or not.
Custom fields and prompts are the real data model
The schema is not fixed, and this is where TaxHacker differs from a receipt scanner with a settings page. You can create unlimited custom fields, which the docs compare to adding columns in Excel, and each field can carry its own AI prompt. Prompts are editable for fields, categories and projects, plus the general system prompt template in settings. Categories and projects sit alongside them for grouping, full text search reaches into the recognised document content, and bulk operations process many documents or transactions at once. Two extraction details are worth knowing: new uploads wait in an `unsorted` pile until you process them, and line items can be split out of an invoice into separate transactions.
Conversion uses the rate from the transaction date
Multi currency handling is the feature with a concrete number attached, and the number is not small: 170 or more world currencies plus 14 popular cryptocurrencies, with BTC, ETH, LTC and DOT named in the list. The rule that makes the accounting defensible is that the rate comes from the transaction date rather than today, so last year's invoice converted at last year's rate. Currency detection runs on the document itself. When the model guesses wrong or a transaction has no document at all, manual entry is always available, which is the escape hatch for anything the extraction layer mangles. Paper trail storage is handled separately: documents attach to their transactions and travel with CSV exports.
A cron sidecar runs the mailbox importer
Email is a first class input, and it is handled by infrastructure rather than by the web app. The compose file mounts `./etc/crontab` read only at `/mnt/crontab` into the cron container and overrides its command with `docker-cron-entrypoint.sh`. A related script lives in `package.json` as `email:sync`, pointing at `app/(app)/apps/email/scripts/fetch-emails.ts` and executed through `tsx`. The dependency list explains why that script exists: `imap-simple` for talking to the mailbox and `mailparser` for turning message bodies into text before the LLM sees them. The runtime image installs the `cron` daemon for exactly this container.
Node 26, prisma migrate deploy, and a private package
The build is Next.js on Node 26 with Prisma 7 for the database layer. `package.json` marks the package `private: true` and requires `node >= 26`. The Dockerfile starts from `node:26-slim`, runs `npm ci`, generates the Prisma client with `npx prisma generate`, then `npm run build`, with a `SKIP_PRISMA_GENERATE` escape for cross architecture emulated builds. The runtime stage installs `ca-certificates`, `cron` and `ghostscript`.
"start": "prisma migrate deploy && next start",
"dev": "next dev -p 7331 --turbopack"Migrations run automatically on every start, so schema changes apply on upgrade without a separate step. Local work runs on the same port as production, 7331.
An early development warning on a 0.8.x version line
The project carries a notice above its feature list: still in early development, use at your own risk. The version numbers support that reading. `package.json` is at 0.8.5, matching the published v0.8.5 tag from 2026-07-20, and the two tags before it are v0.8.2 and v0.8.1, both from 2026-07-07. The last push to the default branch came on 2026-10-31, so commits are landing on the main branch after the last release, which means a fresh clone can be ahead of the published image. What TaxHacker does not do is file anything. It produces filtered exports and reports to hand to an accountant, and it makes no claim about the correctness of what the model read. Sentry is wired into the build for server and edge, and the licence is MIT. Treat the auto-categorisation and the item splitting as conveniences that need a human pass, because a wrong category or a misread line item propagates straight into the totals you later hand over.
Editorial conclusion
TaxHacker fits a freelancer who wants their documents to stay on their own hardware and is willing to run a Postgres database and pick an LLM. It does not fit anyone who needs filed tax returns, audited figures or a guarantee that a receipt was read correctly. Before trusting its output, check which model name is set in your .env, confirm BETTER_AUTH_SECRET is set, and reread your own entries against the original PDFs.
Frequently asked questions
Which AI providers can TaxHacker use for extraction?
OpenAI, Google Gemini and Mistral out of the box, each with a model name and API key in the .env file. In self-hosted mode you can point it at a local model such as Ollama, LM Studio, vLLM or LocalAI through an OpenAI compatible endpoint.
What does it take to run TaxHacker on my own server?
A Docker Compose setup with three services: the app on port 7331, a cron container, and postgres:17-alpine. The app image is published as ghcr.io/vas3k/taxhacker:latest and expects SELF_HOSTED_MODE set in the environment.
Can TaxHacker read receipts fully offline with a local model?
It can call any OpenAI compatible endpoint, which covers Ollama, LM Studio, vLLM and LocalAI. The documentation warns that the local model has to be good at OCR and that results are not guaranteed otherwise.
How do I get transactions out of TaxHacker?
Filtered transactions export to CSV with the attached documents included, and complete data archives can be downloaded for migration to another service. You can also filter by date ranges, categories, projects, amounts and custom fields.
Should I trust TaxHacker with real accounting data?
It is labelled early development and to be used at your own risk. Extraction quality rests on the model you configure, and the project states that you are responsible for the quality and privacy of your data.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/vas3k-taxhacker)Star history chart for your README
[](https://hysenlabs.com/projects/vas3k-taxhacker)Was this useful?