Ghostfolio Agent is a portfolio-analysis assistant built around typed tools and response checks. It can summarize holdings, assess concentration risk, retrieve market data, categorize transactions, and run compliance rules. The repository contains a FastAPI service and a React application.
The previous Railway deployment has been removed. Follow the deployment guide to create a new instance.
- Seven LangChain tools for portfolio analysis, risk, market data, transaction categorization, compliance, price history, and cryptocurrency trends
- A verification pipeline with confidence scores, constraint checks, fact checks, and escalation signals
- Evaluation cases for normal, edge, and adversarial requests
- Session history, usage tracking, feedback records, and optional LangSmith traces
- A React interface for portfolio chat, repository analysis, tool management, evaluations, and cost review
React application
|
| /api/*
v
FastAPI service
|
+-- Ghostfolio client
+-- market-data clients
+-- LangGraph agent and tools
+-- verification and evaluations
The frontend sends /api/* requests to Nginx. Nginx reads BACKEND_URL when the container starts and proxies those requests to FastAPI.
Requirements: Docker and Docker Compose.
cp .env.example .envSet OPENAI_API_KEY and a random API_ACCESS_TOKEN of at least 32 characters in .env.
Generate the owner token with python -c "import secrets; print(secrets.token_urlsafe(32))".
Enter that token in the frontend sign-in form. Leave USE_MOCK_DATA=true if you do not have a Ghostfolio instance.
This application supports one trusted owner per deployment. All private API routes
(including documentation and administrative operations) require Authorization: Bearer <API_ACCESS_TOKEN>.
Only /health and CORS preflight are public; an unconfigured token returns 503 on protected routes.
Do not share the owner token between unrelated users. Run one backend worker; request limits and
session serialization are process-local. Multi-user or multi-worker deployments require a shared
authorization, rate-limit, and persistence layer.
docker compose up --buildOpen:
- React application:
http://localhost:3000 - FastAPI documentation:
http://localhost:8000/docs - Backend health check:
http://localhost:8000/health
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
uvicorn src.api.routes:app --reload --port 8002On Windows, activate the environment with .venv\Scripts\activate.
Configure .env and the owner token as described above before using the API or frontend.
cd frontend
npm ci
npm run devOpen http://localhost:5173. Vite proxies /api to http://localhost:8002.
Set these variables in .env:
USE_MOCK_DATA=false
GHOSTFOLIO_API_URL=http://localhost:3333
GHOSTFOLIO_ACCESS_TOKEN=replace_with_your_tokenCreate the access token in Ghostfolio under Settings > Security. Keep the token on the backend. Do not put it in the React application or commit it to Git.
| Route | Purpose |
|---|---|
GET /health |
Service and dependency status |
POST /chat |
Run an agent request |
GET /portfolio |
Portfolio summary |
GET /portfolio/risk |
Concentration and risk analysis |
GET /market/{symbol} |
Market-data lookup |
GET /tools |
Available tools |
POST /evals/run |
Run evaluation cases |
GET /traces |
Stored trace records |
See the interactive FastAPI documentation at /docs for the full API.
The outcome evaluation harness adds versioned synthetic financial scenarios, mutation-tested graders, and reproducible paired experiments:
python -m evals.benchmark --repetitions 5 --require-candidate-pass --fail-on-regressionThe default comparison is explicitly an offline policy demonstration. Real model
comparisons require configured model identifiers and --allow-paid. Reports keep
per-scenario outcomes, errors, traces, uncertainty, source/data hashes, and unknown
costs distinct.
See the recorded offline comparison
for a complete example with per-scenario results and failure evidence.
The real-model comparison notes include
observed OpenRouter free-model runs, the issues they uncovered, and the final
repeated baseline/candidate results. The comparison reports distinguish verified
financial outcomes from optional-output adherence and preserve original failures.
Backend:
python -m pytest -q
python -m ruff check src tests --select E9,F63,F7,F82Frontend:
cd frontend
npm ci
npm audit --omit=dev --audit-level=high
npm run lint
npm test
npm run buildThe CI workflow runs these checks and builds both Docker images.
| Variable | Required | Purpose |
|---|---|---|
OPENAI_API_KEY |
Yes | Model requests |
USE_MOCK_DATA |
No | Use local sample portfolio data |
GHOSTFOLIO_API_URL |
For live data | Ghostfolio server URL |
GHOSTFOLIO_ACCESS_TOKEN |
For live data | Server-side Ghostfolio token |
LANGSMITH_API_KEY |
No | LangSmith traces |
COINGECKO_API_KEY |
No | Higher CoinGecko rate limits |
API_ACCESS_TOKEN |
Yes | Random single-owner bearer token, at least 32 characters |
REPO_ALLOWED_ROOTS |
No | Allowed local repository roots; empty disables local attachment |
GENERATED_TOOL_EXECUTION_ENABLED |
No | Opt into isolated Docker tool execution; default false |
CORS_ORIGINS |
Production | Comma-separated frontend origins |
BACKEND_URL |
Frontend container | FastAPI URL used by Nginx |
The complete list and local defaults are in .env.example.
Live market-data failures return explicit errors; synthetic data is only available in
mock mode and is labeled is_mock. Verification confidence is heuristic and is null
when scoring is disabled. Disabling human review preserves detected warnings but
does not request escalation. Evaluation requests return completed after finishing,
and unmeasured hallucination rates remain null.
Local repository reads reject hidden/secret files, symlinks, path escapes, and oversized files even inside allowed roots. Generated Python is never imported into the API process. See the security and verification changes for sandbox setup and regression coverage.
See docs/DEPLOYMENT.md for the two-service Railway configuration and post-deployment checks.
MIT. See LICENSE.