Ghostfolio

Open Source Wealth Management Software

Ghostfolio is an open source wealth management software built with web technology. The application empowers busy people to keep track of stocks, ETFs or cryptocurrencies and make solid, data-driven investment decisions. The software is designed for personal use in continuous operation.

Ghostfolio Premium

Our official Ghostfolio Premium cloud offering is the easiest way to get started. Due to the time it saves, this will be the best option for most people. Revenue is used to cover operational costs for the hosting infrastructure and professional data providers, and to fund ongoing development.

If you prefer to run Ghostfolio on your own infrastructure, please find further instructions in the Self-hosting section.

Why Ghostfolio?

Ghostfolio is for you if you are...

💼 trading stocks, ETFs or cryptocurrencies on multiple platforms
🏦 pursuing a buy & hold strategy
🎯 interested in getting insights of your portfolio composition
👻 valuing privacy and data ownership
🧘 into minimalism
🧺 caring about diversifying your financial resources
🆓 interested in financial independence
🙅 saying no to spreadsheets
😎 still reading this list

Features

✅ Create, update and delete transactions
✅ Multi account management
✅ Portfolio performance: Return on Average Investment (ROAI) for Today, WTD, MTD, YTD, 1Y, 5Y, Max
✅ Various charts
✅ Static analysis to identify potential risks in your portfolio
✅ Import and export transactions
✅ Dark Mode
✅ Zen Mode
✅ Progressive Web App (PWA) with a mobile-first design

Image of a phone showing the Ghostfolio app open

Technology Stack

Ghostfolio is a modern web application written in TypeScript and organized as an Nx workspace.

Backend

The backend is based on NestJS using PostgreSQL as a database together with Prisma and Redis for caching.

Frontend

The frontend is built with Angular and uses Angular Material with utility classes from Bootstrap.

Self-hosting

We provide official container images hosted on Docker Hub for linux/amd64, linux/arm/v7 and linux/arm64.

Supported Environment Variables

Name	Type	Default Value	Description
`ACCESS_TOKEN_SALT`	`string`		A random string used as salt for access tokens
`API_KEY_COINGECKO_DEMO`	`string` (optional)		The CoinGecko Demo API key
`API_KEY_COINGECKO_PRO`	`string` (optional)		The CoinGecko Pro API key
`DATABASE_URL`	`string`		The database connection URL, e.g. `postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@localhost:5432/${POSTGRES_DB}?sslmode=prefer`
`ENABLE_FEATURE_AUTH_TOKEN`	`boolean` (optional)	`true`	Enables authentication via security token
`HOST`	`string` (optional)	`0.0.0.0`	The host where the Ghostfolio application will run on
`JWT_SECRET_KEY`	`string`		A random string used for JSON Web Tokens (JWT)
`LOG_LEVELS`	`string[]` (optional)		The logging levels for the Ghostfolio application, e.g. `["debug","error","log","warn"]`
`PORT`	`number` (optional)	`3333`	The port where the Ghostfolio application will run on
`POSTGRES_DB`	`string`		The name of the PostgreSQL database
`POSTGRES_PASSWORD`	`string`		The password of the PostgreSQL database
`POSTGRES_USER`	`string`		The user of the PostgreSQL database
`REDIS_DB`	`number` (optional)	`0`	The database index of Redis
`REDIS_HOST`	`string`		The host where Redis is running
`REDIS_PASSWORD`	`string`		The password of Redis
`REDIS_PORT`	`number`		The port where Redis is running
`REQUEST_TIMEOUT`	`number` (optional)	`2000`	The timeout of network requests to data providers in milliseconds
`ROOT_URL`	`string` (optional)	`http://0.0.0.0:3333`	The root URL of the Ghostfolio application, used for generating callback URLs and external links.

OpenID Connect OIDC (Experimental)

Name	Type	Default Value	Description
`ENABLE_FEATURE_AUTH_OIDC`	`boolean` (optional)	`false`	Enables authentication via OpenID Connect
`OIDC_AUTHORIZATION_URL`	`string` (optional)		Manual override for the OIDC authorization endpoint (falls back to the discovery from the issuer)
`OIDC_CALLBACK_URL`	`string` (optional)	`${ROOT_URL}/api/auth/oidc/callback`	The OIDC callback URL
`OIDC_CLIENT_ID`	`string`		The OIDC client ID
`OIDC_CLIENT_SECRET`	`string`		The OIDC client secret
`OIDC_ISSUER`	`string`		The OIDC issuer URL, used to discover the OIDC configuration via `/.well-known/openid-configuration`
`OIDC_SCOPE`	`string[]` (optional)	`["openid"]`	The OIDC scope to request, e.g. `["email","openid","profile"]`
`OIDC_TOKEN_URL`	`string` (optional)		Manual override for the OIDC token endpoint (falls back to the discovery from the issuer)
`OIDC_USER_INFO_URL`	`string` (optional)		Manual override for the OIDC user info endpoint (falls back to the discovery from the issuer)

Run with Docker Compose

Prerequisites

Basic knowledge of Docker
Installation of Docker
Create a local copy of this Git repository (clone)
Copy the file .env.example to .env and populate it with your data (cp .env.example .env)

a. Run environment

Run the following command to start the Docker images from Docker Hub:

docker compose -f docker/docker-compose.yml up -d

b. Build and run environment

Run the following commands to build and start the Docker images:

docker compose -f docker/docker-compose.build.yml build
docker compose -f docker/docker-compose.build.yml up -d

Setup

Open http://localhost:3333 in your browser
Create a new user via Get Started (this first user will get the role ADMIN)

Upgrade Version

Update the Ghostfolio Docker image
- Increase the version of the ghostfolio/ghostfolio Docker image in docker/docker-compose.yml
- Run the following command if ghostfolio:latest is set:
```
docker compose -f docker/docker-compose.yml pull
```
Run the following command to start the new Docker image:
```
docker compose -f docker/docker-compose.yml up -d
```
The container will automatically apply any required database schema migrations during startup.

Home Server Systems (Community)

Ghostfolio is available for various home server systems, including CasaOS, Home Assistant, Runtipi, TrueCharts, Umbrel, and Unraid.

Development

For detailed information on the environment setup and development process, please refer to DEVELOPMENT.md.

Public API

Authorization: Bearer Token

Set the header for each request as follows:

"Authorization": "Bearer eyJh..."

You can get the Bearer Token via POST http://localhost:3333/api/v1/auth/anonymous (Body: { "accessToken": "<INSERT_SECURITY_TOKEN_OF_ACCOUNT>" })

Deprecated: GET http://localhost:3333/api/v1/auth/anonymous/<INSERT_SECURITY_TOKEN_OF_ACCOUNT> or curl -s http://localhost:3333/api/v1/auth/anonymous/<INSERT_SECURITY_TOKEN_OF_ACCOUNT>.

Health Check (experimental)

Request

GET http://localhost:3333/api/v1/health

Info: No Bearer Token is required for health check

Response

Success

200 OK

{
  "status": "OK"
}

Import Activities

Prerequisites

Bearer Token for authorization

Request

POST http://localhost:3333/api/v1/import

Body

{
  "activities": [
    {
      "currency": "USD",
      "dataSource": "YAHOO",
      "date": "2021-09-15T00:00:00.000Z",
      "fee": 19,
      "quantity": 5,
      "symbol": "MSFT",
      "type": "BUY",
      "unitPrice": 298.58
    }
  ]
}

Field	Type	Description
`accountId`	`string` (optional)	Id of the account
`comment`	`string` (optional)	Comment of the activity
`currency`	`string`	`CHF` \| `EUR` \| `USD` etc.
`dataSource`	`string`	`COINGECKO` \| `GHOSTFOLIO` ¹ \| `MANUAL` \| `YAHOO`
`date`	`string`	Date in the format `ISO-8601`
`fee`	`number`	Fee of the activity
`quantity`	`number`	Quantity of the activity
`symbol`	`string`	Symbol of the activity (suitable for `dataSource`)
`type`	`string`	`BUY` \| `DIVIDEND` \| `FEE` \| `INTEREST` \| `LIABILITY` \| `SELL`
`unitPrice`	`number`	Price per unit of the activity

Response

Success

201 Created

Error

400 Bad Request

{
  "error": "Bad Request",
  "message": [
    "activities.1 is a duplicate activity"
  ]
}

Portfolio (experimental)

Prerequisites

Grant access of type Public in the Access tab of My Ghostfolio.

Request

GET http://localhost:3333/api/v1/public/<INSERT_ACCESS_ID>/portfolio

Info: No Bearer Token is required for authorization

Response

Success

{
  "performance": {
    "1d": {
      "relativeChange": 0 // normalized from -1 to 1
    };
    "ytd": {
      "relativeChange": 0 // normalized from -1 to 1
    },
    "max": {
      "relativeChange": 0 // normalized from -1 to 1
    }
  }
}

Community Projects

Discover a variety of community projects for Ghostfolio: https://github.com/topics/ghostfolio

Are you building your own project? Add the ghostfolio topic to your GitHub repository to get listed as well. Learn more →

Contributing

Ghostfolio is 100% free and open source. We encourage and support an active and healthy community that accepts contributions from the public - including you.

Not sure what to work on? We have some ideas, even for newcomers. Please join the Ghostfolio Slack channel or post to @ghostfolio_ on X. We would love to hear from you.

If you like to support this project, become a Sponsor, get Ghostfolio Premium or Buy me a coffee.

Analytics

AI Agent — Ghostfolio Financial Assistant

Built by @Theesamkos as part of the Gauntlet AI AgentForge program.

AgentForge Bounty Submission

This project includes a production-grade implementation of a Unified Real Estate Ledger for Ghostfolio, submitted as a bounty contribution to the Gauntlet AI AgentForge program.

For graders and reviewers: Please see BOUNTY.md for the full submission writeup, including the problem statement, feature description, technical architecture, and impact.

What was built

Database: Two new Prisma models (RealEstateAsset, RentalIncomeRecord) with cascading deletes and indexed foreign keys
Backend: A complete RealEstateModule (NestJS) with 8 REST endpoints under /api/v1/real-estate, powered by the RentCast AVM API
AI Agent: 6 new async tool functions in Python (get_real_estate_summary, get_real_estate_holdings, add_property, update_property_valuation, get_rental_income_history, add_rental_income)

The agent can now answer: "What percentage of my net worth is real estate vs. equities?" — for the first time, with a real answer.

→ Read the full bounty submission: BOUNTY.md

→ Bounty Repository: github.com/Theesamkos/ghostfolio-bounty

Ghostfolio Agent Framework

AI-powered financial assistant built on the Ghostfolio open-source wealth management platform. It exposes a streaming chat API that reasons about your portfolio using a dual-LLM pipeline and a five-layer verification system.

Full architecture reference → docs/AGENT_ARCHITECTURE.md

Live Deployment

Service	URL
Backend API (Railway)	`https://ghostfolio-production-c6dd.up.railway.app`
Frontend (Vercel)	`https://ghostfolio-chi-sage.vercel.app`
API Docs (Swagger)	`https://ghostfolio-production-c6dd.up.railway.app/docs`
Health Check	`https://ghostfolio-production-c6dd.up.railway.app/health`

MVP Requirements Checklist

#	Requirement	Status
1	Agent responds to natural language queries in chosen domain (finance / portfolio management)	✅
2	At least 3 functional tools the agent can invoke	✅ 10+ tools (portfolio, performance, risk, market, transaction, execution, and more)
3	Tool calls execute successfully and return structured results	✅
4	Agent synthesises tool results into coherent, domain-specific responses	✅ Claude Sonnet 4.6 streaming synthesis
5	Conversation history maintained across turns	✅ Supabase-backed persistence (in-process fallback)
6	Basic error handling — graceful failure, not crashes	✅ Typed exception handlers for timeout, connection, and unexpected errors
7	At least one domain-specific verification check	✅ Five-layer verification (hallucination, rate limit, trade floor, sandbox, PII sanitisation)
8	Simple evaluation: 5+ test cases with expected outcomes	✅ 56 test cases across portfolio, transaction, and general categories
9	Deployed and publicly accessible	✅ Railway + Vercel (URLs above)

Debug View — Tool Call Verification

Every agent message that invokes a tool shows a collapsible "Show tool call" toggle in the chat UI. Clicking it expands a syntax-highlighted JSON panel displaying the exact tool name and parameters sent to the backend. This provides direct, per-message verification that tool calls are being made.

Features

Feature	Detail
Dual-LLM reasoning	Claude Sonnet 4.6 for synthesis · GPT-4o Mini for parameter normalisation
Streaming responses	Server-Sent Events (SSE) — token-by-token typewriter effect
Tool call debug view	Collapsible JSON panel in chat showing each tool invocation
Data visualisation	Interactive doughnut charts for portfolio allocation queries
Five-layer security	Hallucination check · rate limiting · trade floor · sandbox execution · PII sanitisation
Human-in-the-loop	Countdown confirmation modal before any trade is submitted
Conversation memory	Supabase-backed persistence; falls back to in-process store if unconfigured
Cost tracking	Per-call and cumulative token spend logged to LangSmith
React frontend	Vite + TypeScript · dark theme · syntax-highlighted code blocks

Evaluation Harness

The eval suite lives in evals/ and contains 56 test cases across three categories.

Test case breakdown

Category	Count	Eval methods
Portfolio	22	`keyword_match`, `json_schema_match`, `llm_as_judge`
Transaction	22	`keyword_match`, `json_schema_match`, `llm_as_judge`
General	12	`keyword_match`, `llm_as_judge`

Eval methods

Method	Description
`keyword_match`	All `response_contains` strings must appear in the response (case-insensitive)
`json_schema_match`	Stricter variant: symbols, numbers, and action words must all be present
`llm_as_judge`	Claude Sonnet 4.6 scores the response 0–1 against a human-written rubric; pass ≥ 0.70

Run the evals

# Install dependencies (from agent/)
pip install -r requirements.txt

# Run all 56 tests against the live Railway deployment
python3 evals/eval_runner.py \
    --agent-url https://ghostfolio-production-c6dd.up.railway.app

# Run against a local agent
python3 evals/eval_runner.py

# Only portfolio tests, save to a custom report path
python3 evals/eval_runner.py --category portfolio \
    --output results/portfolio_$(date +%Y%m%d).md

# Skip LangSmith tracing
python3 evals/eval_runner.py --no-langsmith

The runner produces a Markdown evaluation report at evals/evaluation_report.md (overridable with --output).

Test cases file

evals/test_cases.json — 56 structured test cases, each with:

id — unique identifier (e.g. P-001, T-012, G-005)
category — portfolio | transaction | general
description — human-readable test name
input — the natural-language query sent to the agent
eval_method — one of the three methods above
expected_output — response_contains keywords or judge_criteria rubric

LangSmith integration

Set LANGSMITH_API_KEY and LANGSMITH_PROJECT to have each eval run recorded as an individual trace with pass/fail feedback scores in LangSmith.

Quick Start

Prerequisites

Python 3.11+
Node 18+ (frontend)
A running Ghostfolio instance (or use the demo fallback)

1. Clone and install (Python)

git clone https://github.com/Theesamkos/ghostfolio
cd ghostfolio/agent

python3 -m venv .venv
source .venv/bin/activate

pip install -r requirements.txt

2. Configure environment

cp ../.env.example .env

Required variables:

# LLMs
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...

# Ghostfolio API
GHOSTFOLIO_API_URL=http://localhost:3333
GHOSTFOLIO_SECRET_TOKEN=your-ghostfolio-secret-token

# Optional: LangSmith tracing
LANGSMITH_API_KEY=ls-...
LANGSMITH_PROJECT=ghostfolio-agent

# Optional: Supabase persistent memory
SUPABASE_URL=https://xyz.supabase.co
SUPABASE_ANON_KEY=eyJ...

# Optional: Redis rate limiting (falls back to in-memory if unset)
REDIS_URL=redis://localhost:6379

3. Start the backend

uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload

The API is now available at http://localhost:8000. Interactive docs: http://localhost:8000/docs.

4. Start the frontend

cd frontend
npm install
npm run dev

Open http://localhost:5173 in your browser.

Supabase Persistent Memory (optional)

By default the agent uses an in-process conversation store that resets on restart. To enable cross-restart, cross-instance persistence:

Open your Supabase project → SQL Editor and run the migration:
```
# File: agent/migrations/001_create_conversations.sql
```

Set two environment variables in Railway (or your .env):

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=eyJ...

Redeploy — the backend will auto-detect the variables and switch to SupabaseMemory.

If either variable is absent the server falls back to ConversationMemory silently.

Docker

# From the repo root
docker compose up agent

The Dockerfile in this directory builds the FastAPI backend. The frontend is served separately by Vite (dev) or Nginx (prod).

Project Structure

agent/
├── src/
│   ├── main.py          # FastAPI app — SSE streaming endpoint
│   ├── agent.py         # Dual-LLM pipeline + streaming generator
│   ├── llm.py           # Anthropic / OpenAI client initialisation
│   ├── memory.py        # ConversationMemory + SupabaseMemory backends
│   ├── cost_tracker.py  # Token spend tracking + LangSmith integration
│   └── verification.py  # Five-layer verification system
├── tools/
│   ├── portfolio.py     # Portfolio analysis + chart data generation
│   ├── performance.py   # Returns, benchmark comparison
│   ├── risk.py          # Volatility, Sharpe ratio, VaR
│   ├── market.py        # Live market data
│   ├── transaction.py   # Transaction history
│   └── execution.py     # Trade execution (HITL gated)
├── migrations/
│   └── 001_create_conversations.sql   # Supabase schema migration
├── frontend/            # React + Vite + TypeScript chat UI
│   └── src/
│       └── components/
│           ├── ChatInterface.tsx           # SSE streaming fetch + state
│           ├── Message.tsx                # Markdown + chart + debug view
│           ├── TradeConfirmationModal.tsx
│           └── charts/
│               └── PieChart.tsx           # Chart.js doughnut component
├── evals/               # Evaluation harness (56 test cases)
│   ├── eval_runner.py   # Runner — SSE stream, 3 eval methods, MD report
│   └── test_cases.json  # 56 test cases (portfolio / transaction / general)
├── tests/               # Pytest unit tests
├── requirements.txt
├── setup.py
└── Dockerfile

API Reference

`POST /agent/query`

Streams the agent's response as Server-Sent Events.

Request body

{
  "message": "What is my portfolio allocation?",
  "session_id": "abc-123"
}

SSE event stream

data: {"type": "token", "content": "Your "}
data: {"type": "token", "content": "portfolio "}
data: {"type": "tool_call", "tool_name": "get_portfolio_allocation", "parameters": {"currency": "USD"}}
...
data: {"type": "done", "session_id": "abc-123", "trade_preview": null}

Event type	Fields	Description
`token`	`content: str`	Incremental response chunk
`tool_call`	`tool_name: str`, `parameters: object`	Tool invocation details (shown in debug panel)
`done`	`session_id`, `trade_preview`	Stream complete; trade preview present if a trade was prepared

`GET /health`

Returns server status with a UTC timestamp:

{"status": "ok", "timestamp": "2025-01-15T12:34:56.789012+00:00"}

`GET /agent/history/{session_id}`

Returns the conversation history for a session.

`POST /agent/reset`

Clears the history for a session.

`GET /docs`

Swagger UI for all endpoints.

Five-Layer Verification System

Every agent response passes through five gates before tokens reach the client:

Hallucination detection — cross-checks tool output against response text
Rate limiting — per-session request throttling (Redis-backed, in-memory fallback)
Trade floor enforcement — rejects orders below configurable minimum value
Sandbox execution — tool calls run in a restricted async context
Output sanitisation — strips PII patterns before streaming

See docs/AGENT_ARCHITECTURE.md for full details.

Data Visualisation

When you ask about portfolio allocation, the agent automatically embeds a Chart.js-compatible JSON block in its response. The frontend (Message.tsx) detects ```chart code fences and renders them as interactive doughnut charts via PieChart.tsx.

Example query: "Show me my portfolio allocation"

Running Tests

# Unit tests
pytest tests/ -v

# Evaluation harness — all 56 cases against local agent
python3 evals/eval_runner.py

# Evaluation harness — all 56 cases against Railway deployment
python3 evals/eval_runner.py \
    --agent-url https://ghostfolio-production-c6dd.up.railway.app

Architecture Overview

User message
     │
     ▼
┌─────────────────────────────────────────┐
│          FastAPI  /agent/query          │
│         (SSE StreamingResponse)         │
└──────────────────┬──────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────┐
│           Five-Layer Verification        │
└──────────────────┬──────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────┐
│       Step 1 — Claude Sonnet 4.6        │
│   Reason · Select tool · Build params   │
└──────────────────┬──────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────┐
│       Step 2 — GPT-4o Mini              │
│   Normalise & validate tool params      │
└──────────────────┬──────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────┐
│       Step 3 — Tool Execution           │
│   portfolio / performance / risk / ...  │
│   ↳ emits tool_call SSE event           │
└──────────────────┬──────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────┐
│       Step 4 — Claude Sonnet 4.6        │
│   Synthesise · Stream tokens to client  │
└──────────────────┬──────────────────────┘
                   │
            token events ──► browser
            tool_call event ► debug panel
            done  event  ──► browser

Full diagram with HITL trade flow → docs/AGENT_ARCHITECTURE.md.

Contributing

Fork the repo and create a feature branch
Run pytest tests/ -v to verify existing tests pass
Add tests for new behaviour in tests/
Open a pull request against main

License

MIT — see LICENSE in the repository root.

License

Licensed under the AGPLv3 License.

Available with Ghostfolio Premium. ↩

Name		Name	Last commit message	Last commit date
Latest commit History 4,646 Commits
.agent/skills		.agent/skills
.agents/skills		.agents/skills
.claude		.claude
.config		.config
.github		.github
.husky		.husky
.vercel		.vercel
.vscode		.vscode
agent		agent
apps		apps
docker		docker
docs		docs
libs		libs
prisma		prisma
test/import		test/import
tools		tools
.editorconfig		.editorconfig
.env.dev		.env.dev
.env.example		.env.example
.gitignore		.gitignore
.nvmrc		.nvmrc
.prettierignore		.prettierignore
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
DEVELOPMENT.md		DEVELOPMENT.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
chat.html		chat.html
eslint.config.cjs		eslint.config.cjs
jest.config.ts		jest.config.ts
jest.preset.js		jest.preset.js
nx.json		nx.json
package-lock.json		package-lock.json
package.json		package.json
replace.build.mjs		replace.build.mjs
skills-lock.json		skills-lock.json
tsconfig.base.json		tsconfig.base.json

Folders and files

Latest commit

History

Repository files navigation

Ghostfolio

Ghostfolio Premium

Why Ghostfolio?

Features

Technology Stack

Backend

Frontend

Self-hosting

Supported Environment Variables

OpenID Connect OIDC (Experimental)

Run with Docker Compose

Prerequisites

a. Run environment

b. Build and run environment

Setup

Upgrade Version

Home Server Systems (Community)

Development

Public API

Authorization: Bearer Token

Health Check (experimental)

Request

Response

Success

Import Activities

Prerequisites

Request

Body

Response

Success

Error

Portfolio (experimental)

Prerequisites

Request

Response

Success

Community Projects

Contributing

Sponsors

Analytics

AI Agent — Ghostfolio Financial Assistant

AgentForge Bounty Submission

What was built

Ghostfolio Agent Framework

Live Deployment

MVP Requirements Checklist

Debug View — Tool Call Verification

Features

Evaluation Harness

Test case breakdown

Eval methods

Run the evals

Test cases file

LangSmith integration

Quick Start

Prerequisites

1. Clone and install (Python)

2. Configure environment

3. Start the backend

4. Start the frontend

Supabase Persistent Memory (optional)

Docker

Project Structure

API Reference

POST /agent/query

GET /health

GET /agent/history/{session_id}

POST /agent/reset

GET /docs

Five-Layer Verification System

Data Visualisation

Running Tests

Architecture Overview

Contributing

License

License

`POST /agent/query`

`GET /health`

`GET /agent/history/{session_id}`

`POST /agent/reset`

`GET /docs`

Packages