Documentation

Guides for Glideworth: self-hosting, connecting an AI assistant over MCP, the REST API, importing from ProjectionLab, and how the results are calculated.

Guides for running and using Glideworth: getting started, building and reading a plan, running it yourself, connecting an AI assistant, importing your data, and how the numbers are calculated. Commands and settings are shown as they are in the current release. If you are upgrading an instance that still uses the old names, seeUpgrading.

Getting started

  • What Glideworth is: Glideworth is an open-source financial and retirement planner. See what it does, what it does not do, and the two ways to run it.
  • Your first plan in ten minutes: Start Glideworth, choose a passphrase, answer six setup questions, and read your first projection and chance of success.
  • Core concepts: The ideas behind Glideworth in plain words - household, current finances, plans, milestones, today's money versus future money, and amounts with a basis and a frequency.
  • The hosted service: What the Glideworth hosted service will add to the software you can self-host today, what is planned but not built, and why self-hosting stays free. It is not open yet.

Planning

  • Build a plan: Enter accounts, real assets, debts, income, expenses, savings flows, milestones, drawdown order and assumptions in the Current finances page and the Plan editor.
  • Read your results: What each results page shows - Results, Cash flow, Taxes, Chance of success and Estate and legacy - and how to check that the numbers add up.
  • Tax settings, countries and currency: Choose how tax is estimated, which countries are covered, what each estimate leaves out, and how accounts in several currencies work.
  • Moving country and cross-border plans: Model a move between countries with a residency timeline, source-country tax, treaty relief and wrapper rules, and compare staying with moving.
  • Solvers, guardrails and insights: Ask how much you can spend, when you can retire, how much to save, what a safe withdrawal rate is, and how to adjust spending as markets move.
  • Branches, compare, history and what-ifs: Try an idea without touching your main plan with branches, compare plans side by side, go back through version history, and use what-if templates and survivor scenarios.
  • Progress snapshots and check-ins: Record your real balances over time with progress snapshots, compare them with the plan, and use scheduled check-ins and notifications to spot drift.
  • Sharing and roles: Give a partner or adviser their own sign-in with an owner, editor or viewer role, or send a read-only share link that shows results without your accounts.
  • Reports, exports and settings: Print a plan report, export tables and backups, and what each section of Settings controls, from locale and planning defaults to API keys and webhooks.

Self-hosting

  • Install with Docker: Run Glideworth in one Docker container with its data in a volume, protect first-run setup with a token, choose a passphrase, and create API keys.
  • Configuration reference: Every Glideworth environment variable, its default and what it does, for the Docker image and for running from source.
  • HTTPS behind a reverse proxy: Put Caddy or nginx with TLS in front of Glideworth, bind the container to loopback, and set the proxy and public URL variables correctly.
  • Backups, restore and moving machines: Take an online backup of the single SQLite file, copy it off the machine, restore it safely, and move Glideworth to a new machine.
  • Upgrading: Back up, pull the new version, rebuild, and roll back if something goes wrong. Migrations run automatically at start-up.
  • Self-hosting troubleshooting: Fix a container that is unhealthy, sign-in loops behind HTTPS, throttling, imports that fail with 413, blocked webhooks, restore errors and slow simulations.

API and MCP

  • Connect an AI assistant over MCP: Connect Claude Code, Claude Desktop, Cursor and other MCP clients to Glideworth over HTTP or stdio with a least-privilege key, and keep plan edits as proposals you approve.
  • REST API overview and conventions: Base URL, units, errors, pagination, optimistic concurrency with ETag and If-Match, idempotency keys, rate limits and partial updates for the Glideworth REST API.
  • API authentication, scopes and roles: Create scoped API keys, sign in from a browser with a passphrase and CSRF token, understand owner, editor and viewer roles, and connect remote MCP clients with OAuth 2.1.
  • API quick start with curl: Call the Glideworth API in minutes - identify your key, run a projection, start a Monte Carlo job, edit one number safely, and push balances atomically.
  • API - households, finances and plans: Routes for households and people, accounts, real assets and debts, plan collections and settings, version history and undo, and branches.
  • API - simulation, solvers, insights and jobs: Deterministic projections with compact views, Monte Carlo and solver jobs with polling, server-sent events and cancellation, insights, and moving-country routes.
  • API - change sets and safe edits: Propose, preview, apply or discard plan edits as change sets with conflict detection, and a worked example of an agent editing a plan safely with curl.
  • API - import, export and reports: Export a household as JSON, import Glideworth or ProjectionLab files, import CSV and bank files with a dry run, and fetch table and report data.
  • API - share links, check-ins and webhooks: Create read-only share links, schedule plan check-ins and read notifications, and receive signed webhook events with HMAC signature verification.
  • API reference: Every Glideworth REST API operation by group, with method, path, summary, required key scope, parameters and the request and response schema names.
  • MCP server overview and safety model: What the Glideworth MCP server is, how read-only access and change sets keep AI assistants safe, how writes are enabled, and the prompts and resources it offers.
  • MCP tools reference: All 75 Glideworth MCP tools by purpose, with one line each: 54 that read and compute, and 21 write tools that exist only when writes are enabled.
  • MCP worked examples: Five example conversations with the tool calls an assistant makes, from summarising a plan to editing one safely with your approval at each step.

Importing

  • Import from ProjectionLab: Export from ProjectionLab as JSON and import it with a report of what mapped exactly, what was approximated and what has no equivalent. Re-import safely.
  • Import from CSV: Import account balances, net-worth history or transactions from Monarch, YNAB and generic CSV files, with a dry run that shows what will change first.
  • Import bank files (OFX, QFX, QIF): Import balances and spending from bank and card statements in OFX, QFX or QIF format, with account numbers masked and a dry run before anything is written.
  • Glideworth JSON backup and restore: Export a household as one JSON file, restore it into any Glideworth instance, and how replace and merge modes treat existing plans and history.

Reference

  • How a projection is computed: The yearly pipeline in plain language, real versus nominal money, the flow and stock convention, cash-flow timing, and how tax estimates plug in.
  • Monte Carlo and historical replay: How the chance of success is computed, with sampling methods, seeds, what counts as success, failure analysis, and a comparison with FIRECalc.
  • Historical data and its limits: Which historical return datasets Glideworth uses, where each comes from, how they are licensed and what they cannot tell you, including the limits of the UK data.
  • Known limitations: What Glideworth does not model, where its tax estimates are simplified, which figures could not be confirmed, and what is partial, from the project's status document.
  • FAQ and troubleshooting: Quick answers on accuracy, privacy, tax estimates, chance of success, importing, AI assistants, self-hosting and the hosted service, with fixes for common problems.