TaxHacker: Build an AI Financial Bookkeeping System at Zero Cost

March 21, 2026

Difficulty: ★★☆☆☆ | Duration: 15 minutes | Takeaway: Master the deployment and core features of a self-hosted AI accounting application

Target Readers: Individual developers, freelancers, small business owners, and tech enthusiasts interested in automating financial management.

Core Dependencies: Docker, Docker Compose, LLM API (OpenAI/Gemini/Mistral)

1 Project Introduction

Let's talk about the TaxHacker project.

TaxHacker is an open-source, self-hosted AI accounting application specifically designed for freelancers, small businesses, and individual developers. Its core selling point is: using AI to automatically identify and extract financial data from invoices and receipts, turning tedious manual bookkeeping into a one-click task.

You might ask, with so many financial software options on the market, why use this one? Here are a few reasons:

  • AI Intelligent Recognition: Upload a photo of a receipt, and the AI automatically extracts product names, amounts, dates, merchants, etc., even recognizing handwritten notes.
  • Multi-Currency Support: Supports 170+ fiat currencies and 14 cryptocurrencies, with automatic conversion based on historical exchange rates on the transaction date.
  • 100% Self-Hosted: Data is stored on your own server, giving you full control over privacy without worrying about financial data leaks.
  • Free and Open Source: MIT license, zero licensing fees.

Built with Next.js 15 + Prisma + PostgreSQL, Docker deployment is very simple and can be up and running in 15 minutes.

2 Environment Preparation

Before we begin deployment, let's confirm your environment.

2.1 Hardware Requirements

  • Memory: At least 4GB RAM (8GB recommended)
  • Storage: At least 10GB available space (for storing uploaded invoice images)
  • System: Linux/macOS/Windows (requires Docker support)

2.2 Software Requirements

You need to install the following software:

  • Docker Engine 20.10+
  • Docker Compose 2.0+

TIP

Windows users are recommended to use WSL2 + Docker Desktop, which is the most stable combination.

2.3 LLM API Preparation

TaxHacker supports three LLM providers:

  • OpenAI (GPT-4o recommended)
  • Google Gemini
  • Mistral

You need an API Key to enable AI invoice recognition. If you want to save money, consider the Defapi platform—it provides mainstream LLM APIs at half the official price, supports various models like OpenAI, Claude, and Gemini, and is fully compatible with the OpenAI API protocol.

3 Project Structure

Before deploying, let's look at the overall structure of the project:

TaxHacker/
├── app/                    # Next.js Application
│   ├── (app)/             # Main app routes
│   │   ├── dashboard/    # Dashboard
│   │   ├── transactions/ # Transaction records
│   │   ├── settings/      # Settings page
│   │   └── ...
│   └── api/              # API routes
├── ai/                    # AI core logic
│   ├── analyze.ts        # Receipt analysis
│   ├── prompt.ts         # Prompt templates
│   └── providers/        # LLM providers
├── prisma/               # Database models
├── docker-compose.yml    # Docker orchestration config
├── Dockerfile            # Docker image definition
└── .env.example          # Environment variable example

4 One-Click Docker Deployment

Now we officially begin the deployment. Docker is the simplest way, running with just a few commands.

4.1 Download Configuration Files

# Create project directory
mkdir -p taxhacker && cd taxhacker

# Download docker-compose.yml
curl -O https://raw.githubusercontent.com/vas3k/TaxHacker/main/docker-compose.yml

# Download environment variable template
curl -O https://raw.githubusercontent.com/vas3k/TaxHacker/main/.env.example

4.2 Configure Environment Variables

# Copy environment variable file
cp .env.example .env

Open .env with your favorite editor and fill in the following key configurations:

# Base Config
PORT=7331
BASE_URL=http://localhost:7331
SELF_HOSTED_MODE=true

# Database Config (using PostgreSQL included in docker-compose)
DATABASE_URL=postgresql://postgres:postgres@db:5432/taxhacker

# File Storage Path
UPLOAD_PATH=/app/data/uploads

# Authentication Secret (at least 16 characters)
BETTER_AUTH_SECRET=your-super-secret-key-change-this

# Disable Signup (recommended for self-hosted mode)
DISABLE_SIGNUP=true

# LLM Config (using OpenAI as an example)
OPENAI_MODEL_NAME=gpt-4o
OPENAI_API_KEY=your-openai-api-key-here

# Or use Google Gemini
# GOOGLE_MODEL_NAME=gemini-2.0-flash
# GOOGLE_API_KEY=your-gemini-api-key-here

WARNING

Be sure to change BETTER_AUTH_SECRET to a complex random string, otherwise security cannot be guaranteed.

4.3 Start the Service

# Start all services
docker compose up -d

On the first run, it will automatically create the PostgreSQL database and run migrations, which takes about 1-2 minutes.

4.4 Verify Deployment

# Check container status
docker compose ps

# Check logs
docker compose logs -f app

If everything is normal, visiting http://localhost:7331 should show the login page.

5 Basic Configuration

Once the service is running, we need to complete some basic configurations.

5.1 First Login

In self-hosted mode, TaxHacker automatically creates an admin account. The default login is:

  • Email: admin@localhost
  • Password: admin

WARNING

Please change the default password immediately after the first login!

5.2 Configure LLM

Click Settings → LLM in the bottom left corner to confirm your API Key is correctly configured. You can test if the AI is working on this page:

Test AI Connection: [Click to Test]

If it returns success, the LLM is configured correctly.

5.3 Set Base Currency

Set your base currency in Settings → Currencies. I recommend setting it to CNY or your most frequently used currency.

5.4 Create Categories

Create the expense/income categories you need in Settings → Categories, such as:

  • Dining
  • Transport
  • Office Supplies
  • Software Services
  • Other Income

6 Core Features in Action

With the environment set up, let's see how to use AI to recognize invoices.

6.1 Upload Your First Receipt

Go to the Unsorted area on the homepage, click the Upload button, and upload a receipt image or PDF invoice.

Supported file formats: JPG, PNG, PDF

After a successful upload, you will see a file preview.

6.2 AI Automatic Recognition

Click the Analyze button next to the file, and the AI will begin analyzing your receipt. After a few seconds, you will see the extracted results:

{
  "date": "2026-03-15",
  "merchant": "Starbucks Coffee",
  "amount": 35.00,
  "currency": "CNY",
  "items": [
    { "name": "Latte", "quantity": 1, "price": 30.00 },
    { "name": "Napkin", "quantity": 1, "price": 5.00 }
  ],
  "category": "Dining"
}

If the results are incorrect, you can manually edit and correct them.

6.3 Confirm and Save

After confirming the data is correct, click Confirm, and the transaction will enter your ledger.

6.4 Automatic Multi-Currency Conversion

If you upload a foreign currency invoice, such as USD or EUR, TaxHacker will automatically:

  1. Identify the currency type
  2. Retrieve the historical exchange rate for the transaction date
  3. Convert it to your base currency

You can view the list of supported currencies, including BTC, ETH, and other cryptocurrencies, in Settings → Currencies.

6.5 Custom Fields

If you have special extraction needs, you can create custom fields in Settings → Fields. For example, if you want to extract a Tax ID from an invoice:

  1. Click Add Field
  2. Field Name: Tax ID
  3. Fill in AI extraction prompt: Please extract the Tax Identification Number/Tax ID from the invoice
  4. Save

The next time you analyze an invoice, the AI will automatically attempt to extract this field.

7 Data Export and Backup

One of the most important aspects of bookkeeping is that data is exportable, and TaxHacker performs well here.

7.1 Filtered Export

On the Transactions page, you can filter by date, category, project, and other criteria:

  • Date range: 2026-01-01 to 2026-03-21
  • Category: Dining, Transport
  • Amount: > 100

After filtering, click Export CSV to export the transaction records along with all attachments.

7.2 Full Backup

In Settings → Backups, you can create a full data backup, including:

  • Database snapshot
  • All uploaded files
  • Configuration information

Backup files can be downloaded locally to ensure data security.

8 Troubleshooting

You may encounter these issues during deployment and use:

Q1: Container failed to start, database connection error

Check if DATABASE_URL in docker-compose.yml is correct. The default configuration uses db as the hostname (internal Docker network). If you used a custom database, adjust accordingly.

Q2: AI analysis stuck on "Processing"

First, check if the LLM API Key is correctly configured. Then check the container logs:

docker compose logs app | grep -i error

If you see a rate limit error, it means your API call frequency is restricted.

Q3: Upload file says "File too large"

The default maximum file limit is 10MB. To upload larger files, modify .env:

MAX_FILE_SIZE=20971520  # 20MB

Then restart the service: docker compose restart

Q4: Inaccurate receipt recognition

You can customize the system prompt in Settings → LLM to give the AI more context. For example, if you are in the catering industry, you can add:

You are a professional accountant in the catering industry, skilled at identifying receipt formats from various restaurants and snack bars.

Q5: How to change the login password

After logging in, click the avatar in the top right corner → Profile to change your password and email.

Q6: What if I forget the admin password?

You need to reset it via the database. Connect to the PostgreSQL container:

docker exec -it taxhacker-db-1 psql -U postgres -d taxhacker

Then execute:

UPDATE users SET password_hash = 'new_password_hash' WHERE email = 'admin@localhost';

9 Advanced Directions

After mastering the basics, you can explore these advanced features:

9.1 Custom AI Prompts

TaxHacker allows you to deeply customize AI behavior. Modify the system prompt in Settings → LLM to let the AI extract data according to your industry standards.

9.2 Multi-Project Management

Create different projects in Settings → Projects, such as "Project A" and "Project B". You can track income and expenses by project, which is perfect for freelancers with multiple business lines.

9.3 Automation with OpenClaw

If you also deploy OpenClaw, you can have it periodically call the TaxHacker API to automatically process unsorted receipts, achieving truly unattended bookkeeping.

9.4 Scheduled Auto-Backups

Use a cronjob to periodically call the backup API:

0 2 * * * curl -X POST http://localhost:7331/api/backups

Automatically create a backup every day at midnight.

Updated March 21, 2026