| id | 597e49f2-4dc3-5aaf-a276-cfbfc09289be |
| name | flowpad_logs |
| description | Where to find the on-disk logs for Flowpad — the local backend instances (Alice / Bob), the Electron desktop app (shell / monitor / server), and the local hub. Use when you need to read backend or desktop logs to debug the running processes instead of asking the user to copy-paste console output. |
| tags | ["logs","debugging","dev","instances","electron","desktop"] |
Flowpad Logs — where to find them
Each local flowpad backend and the local hub mirror their full log output
to a timestamped file on disk (in addition to the PyCharm / stdout console).
Read these files directly — do not ask the user to copy-paste console output.
Layout
| Process | Checkout | Instance | Port | Log directory |
|---|
| Alice — flowpad app | ~/Developer/flowpad-2 | dev | 9008 | ~/.flow/instances/dev/logs/ |
| Bob — flowpad app | ~/Developer/flowpad | prod | 9007 | ~/.flow/instances/prod/logs/ |
| Local hub | ~/Developer/flowpad-hub | n/a | 8093 | ~/Developer/flowpad-hub/logs/ |
The app log directory comes from instance_settings.logs_dir, which resolves
to <flow_home>/instances/<instance_name>/logs (flow_home = ~/.flow).
instance_name is dev when FLOWPAD_DEV=true (Alice, port 9008) and prod
otherwise (Bob, port 9007) — so the two local instances never share a folder.
The hub is a single shared service, not per-instance, so its logs live in the
hub repo at <hub-repo>/logs/, not under ~/.flow/instances.
Electron desktop app logs (~/.flow/logs/...)
The packaged desktop app (the Electron shell) writes a separate set of logs
under ~/.flow/logs/ — not under ~/.flow/instances/<name>/logs/. These are
the ones to read when the app "won't start" / is "stuck on Starting…":
| Dir | Written by | What's in it |
|---|
~/.flow/logs/main_desktop/ | Electron main process (electron/main.js) | shell startup, waitForBackend health polling, [uv] / [electron-updater] / [flow stderr] lines, the "Startup Error" details |
~/.flow/logs/monitor/ | the backend monitor (flow start) | monitor / restart activity, the tail shown in the shell's Startup-Error dialog |
~/.flow/logs/server/ | the backend server process | the Python backend's own log for a desktop-launched run |
Filenames are timestamped (<day><Mon><Year>_<HH>_<MM>_<SS>.log); take the newest:
for d in main_desktop monitor server; do
echo "== $d =="; tail -40 "$(ls -t ~/.flow/logs/$d/*.log 2>/dev/null | head -1)"
done
# Windows
foreach ($d in 'main_desktop','monitor','server') {
"== $d =="; Get-Content (Get-ChildItem $HOME\.flow\logs\$d\*.log | Sort LastWriteTime -Desc | Select -First 1) -Tail 40
}
Key signatures to look for in main_desktop: Backend failed to start within timeout, [startup error details], [update] desktop upgraded, [uv] Upgrading flowpad..., [electron-updater] update downloaded, flow shim blocked by Windows Device Guard, Failed to spawn flow start.
Get the most recent log
A new timestamped file (<day><Mon><Year>_<HH>_<MM>_<SS>.log, e.g.
19May2026_11_06_58.log) is created each time a server starts. The server
also prints the exact path at boot as Dev file log: <path>.
ls -t ~/.flow/instances/dev/logs/*.log | head -1
ls -t ~/.flow/instances/prod/logs/*.log | head -1
ls -t ~/Developer/flowpad-hub/logs/*.log | head -1
What's in them
Each file contains both the stdlib logging tree (uvicorn access logs,
flow_sdk.* / flowpad.hub.* module loggers) and the rich-console timer
lines — the same content shown in the PyCharm Run console.
Notes
- File logging is active only when running locally in development mode; a
prod cloud deploy writes nothing to disk.
- Besides stdout and these files, the hub also ships logs to Logfire (cloud
observability) when configured —
<hub-repo>/logs/ is its only on-disk log.
- Old files are pruned automatically (roughly the 15 most recent are kept).
- Written by
init_dev_file_logging() — flow_sdk/service_log.py for the app,
flowpad/hub/service_log.py for the hub.
