flowgraphapp 0.2.49

FlowGraph — local-first knowledge-graph canvas + AI planner, run securely on your own machine.

FlowGraph — local server (flowgraphapp)

Run FlowGraph — the local-first knowledge-graph canvas + AI planner — on your own machine. Same app as flow-graph.com, served from a hardened localhost server; your data stays in your browser, and (optionally) your AI key stays in your OS keychain instead of the browser.

Install

From PyPI:

python3 -m pip install flowgraphapp      # or, isolated: pipx install flowgraphapp
flowgraph                              # serves http://127.0.0.1:8765 and opens your browser

If your shell has a pip command, pip install flowgraphapp is equivalent. The PyPI distribution is named flowgraphapp; the installed command is flowgraph, not flowgraphapp.

From source (developers — the private-repo path, no PyPI needed):

# 1. build the frontend once (the server serves app/dist)
cd app && npm run build && cd ..
# 2. install EDITABLE — the `flowgraph` command links back to this repo, so every
#    `git pull` / local edit is live immediately (never reinstall, never publish)
python3 -m pip install -e server/        # or: pipx install -e server/
# 3. run it
flowgraph

A plain pip install server/ (no -e) also works but installs a frozen COPY — it goes stale the moment the repo moves, which is exactly how a flowgraph command ends up missing newer subcommands. Editable is the right mode while developing. The headless intent runner (flowgraph run "…") resolves app/scripts/headless-intent.ts relative to the repo — automatic under -e; a copied install needs FLOWGRAPH_HEADLESS_ENTRY set.

Open the printed URL if the browser does not launch automatically. The default port is http://127.0.0.1:8765; if that port is already busy, FlowGraph picks a free port and prints the replacement URL. Stop with Ctrl-C. Options: flowgraph --port 0 (auto-pick a free port), --no-open (don't open the browser), flowgraph --help.

Why local

• Offline / air-gapped — no Cloudflare, no network required for the app itself.
• Privacy / data locality — your graph lives in the browser's IndexedDB on this machine.
• On-device models — point at Ollama / LM Studio for zero-key, zero-cost AI.
• No size ceiling — not bound by hosting per-file limits as the app grows.

AI

Local-model-first: if a local runtime (Ollama :11434, LM Studio :1234) is reachable, it's used with no key. Otherwise bring your own provider key — stored in the OS keychain, used server-side, never sent to the browser:

flowgraph keys set anthropic     # or openrouter / openai / google / deepseek
flowgraph keys list              # shows source, never the key

Live Voice

Live Voice specifically requires an OpenAI key on the trusted local server. Store it in the OS keychain and restart FlowGraph:

flowgraph keys set openai
flowgraph keys list
flowgraph

The local server calls OpenAI's Realtime client-secret endpoint and returns only a short-lived credential to the browser. Do not put a normal OpenAI key into browser storage for the Voice transport. The in-app Settings → AI model & keys → OpenAI field is separate: it configures ordinary Chat, Compose, Studio mapping, and delegated expert answers.

BIM questions use the already-indexed IFC/Autodesk metadata first. Opening Studio, turning 3D on, and navigating live geometry are separate, confirmation-gated actions because waking geometry can be slower and use more device memory; turning 3D off is immediate.

The Realtime model itself understands ordinary spoken requests, answers, and chooses typed FlowGraph actions. It does not use a deterministic phrase table or require a second model call for every turn. A second, grounded text-model call happens only when Realtime chooses the expert tool for a deeper evidence or judgment question. The voice action surface includes Undo/Redo, cards, sections, checklist actions, groups and nested groups, relationship labels, image/video cards, review status, themes, lenses, scrolling, canvas navigation, and Studio controls.

If the person explicitly asks Voice to inspect the layout, the browser can send the same Realtime session one temporary image of the visible Canvas and exact graph structure. It excludes app and browser chrome, is never triggered automatically after a move, and is not saved in the vault or transcript.

New user-facing operations become voice-capable by registering one typed AppAction; the Realtime tool catalog is generated from that registry and parity-tested. There is no separate voice phrase table to keep synchronized.

Autodesk Construction Cloud / Revit / Navisworks

IFC stays local, private, and free. To sign into Autodesk Construction Cloud from the pip-installed app—or view/translate .rvt, .nwd, .dwg, or .dgn—connect your own Autodesk APS app once:

# 1. At https://aps.autodesk.com/myapps create a Traditional Web App and add:
#    http://127.0.0.1:8765/api/aps/auth/callback
#
# 2. Store its Client ID + Secret in the OS keychain (input is hidden):
flowgraph keys set aps-client-id
flowgraph keys set aps-client-secret

# 3. Start/restart FlowGraph on the callback's default port:
flowgraph

In FlowGraph, add a Smart 3D card → Choose from Autodesk → complete Autodesk's sign-in page → choose the ACC project, folder, and model for that card. Each card retains its exact model version. Autodesk access/refresh tokens and the app secret stay in the local server process and are never returned to browser JavaScript. APS_CLIENT_ID / APS_CLIENT_SECRET environment variables are also supported. Keep port 8765 available because OAuth callback URLs are port-specific.

MCP tools (live execution)

The app's Agent view can execute action steps against your MCP servers — allowlisted, deny-by-default, configured server-side only (the browser never holds a session or a secret). Create mcp-servers.json in the FlowGraph config dir (macOS ~/Library/Application Support/flowgraph/, Linux ~/.config/flowgraph/; override with FLOWGRAPH_MCP_CONFIG=/path/to/file.json):

{
  "servers": {
    "revit": {
      "kind": "mcp", "transport": "stdio",
      "command": "python3", "args": ["-m", "revit_mcp_server"],
      "env": { "REVIT_TOKEN": "…" },
      "tools": ["export_ifc", "list_levels"],
      "timeoutMs": 60000
    }
  },
  "limits": { "callTimeoutMs": 30000, "maxResponseBytes": 262144 }
}

Only named servers run, and only their named tools (or "*") are discoverable/callable. Every call is timeout-bound and size-capped; a duplicate of the same pending run is refused (idempotency); config secrets are never echoed in any response. Each server is spawned with a minimal environment (PATH/HOME/locale + the entry's own env) — API keys in your shell are never inherited by MCP subprocesses — and a server that fails or hangs during startup is killed on the spot, never orphaned. executed:true in the app means a genuine tools/call completed here — nothing else can flip a run to LIVE. Transport is stdio in this version.

This section describes FlowGraph acting as an MCP client for tools such as Revit. FlowGraph also has its own 36-tool governed MCP server for external agents; that developer server is currently run from a source checkout (app/mcp/server.ts) with Node.js and is not embedded in the Python wheel:

cd /path/to/FlowGraph/app
FLOWGRAPH_VAULT=/path/to/your/vault npx tsx mcp/server.ts

Its generated catalog is ../docs/api.md. API v1.1 adds the data-only ifc_qa read surface: the same readiness denominator, answer-source partition, held/rejected rules, per-key coverage, and remediation list shown by Model QA. It reads a saved Domain from the connected folder’s vault.json; it never starts a model, loads geometry, or runs AI.

Security (safe by default)

Binds loopback only (127.0.0.1); a per-session token is required (delivered via the terminal + a 0600 file; the auto-opened URL carries a one-time ticket, never the token). Host-header allow-listing blocks DNS-rebinding from websites you visit; Origin checks, strict CSP, and security headers apply to every route. Exposing beyond loopback (--allow-lan) requires TLS. See docs/18-local-server.md for the full threat model.

Updates

pip install -U flowgraphapp (or flowgraph upgrade) updates the app and server together; your data is untouched. A calm one-line "update available" notice appears at startup — disable with FLOWGRAPH_NO_UPDATE_CHECK=1.

What is in the package

The PyPI wheel contains the local server plus the compiled FlowGraph web app. It does not include the repo's private planning docs, reference folders, tests, app source tree, or development scripts.