AgentForge

AgentForge is a production-ready AI finance agent layered on top of Ghostfolio. It adds a conversational AI assistant (powered by LangChain + Claude/GPT-4o) that can answer questions about your portfolio, surface insights, flag risks, and execute read operations — all from a floating chat widget embedded in the Ghostfolio UI.

• Floating chat widget on every page — no separate route
• POST /api/v1/chat — conversational interface to your portfolio
• GET /api/v1/tools — lists available agent tools
• GET /api/v1/insights — proactive portfolio insights
• POST /api/v1/evals/run — LangSmith eval runner
• LLM routing: GPT-4o-mini (simple) · Claude Sonnet (complex)
• Conversation state via Redis · Insights persisted in SQLite

The entire stack runs in Docker. Requires Docker and Node.js 22+.

git clone https://github.com/jsquire4/gf-AgentForge.git && cd gf-AgentForge
npm install
npm run setup

npm run setup walks you through everything interactively: creates .env with generated secrets, prompts for your OpenAI API key (and optional LangSmith key), starts Docker (Postgres, Redis, Ghostfolio), waits for health checks, runs database migrations and seeding, creates an eval user with a demo portfolio (AAPL, GOOGL, MSFT, AMZN, VTI, BND, VXUS), and builds the agent.

After setup completes, start the agent:

npm run start:agent

# 1. Clone and install
git clone https://github.com/jsquire4/gf-AgentForge.git && cd gf-AgentForge
npm install
cp .env.example .env

Edit .env and fill in the required values:

Important: The default DATABASE_URL in .env.example uses @postgres:5432 (the Docker service hostname). This works for containers but not for host commands like npm run database:setup. Update it to @localhost:5432 for running setup commands from your machine:

DATABASE_URL=postgresql://user:YOUR_PASSWORD@localhost:5432/ghostfolio-db?connect_timeout=300&sslmode=prefer

# 2. Start infrastructure (Postgres, Redis, Ghostfolio)
docker compose -f docker/docker-compose.yml up -d

# 3. Wait for Ghostfolio to be healthy (~30s)
until curl -sf http://localhost:3333/api/v1/health > /dev/null; do sleep 5; done

# 4. Seed the database and create an eval user with demo portfolio
npm run database:setup
npm run eval:seed        # creates eval user, writes GHOSTFOLIO_API_TOKEN to .env

# 5. Build and start the agent
npm run build:agent
npm run start:agent

Once both Ghostfolio and the agent are running:

# Verify the agent is up and tools are registered
curl http://localhost:8000/api/v1/health
curl http://localhost:8000/api/v1/tools

# Chat with the agent
curl -X POST http://localhost:8000/api/v1/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-jwt>" \
  -d '{"message": "How is my portfolio doing?"}'

# Validate setup (checks all services, env vars, build artifacts)
npm run eval:setup

# Run golden evals to validate the full pipeline
npm run eval:golden

The agent ships with 6 tools that cover portfolio analysis, market data, compliance, and regulatory guidance:

Tools are registered via a single barrel export (tools/tools.exports.ts) and auto-discovered by the system prompt builder at runtime.

# Build agent
npm run build:agent

# Test agent
npm run test:agent

# Smoke-test chat round-trip
./scripts/test-chat.sh "What is my portfolio performance?"

Every agent request is traced end-to-end via LangSmith. Traces include the full reasoning chain (input, tool calls, LLM reasoning, output) plus structured metadata for filtering.

Setup: Provide your LangSmith API key during npm run setup, or set these in .env manually:

LANGSMITH_API_KEY=lsv2_pt_...
LANGSMITH_PROJECT=ghostfolio-agent
LANGCHAIN_TRACING_V2=true
LANGCHAIN_CALLBACKS_BACKGROUND=true

What's traced:

Eval runs automatically tag traces with eval + the case ID, so you can filter eval traces from production in the LangSmith dashboard. Each request's langsmithRunId is also stored in the local metrics SQLite database for cross-referencing.

Two-tier eval system for validating agent behavior. Both tiers send prompts through the full agent loop (LLM + real Ghostfolio API). See evals/dataset/ for all eval cases.

Both eval tiers require the full stack running (Ghostfolio + Agent) and a seeded user with portfolio data:

# 1. Copy environment and add your keys
cp .env.example .env
# Edit .env → set OPENAI_API_KEY (required) + LANGSMITH_API_KEY (optional, for traces)

# 2. Start infrastructure
docker compose -f docker/docker-compose.yml up -d
npm run database:setup    # creates tables + system tags

# 3. Seed eval user + demo portfolio (auto-writes GHOSTFOLIO_API_TOKEN to .env)
npm run eval:seed

# 4. Start the agent
npm run start:agent

# 5. Run evals
npm run eval:golden

npm run eval:seed creates a Ghostfolio user, imports demo holdings (AAPL, GOOGL, MSFT, AMZN, VTI), and writes the GHOSTFOLIO_API_TOKEN to .env automatically. The eval runner exchanges this token for a real JWT at runtime so tool calls authenticate as a real user. If the token is already valid, the seed is skipped.

# Run golden evals (known-answer, deterministic assertions)
npm run eval:golden

# Run labeled evals (routing + quality)
npm run eval:labeled

# Filter labeled evals by difficulty
npm run eval:labeled -- --difficulty straightforward
npm run eval:labeled -- --difficulty edge

# Run all evals
npm run eval

# Check every tool has eval coverage
npm run eval:coverage

# Validate setup before running evals
npm run eval:setup

Regular users don't need any .env configuration. The Angular client handles authentication automatically — when you log into Ghostfolio, your JWT is stored in the browser and the AuthInterceptor attaches it to all requests, including those to the agent. The agent forwards the JWT to Ghostfolio's API for tool calls. No manual token management needed.

Eval dataset format: Each tool gets two JSON files — one in evals/dataset/golden/ (known-answer tool tests) and one in evals/dataset/labeled/ (routing tests with straightforward/ambiguous/edge cases). See evals/types.ts for the full schema.

Adding evals for a new tool: Drop two files (<tool-name>.eval.json) into golden/ and labeled/ — both runners auto-discover via glob.

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.

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)

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.