How it works

How it works

---

The shape of it

Electron window
      │  HTTP + SSE on 127.0.0.1:3456
      ▼
Local Node server ──── LLM provider (your key, or local Ollama/LM Studio)
      │
      ├─ writes case files to disk
      └─ Docker ──► OpenFOAM 13 container ──► solver output

Three moving parts:

The window is a React renderer. It holds no state you care about permanently and talks to the local server over HTTP and server-sent events. It never touches your filesystem or Docker directly.

The local server is where everything happens: the agent loop, file generation, Docker orchestration, error diagnosis, and VTK conversion. It binds to 127.0.0.1 only — never a LAN interface — because it exposes project files and container execution.

The container is stock microfluidica/openfoam:13 (OpenFOAM 13 Foundation). Your case directory is bind-mounted in. Nothing about your case lives inside the image, so you can delete and re-pull it freely.

The packaged app runs the server using Electron's own bundled Node, which is why there is no Node.js prerequisite.

---

What the agent can actually do

It has a small, fixed set of tools — not shell access:

• Read and write files inside the active case directory
• Run a command from a fixed allowlist inside the container
• Read solver logs
• Search the bundled CFD knowledge base and the OpenFOAM 13 documentation cache

The Docker allowlist is exactly: blockMesh, checkMesh, setFields, foamRun, foamToVTK, icoFoam, simpleFoam, pimpleFoam. Anything else is refused before it reaches Docker.

There is no raw shell access, ever. No arbitrary command execution is exposed to the model, so a prompt — however crafted — cannot make it run something outside that list. File writes are confined to managed project directories; path traversal outside them is rejected.

The knowledge base ships inside the app: a curated set of OpenFOAM 13 pages on case structure, solver selection, and known failure patterns, searched by keyword rather than a vector database. The corpus is small and citation-style hits work better here than dense retrieval.

---

The four roles

One conversation, four roles the model moves through in order:

1. Architect — classify the simulation, list required files in dependency order.
2. Input Writer — generate each file in that order, each with full context of the ones before it.
3. Runner — mesh, then solve, through the allowlist.
4. Reviewer — on failure, read the log, produce a root-cause diagnosis and a file-level fix, wait for your approval, then hand back to the Runner. Three cycles maximum.

No orchestration framework and no multi-agent handoff. It is one thread with a system prompt that defines the sequence.

---

Where your data lives

Everything is plain files. There is no database.

<settings dir>/projects/<project-id>/
├── meta.json          project metadata and full conversation history
├── case/              the OpenFOAM case — ordinary dictionaries and field files
├── runs.jsonl         one record per run
├── runs/<runId>.log   stored solver log per run
└── commands.jsonl     every Docker command executed, with exit codes

<settings dir> is ~/Library/Application Support/OpenFOAM Studio on macOS and %APPDATA%\OpenFOAM Studio on Windows.

Consequences worth knowing: case/ is a normal OpenFOAM case, so any external OpenFOAM tooling works on it. Backing up a project means copying one directory. Deleting the app leaves your projects untouched.

---

Results rendering

After a successful solve, foamToVTK converts every written time step to legacy VTK under <case>/VTK/. The app walks that directory, classifies internal-mesh versus boundary-patch files, and builds a time series.

The renderer parses those files itself — vtk.js v35 ships no legacy unstructured-grid reader — extracts the external surface, and caches each parsed step so scrubbing through time never re-reads from disk.

---

Line endings

Every OpenFOAM file is written with LF endings, enforced in the file writer regardless of platform. A single CRLF silently corrupts an OpenFOAM dictionary, and this class of bug is invisible until the solver produces nonsense. Windows users get correct files.

---

Environment variables

For unusual setups:

Variable	Effect
OFS_OPENFOAM_IMAGE	Use a different OpenFOAM image instead of microfluidica/openfoam:13
OFS_DISABLE_GPU=1	Force software rendering if your GPU driver breaks the 3D viewers
OFS_CONFIG_DIR	Move the settings and projects directory

---

Reading the source

Path	What is in it
core/	Agent loop, tools, knowledge index, file generation, Docker runner, error recovery
demo/server.ts	The local HTTP + SSE server
demo/electron-main.cjs	Electron entry point
renderer/	React UI
wiki/	The CFD knowledge base the agent searches
tests/	Five staged suites, from environment up to the Ghia physics benchmark

github.com/PKrunal26/openfoam-studio