🤖 AI Agent Integration

This fork includes an AI Portfolio Assistant powered by Claude + LangGraph. See AGENT_README.md for setup, demo, and architecture.

---

Ghostfolio

Open Source Wealth Management Software

Ghostfol.io | Live Demo | Ghostfolio Premium | FAQ | Blog | LinkedIn | Slack | X

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

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

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

Upgrade Version

1. 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
     

2. 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 1 | 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
    }
  }
}

🏠 Real Estate / Housing Integration (AgentForge)

This project extends the Ghostfolio AI Agent with a Housing & Real Estate capability — an example of brownfield AgentForge integration where a new tool is added to an existing LangGraph agent without touching core portfolio functionality.

Feature Flag

The feature is off by default and must be explicitly enabled:

# agent/.env
ENABLE_REAL_ESTATE=true    # activate
ENABLE_REAL_ESTATE=false   # deactivate (default) — zero behavior change

When false, all real estate keywords are ignored and the agent behaves exactly as it did before this feature was added.

What it adds

Three new agent capabilities accessible through the existing AI chat interface:

Capability	Example prompt
Neighborhood snapshot	"What's the housing market like in Austin?"
Listing search	"Show me listings in Seattle"
Neighborhood comparison	"Compare Austin vs Denver for affordability and rental yield"
Cashflow analysis	"Estimate rental cashflow for Chicago real estate"

2-Minute Demo (Friday)

Step 1 — start the agent (if not already running):

cd ghostfolio/agent
source venv/bin/activate
uvicorn main:app --reload --port 8000

Step 2 — confirm the flag is on: Open agent/.env and verify ENABLE_REAL_ESTATE=true.

Step 3 — open the AI chat in the Ghostfolio app (the floating chat FAB button).

Step 4 — run these demo prompts in order:

1. "What's the housing market like in Austin?"
   → Shows: median price, price/sqft, DOM, YoY change, inventory, rental yield

2. "Show me listings in Seattle"
   → Shows: 2 active listings with price, beds/baths, sqft, cap rate

3. "Compare Austin vs Chicago for real estate investment"
   → Shows: side-by-side metrics + which market wins on affordability, yield, walkability

4. "Estimate rental cashflow for a Chicago investment property"
   → Agent synthesizes cap rate, rent estimate, and mortgage estimate

Expected output: Conversational responses with specific data points, no raw JSON, citations included.

Architecture (how it integrates)

graph.py  classify_node  ──► detects real estate keywords
                         ──► routes to query_type = real_estate_snapshot | real_estate_search | real_estate_compare

graph.py  tools_node     ──► calls tools/real_estate.py functions
                             (get_neighborhood_snapshot / search_listings / compare_neighborhoods)

tools/real_estate.py     ──► MockProvider with realistic 2024 data for 10 US cities
                             TTL cache (5 min) to avoid repeat computation
                             Feature flag guard on every function

tools/__init__.py        ──► 3 new entries in TOOL_REGISTRY (append-only)

Critical paths untouched: state.py, main.py endpoints, existing tool files, Angular routes, Ghostfolio NestJS API — none of these files were modified.

Running the tests

cd ghostfolio/agent
source venv/bin/activate
python -m pytest evals/test_real_estate.py -v
# → 5 passed in < 1s

Rollback

1. Instant off: Set ENABLE_REAL_ESTATE=false in .env → restart agent. Zero UI or behavior change.
2. Full revert: git checkout main — removes all real estate code.
3. Partial revert: git revert the specific commits tagged feat(real-estate).

Supported Cities (Mock Provider)

Austin TX · San Francisco CA · New York NY · Denver CO · Seattle WA · Miami FL · Chicago IL · Phoenix AZ · Nashville TN · Dallas TX

Next Steps (real provider)

To swap in live data, replace MockProvider calls in tools/real_estate.py with an HTTP call to:

• Attom Data API (comprehensive, paid) — REAL_ESTATE_API_KEY env var
• RealtyMole / Realty in US (RapidAPI) — free tier available
• HUD Fair Market Rents API (free, government data, rent estimates)

The normalized return schema is identical — no changes to graph.py needed.

---

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.

Sponsors

Analytics

License

© 2021 - 2026 Ghostfolio

Licensed under the AGPLv3 License.

---

1. Available with Ghostfolio Premium. ↩︎