Skip to content
LiveFoliodocs
Back

Quickstart

Install and run LiveFolio OSS — one command with npx, or from source. Local-first, no account, no database server.

Prerequisites

  • Node.js 20+ (the npm launcher accepts 18.17+, but the app targets 20)
  • Git — only for the from-source path

You do not need a database server, Docker, a .env file, or an account.

Install

Option A — one command (recommended)

npx @livefolio-cloud/cli

The launcher downloads the current standalone build (~24 MB), picks a free port, boots the app, and opens your browser. The terminal prints the web URL and the MCP endpoint.

# useful flags
npx @livefolio-cloud/cli --port 3001        # prefer a specific port
npx @livefolio-cloud/cli --data-dir ~/folio # move the data directory
npx @livefolio-cloud/cli --update           # re-download the latest build
npx @livefolio-cloud/cli --no-open          # don't open a browser

Data lives in ~/.livefolio/data and builds are cached under ~/.livefolio/versions/, so a second run starts instantly. Upgrades are just re-running the command — it resolves the newest release itself.

The @livefolio scope on npm belongs to an unrelated project — the package is @livefolio-cloud/cli.

Option B — from source

git clone https://github.com/LiveFolio-Cloud/LiveFolio-oss.git
cd LiveFolio-oss
npm install
npm run dev

The dev server is pinned to port 3001 so it can sit alongside your other projects. Open http://localhost:3001.

For a production build:

npm run build
npm start          # PORT=8080 npm start to use a different port

First run

  1. The landing page opens. Click Launch Dashboard.
  2. The dashboard asks you to connect a model. Paste an API key (OpenAI, Anthropic, Gemini, or DeepSeek) or point at a local Ollama. Keys are stored in your browser and sent only to the local server with each chat request — see AI Providers.
  3. Create a folio with + New folio in the sidebar (blank, upload, or template), or let an agent create one over MCP.
  4. Open a folio and switch to the Chat tab to edit it with AI, or hit the globe in the header to Go live and share it.

Nothing here requires an account or a network round-trip beyond the model provider you configured.

Where things live

From sourceVia the CLI
Folio data./database.json in the repo~/.livefolio/data/database.json
MCP endpointhttp://localhost:3001/api/mcphttp://localhost:<port>/api/mcp
Documentationhttp://localhost:3001/docshttp://localhost:<port>/docs
Master keySettings → Sharing & Tunnelsame

Verify it's running

# The app responds
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3001/

# The MCP endpoint accepts requests
curl -s -X POST http://localhost:3001/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"list_projects"}'

The first call that touches folio data creates database.json if it doesn't exist yet.

Next steps