# Project pack: Ghostfolio @ f144c72

Facts about **Ghostfolio** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> Ghostfolio tracks your investments. Add what you buy and sell across different brokers and accounts, and it shows how your portfolio is doing, what it is made of and where the risks are. It suits people who invest for the long term and want a clear picture without spreadsheets. You can run it on your own computer or server, or pay for the official hosted version.

## Version and source
- Repository: https://github.com/ghostfolio/ghostfolio
- Pinned commit: `f144c723f471ef04d4b4c1e2571db428b53dfbc3`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/ghostfolio/ghostfolio/archive/f144c723f471ef04d4b4c1e2571db428b53dfbc3.zip
- Official docs: https://ghostfol.io/en/faq
- Live demo: https://ghostfol.io/en/demo. Official live demo with an example portfolio, read-only. No login needed.
- Licence: **AGPL-3.0-only**. Free to use and change. If you run a changed version that other people use over the internet (not just you or your household), you must offer them your source code under the same licence. Private use has no extra obligations.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/ghostfolio/ghostfolio bespoke-ghostfolio
  cd bespoke-ghostfolio
  git checkout --detach f144c723f471ef04d4b4c1e2571db428b53dfbc3
  # Prepare development requirements and local configuration first.
  # Setup notes: then in another terminal: npm run start:client (https://localhost:4200/en)
  cp .env.dev .env && npm install && docker compose -f docker/docker-compose.dev.yml up -d && npm run database:setup && npm run start:server
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  git clone https://github.com/ghostfolio/ghostfolio && cd ghostfolio
  cp .env.example .env
  # fill in REDIS_PASSWORD, POSTGRES_PASSWORD, ACCESS_TOKEN_SALT and JWT_SECRET_KEY in .env
  docker compose -f docker/docker-compose.yml up -d
  # open http://localhost:3333 and create the first user via Get Started (it becomes the admin)
  ```

- Needs: Docker with Docker Compose, or for development Node.js 22.18+ and Docker for PostgreSQL and Redis
- Develop: `cp .env.dev .env && npm install && docker compose -f docker/docker-compose.dev.yml up -d && npm run database:setup && npm run start:server   # then in another terminal: npm run start:client (https://localhost:4200/en)`
- Test: `npm test`
- Check/lint: `npm run lint`
- Build: `npm run build:production`
- Stack: typescript, html, scss (Nx, NestJS, Prisma, Angular, Angular Material, Bootstrap). Difficulty for a non-developer with an AI: **advanced**. A TypeScript monorepo (Nx) with a NestJS API, an Angular client, Prisma and PostgreSQL plus Redis. Most personal changes are settings or API scripts; screen changes need Angular knowledge and a full rebuild.

## The project's own AI instructions
Read these in the repository before changing code: `DEVELOPMENT.md`.

## Customisation points (settings → extend → code)
- **account-settings** [settings]: Base currency, language, date and number format, dark or light appearance, Presenter View (hides amounts), Zen mode and experimental features. → `Account menu → Settings (apps/client/src/app/components/user-account-settings/)`
- **accounts-and-activities** [settings]: Your brokers and bank accounts, and every buy, sell, dividend, fee and interest payment. → `Accounts and Portfolio → Activities pages, CSV import and export`
- **x-ray-rules** [settings]: Which risk checks to run and their limits, such as too much in one currency, region or account. → `Portfolio → X-ray (rules in apps/api/src/models/rules/)`
- **fire-calculator** [settings]: Plan towards financial independence from what you save and what yearly income your portfolio could sustain. → `Portfolio → FIRE (apps/client/src/app/pages/portfolio/fire/)`
- **data-providers** [settings]: Where prices come from, and manual prices for things that have no market price. → `Admin Control → Market Data; providers in apps/api/src/services/data-provider/`
- **api-and-mcp** [extend]: Import trades from a broker export with a script, read your portfolio from other tools or an AI assistant. → `REST API (/api/v1/import, /api/v1/export, public portfolio endpoint; see README) and the experimental MCP server (ENABLE_FEATURE_MCP)`
- **client-pages-and-styles** [code]: New screens, charts, colours and text in the Angular client. → `apps/client/src/app/pages/**, libs/ui/src/**, apps/client/src/styles/theme.scss, apps/client/src/locales/`
- **api-and-data** [code]: New calculations, new data and new API endpoints. → `apps/api/src/app/**, apps/api/src/services/**, prisma/schema.prisma (with a Prisma migration)`

## Must keep working
- Existing activities, accounts and portfolio history. Export your activities and back up the database before code changes.
- Performance calculations (ROAI). They are covered by tests; keep npm test passing.
- Database changes need a Prisma migration (npm run prisma migrate dev --name ...); never edit old migrations.
- Security tokens, login and the separation between users on the same server.

## Staying updatable
Settings, X-ray rules, CSV import and the REST API cover most needs without a fork. For code, keep changes in new Angular components or pages and new API modules so they are easy to rebase on future releases.

## Data, costs and safety
- Personal data: **yes**. Stored in: PostgreSQL (the postgres Docker volume); Redis is only a cache. Your holdings and transactions are sensitive. Export your activities regularly (Portfolio → Activities → Export, or GET /api/v1/export) and back up the PostgreSQL volume before upgrades or code changes.
- Service: Yahoo Finance (optional, free): Default source for share, ETF and fund prices and exchange rates.
- Service: CoinGecko (optional, free demo key or paid): Cryptocurrency prices.
- Service: Other market data providers (EOD Historical Data, Financial Modeling Prep, Alpha Vantage, Ghostfolio Premium data) (optional, paid, with some free tiers): Wider or more reliable price data when Yahoo Finance isn't enough.
- Setting `POSTGRES_PASSWORD` (**secret**: the person enters it themselves, never in chat): The database password.
- Setting `REDIS_PASSWORD` (**secret**: the person enters it themselves, never in chat): The password for the Redis cache.
- Setting `ACCESS_TOKEN_SALT` (**secret**: the person enters it themselves, never in chat): A random string used to protect security tokens.
- Setting `JWT_SECRET_KEY` (**secret**: the person enters it themselves, never in chat): A random string used to protect logins.
- Setting `DATABASE_URL` (**secret**: the person enters it themselves, never in chat): The database address. The example .env builds it from the POSTGRES_* values.
- Setting `ROOT_URL`: The address you open Ghostfolio at, used for links and callbacks.
- Setting `API_KEY_COINGECKO_DEMO` (**secret**: the person enters it themselves, never in chat): Optional CoinGecko key for crypto prices.
- Setting `ENABLE_FEATURE_MCP`: Turns on the experimental MCP server at /mcp so an AI assistant can read your portfolio.
- Self-hosted with security-token login. Keep your security token safe, use HTTPS and set TRUST_PROXY behind a reverse proxy before exposing it to the internet.
- Price look-ups send the symbols you hold to the chosen market data provider.
- Database, Redis and JWT secrets and API keys are secrets. Never paste them into an AI chat.

---

# Customising Ghostfolio

Ghostfolio is a TypeScript monorepo: a NestJS API, an Angular client and shared libraries, managed with Nx. **Most personal adaptations are settings, imports and API scripts.** Code changes need Angular or NestJS knowledge and a full rebuild of the Docker image.

## Level 1: Settings (no code)
- **Your settings:** account menu → Settings. Base currency, language, date and number format, light or dark appearance, Presenter View (hides amounts and quantities), Zen mode (a calmer, distraction-free view) and experimental features.
- **Accounts and activities:** add each broker or bank account, then record buys, sells, dividends, fees and interest. Import and export activities as CSV or JSON.
- **X-ray:** Portfolio → X-ray runs risk checks (currency, region, asset class, account, emergency fund, fees, liquidity). Turn checks on or off and adjust their limits.
- **FIRE:** Portfolio → FIRE estimates a sustainable retirement income from your portfolio and savings.
- **Market data (admin):** Admin Control → Market Data. Choose sources, fix symbols and add manual prices for things without a market price (such as a house).

## Level 2: Extend (no fork)
- **REST API:** get a bearer token with your security token (`POST /api/v1/auth/anonymous`), then use `POST /api/v1/import` and `GET /api/v1/export`. Good for turning a broker's monthly export into Ghostfolio activities.
- **Public portfolio:** grant public access under Settings → Access, then read performance from `/api/v1/public/<access id>/portfolio`, e.g. for a home dashboard.
- **MCP (experimental):** set `ENABLE_FEATURE_MCP=true` to let an AI assistant read your portfolio at `/mcp`.

## Level 3: Code
Read upstream `DEVELOPMENT.md` first. Upstream also ships agent skills in `.agents/skills/` (Angular and NestJS practices).

| Change | Where |
|---|---|
| New page | `apps/client/src/app/pages/**` (routes in each `*-page.routes.ts`) |
| Shared components and charts | `libs/ui/src/**` (Storybook: `npm run start:storybook`) |
| Colours and styles | `apps/client/src/styles/theme.scss`, `apps/client/src/styles/variables.scss` |
| Text | `apps/client/src/locales/messages.xlf` (and `messages.<language>.xlf`) |
| API endpoint | `apps/api/src/app/**` (NestJS modules, controllers, services) |
| X-ray rules | `apps/api/src/models/rules/**` |
| Price sources | `apps/api/src/services/data-provider/**` |
| New data | `prisma/schema.prisma` + `npm run prisma migrate dev --name <change>` |
| Shared types and helpers | `libs/common/src/**` |

## Running locally
- **Just use it:**
  1. Clone the repo and run `cp .env.example .env`.
  2. Fill in `REDIS_PASSWORD`, `POSTGRES_PASSWORD`, `ACCESS_TOKEN_SALT` and `JWT_SECRET_KEY` with random strings.
  3. Run `docker compose -f docker/docker-compose.yml up -d`.
  4. Open http://localhost:3333 and create the first user via *Get Started*. That user becomes the admin.
- **Develop:**
  1. Install Node.js 22.18 or newer and Docker.
  2. Run `cp .env.dev .env` and fill it in, then `npm install`.
  3. Start PostgreSQL and Redis with `docker compose -f docker/docker-compose.dev.yml up -d`.
  4. Run `npm run database:setup`.
  5. Run `npm run start:server`, and in another terminal `npm run start:client`.
  6. Open https://localhost:4200/en.
- **Check:** `npm test` and `npm run lint`.

## Pitfalls
- Export your activities and back up the database first. Rebuilding years of trades by hand is painful.
- Login uses a *security token*, not a password. Store it safely; losing it locks you out.
- Performance and dividend maths has many tests. Run `npm test` after any change to calculations.
- Text in templates is translated with Angular i18n (`i18n` attributes and `$localize`). Keep new text translatable.
- To run your own changes in Docker, build with `docker/docker-compose.build.yml` instead of pulling the official image.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/ghostfolio/f144c72/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/ghostfolio/f144c72/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/ghostfolio/f144c72/r2/SKILL.md)