TaxHacker Documentation

TaxHacker is a self-hosted AI-powered accounting application designed for freelancers, indie-hackers, and small businesses. It automates expense and income tracking by using AI to analyze photos, invoices, and PDFs to extract structured data like product names, amounts, dates, and merchants.

Key capabilities include:

• AI Data Extraction: Automatically recognizes and categorizes transactions.
• Multi-currency Support: Automatic conversion for 170+ world currencies and 14 cryptocurrencies using historical exchange rates.
• Customization: Users can define custom categories, projects, and fields, and even write custom LLM prompts (including system prompts) for specific extraction needs.
• Data Portability: Flexible filtering and CSV export capabilities.
• Privacy: Designed for self-hosting to ensure complete ownership of financial data.

Scheduled tasks run in a shared cron container. If BETTER_AUTH_SECRET is not provided in the environment, the container reads the persisted secret from ./data/.better_auth_secret to ensure the app and cron containers share the same encryption key for passwords.

# docker-compose.yml
cron:
  image: ghcr.io/vas3k/taxhacker:latest
  volumes:
    - ./data:/app/data
    - ./etc/crontab:/mnt/crontab:ro
  environment:
    - DATABASE_URL=postgresql://...
    # Optional override. If unset, the container reads the persisted secret from ./data/.better_auth_secret.
    - BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET:-}
  command: ["docker-cron-entrypoint.sh"]

If you are running TaxHacker in self-hosted mode (SELF_HOSTED_MODE=true), the built-in authentication system is disabled. To expose your instance to the internet while still using TaxHacker's built-in login system, you must use a workaround that involves running in 'cloud mode' but manually managing users via the database.

⚠️ Warning: This is a security workaround. Use with caution. For production, use a reverse proxy with proper authentication or the official cloud version.

To monitor incoming emails for attachments, add an email server via the TaxHacker UI:

1. Navigate to Apps → Email Server Monitor.
2. Click "Add Server".
3. Select your provider (Gmail, Outlook, etc.) or choose "Custom IMAP".
4. Enter your email and App Password (not your regular password).
5. Set a Sync frequency (ranging from 15 minutes to daily).
6. Define allowed file extensions (default: .pdf, .jpg, .jpeg, .png).

To develop locally, you need Next.js 15+, Prisma, PostgreSQL 17+, and Ghostscript/GraphicsMagick (for PDF processing).

Follow these steps to initialize your environment:

1. Clone the repository.
2. Install dependencies via npm install.
3. Copy .env.example to .env and configure your DATABASE_URL.
4. Run Prisma commands to generate the client and migrate the database.
5. Start the development server.

# Clone the repository
git clone https://github.com/vas3k/TaxHacker.git
cd TaxHacker

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env

# Edit .env with your configuration
# Make sure to set DATABASE_URL to your PostgreSQL connection string
# Example: postgresql://user@localhost:5432/taxhacker

# Initialize the database
npx prisma generate && npx prisma migrate dev

# Start the development server
npm run dev

Since signup is disabled, you must manually insert a user into the users table using psql. Replace the email and ID as needed.

docker exec -it postgres psql -U postgres -d taxhacker -c "INSERT INTO users (id, email, name, membership_plan, is_email_verified, updated_at) VALUES ('6f5b4f8e-6f7a-4c3d-9b8b-7f2d2d61a9c3','mail@example.com','Owner','unlimited', true, now());"

After creating a user, go to the TaxHacker login page in your browser, enter the user's email, and click Sign In. To complete the login, retrieve the One-Time Password (OTP) from the verification table using this command:

docker exec -it postgres psql -U postgres -d taxhacker -c "SELECT value FROM verification ORDER BY created_at DESC LIMIT 1;"

The simplest way to self-host TaxHacker is using Docker Compose. This setup includes the TaxHacker application container and a PostgreSQL 17+ database with automatic migrations and persistent volume mounts.

To deploy, download the docker-compose.yml and run it with docker compose up.

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

docker compose up

To enable the public access workaround, run TaxHacker with the following environment variables. This configuration enables the authentication system (SELF_HOSTED_MODE=false) but prevents new public registrations (DISABLE_SIGNUP=true).

SELF_HOSTED_MODE=false
DISABLE_SIGNUP=true
BASE_URL=<URL you'll use to access TaxHacker>

When moving from development to production, use the build and start commands instead of npm run dev.

# Build the application
npm run build

# Start the production server
npm run start