Ghostfolio + AI Finance Agent

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.

This fork extends Ghostfolio with a domain-specific AI agent for natural language financial queries. Built for the Gauntlet AI AgentForge project (Week 2).

Deployed at: https://ghostfolio-production-72a0.up.railway.app/

Users can ask natural language questions about their financial data and receive coherent, data-driven responses. The agent retrieves real portfolio data, market prices, and benchmarks — then synthesizes them into actionable insights.

Example queries:

• "What's in my portfolio?"
• "What's the current price of AAPL and MSFT?"
• "How does my portfolio compare to the S&P 500?"

• Ticker Symbol Validation — Post-response check that prevents the LLM from hallucinating fake ticker symbols by cross-referencing mentioned symbols against actual tool output data.

7 test cases covering happy paths, edge cases, safety boundaries, and multi-tool coordination. Run with:

npm run test:single -- apps/api/src/app/endpoints/agent/agent.eval.spec.ts

POST /api/v1/agent/chat
Authorization: Bearer <JWT>
Content-Type: application/json

{
  "message": "What's in my portfolio?",
  "conversationId": "optional-uuid-for-multi-turn"
}

The AI agent includes a built-in chat interface. You must be logged in to access it.

Note: The /en/ prefix is the locale segment (English). It is required — navigating to just /ai-agent will not work. Replace en with another locale code (e.g., de, fr) if running in a different language.

The chat page is an authenticated route. Log in first (via Get Started or the demo account if configured), then navigate to the URL above.

After logging in, you can reach the AI Agent directly from the home overview page:

• Populated portfolio (users with activities) — An "Ask the AI Agent" card appears below the performance metrics. It links directly to the chat page.
• Empty portfolio (welcome screen) — A 4th item in the onboarding checklist: "Talk to the AI Agent" with the description "Get personalized insights and ask questions about your investments."

Both entry points are guarded by the accessAgentChat permission and appear for users with ADMIN, USER, and DEMO roles.

Once you're on the chat page, you can ask the agent natural language questions. Here are examples organized by category:

• "What's in my portfolio?"
• "Show me my holdings"
• "How is my portfolio diversified?"
• "What's my performance this year?"
• "How much am I up or down?"
• "Tell me about my accounts"
• "What's my total net worth?"

You can also specify a time range: 1d, wtd, mtd, ytd, 1y, 5y, or max.

• "What's the price of AAPL?"
• "Show me prices for MSFT, GOOGL, and NVDA" (up to 10 symbols at once)
• "What's Bitcoin trading at?"
• "Is the market open?"

• "What benchmarks are available?"
• "How does my portfolio compare to the S&P 500?"
• "Am I beating the market?"
• "Compare my returns to Bitcoin over the last 5 years"

The agent can chain tools together in a single query:

• "Show me my AAPL holding and its current market price"
• "What percentage of my portfolio is in tech, and how has it performed vs the S&P 500?"

• Execute trades or modify your portfolio
• Give specific financial advice ("Should I buy X?")
• Make price predictions ("Will BTC hit $100k?")
• Answer non-financial questions (medical, legal, etc.)

All responses include a disclaimer that the information is for educational purposes only and is not financial advice.

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.

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

• ✅ 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

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

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

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

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

• 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)

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

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

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

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

Demo mode allows visitors to explore Ghostfolio with sample data without creating an account. When configured, a Live Demo button appears on the landing page.

Demo mode is configured via the Property table in the database (key-value store), not via environment variables. You need to set two properties:

Steps to enable demo mode:

1. Create a regular user account (this will be the demo user)
2. Add some sample activities to the demo user's portfolio
3. Insert the two properties into the database:

   INSERT INTO "Property" ("key", "value") VALUES ('DEMO_USER_ID', '"<USER_UUID>"');
   INSERT INTO "Property" ("key", "value") VALUES ('DEMO_ACCOUNT_ID', '"<ACCOUNT_UUID>"');

   Note: The value must be a JSON string (wrapped in double quotes inside single quotes).
4. Optionally, tag activities with the built-in demo tag (ID: efa08cb3-9b9d-4974-ac68-db13a19c4874) and use the admin Sync Demo User Account action to refresh demo data

Once configured, the /api/v1/info endpoint will return a demoAuthToken, and the frontend landing page will show the demo access option. Visiting /demo will automatically sign in the visitor as the demo user in read-only mode.

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.

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

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

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

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

Info: No Bearer Token is required for health check

200 OK

{
  "status": "OK"
}

Bearer Token for authorization

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

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

201 Created

400 Bad Request

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

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

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

Info: No Bearer Token is required for authorization

{
  "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
    }
  }
}

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 →

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.

© 2021 - 2026 Ghostfolio

Licensed under the AGPLv3 License.