If a spatial-reasoning exercise uses a fixed image bank, repetition can become a memory test instead of a reasoning test. OpenFold takes a different approach: it generates cube-net folding problems locally, renders them in a web interface, and stores training history in the browser.
This tutorial shows how to run the current OpenFold repository, verify its build and test path, and understand what the project actually guarantees. The result is a local development server for an offline educational simulator, not a hosted account or a claim that the exercises measure intelligence.
TL;DR
OpenFold is a TypeScript monorepo owned by Fernando Paladini and licensed under the MIT License. It uses React, Vite, Three.js, Recharts, and IndexedDB to train mental rotation and spatial visualization with procedurally generated cube-net exercises.
The current repository state requires Node.js 20 or newer and pnpm 10. The minimal path is:
git clone https://github.com/paladini/OpenFold.git
cd OpenFold
pnpm install --frozen-lockfile
pnpm -w build
pnpm --filter @openfold/web dev --host 127.0.0.1
Open http://127.0.0.1:5174/ after Vite starts. OpenFold is offline-only in the documented current state. There is no cloud sync or user account.
Prerequisites
You need Git, Node.js 20 or newer, and pnpm 10. The repository's root package.json declares the Node engine and pins pnpm through its packageManager field. The workspace file includes packages/* and apps/*, so the install command must run from the repository root.
The repository's default branch is main. At the time of this tutorial, I verified commit d4035d8. The README mentions v1.0.0, but that tag and release are not available in the public GitHub releases endpoint. Treat this tutorial as a verification of the current default branch, not as instructions for a stable published release.
Install the workspace
Clone the repository and install the exact dependency graph recorded in pnpm-lock.yaml:
git clone https://github.com/paladini/OpenFold.git
cd OpenFold
pnpm install --frozen-lockfile
The --frozen-lockfile flag makes the first check useful. It prevents pnpm from silently changing the lockfile while you are trying to reproduce the project state. On the verified machine, the install completed with pnpm 10.33.3 and Node.js 24.15.0.
The current root manifest is private and reports version 0.0.0. That is another reason not to describe this checkout as an installed v1.0.0 package. The web workspace package is private and reports version 0.1.0.
Build the web application
Run the root build script:
pnpm -w build
The root script builds the workspace packages and applications. In the verified checkout, TypeScript compilation completed for the core and render packages, and Vite produced the web bundle for @openfold/web.
Vite reported a chunk-size warning for the generated JavaScript bundle. That is a build warning, not a failed build. It is worth keeping in mind if you later turn this educational project into a production web deployment, but it does not prevent local use.
Start the simulator
Start the documented web package directly:
pnpm --filter @openfold/web dev --host 127.0.0.1
The current Vite configuration sets port 5174. Visit http://127.0.0.1:5174/ in a browser. I verified that the development server returned HTTP 200 and that the response contained the OpenFold page title.
The interface is organized around training rounds, explanations, history, and settings. The repository describes three preset difficulty tiers and guided lessons for opposition and orientation rules. These are application behaviors described by the current source and tests, not an adaptive assessment or a clinical instrument.
Verify the project instead of trusting the page
OpenFold includes tests for the mathematical core, rendering behavior, and web application. Run them from the root:
pnpm -w test
In the verified checkout, the command passed 452 tests:
- 112 tests in
packages/core. - 76 tests in
packages/render. - 264 tests in
apps/web.
The core tests check properties such as valid generated nets, distinct distractors, rotation-equivalent solutions, and seeded generation behavior. The render tests compare the visual fold state with the core model. The web tests cover rounds, explanations, IndexedDB persistence, exports, and several integration paths.
That distinction matters. A passing test suite supports confidence in the checked invariants and workflows. It does not prove that every browser, screen reader, GPU, or operating system behaves identically.
Why procedural generation helps
The README describes 11 canonical cube nets and a deterministic pseudorandom generator. Instead of selecting one image from a finite static bank, the core package can generate a problem from a seed, construct alternatives, and verify the folding relationship.
This design gives the project two useful properties. First, the exercise set is not limited to a small collection of screenshots. Second, a failing case can be investigated with a reproducible seed. The tests use that property to sweep many seeds and check invariants rather than relying only on a few hand-written examples.
The web application keeps telemetry and training history locally with IndexedDB. Recharts is used for charts, while Dexie provides the browser database layer. The local storage boundary is explicit: the current project does not provide cloud synchronization, accounts, or a server API.
Common failure modes
The wrong package manager
If pnpm is missing or the version is too old, installation can fail before the workspace is linked. Check the root package.json and use pnpm 10 rather than substituting npm commands. The repository is structured as a pnpm workspace.
Running from the wrong directory
The root scripts use workspace filters. Running them from apps/web changes the context and can make the command appear to be missing packages. Start in the directory that contains pnpm-workspace.yaml.
Mistaking a warning for a failed build
Vite may warn about a bundle larger than 500 kB. Read the final exit status and the generated output. A warning deserves a future optimization task, but it is different from a compilation or test failure.
Expecting saved history on another device
Training data is stored in the local browser. Clearing site data, changing browsers, or moving to another machine can remove access to that history. The project includes export-related code, but it does not currently provide remote backup or synchronization.
Security and privacy boundaries
The current README describes an offline-only application with no network calls during training and no user accounts. That reduces the data-sharing surface for local practice, but it is not a security guarantee for every dependency or future build.
Review the dependency lockfile before distributing a build. Use the source and lockfile from a known commit, keep browser permissions narrow, and do not treat locally stored telemetry as encrypted evidence. If you add cloud sync, authentication, analytics, or a hosted API, those changes require a new threat model and a new privacy review.
The MIT license permits reuse with the conditions stated in LICENSE. It does not provide a warranty, and OpenFold should not be presented as medical, psychological, or employment advice.
FAQ
Does OpenFold need an internet connection while I train?
The documented current design is offline-only after download. You need network access to clone the source and install dependencies, but the application itself is designed to run locally.
Can I use it as an adaptive assessment?
No. The current README explicitly describes deterministic difficulty tiers rather than adaptive IRT. It is an educational simulator for practice, not a validated assessment.
Is there a desktop installer?
The repository contains a Rust desktop wrapper, but the current README lists portable binaries and no native installers as a limitation. The commands in this tutorial run the web application.
Can I add another language?
The README says the structure is ready for translations, while the current application is English only. Adding localization would require implementation and verification work; it is not enabled by the commands above.
Takeaway
OpenFold is a useful example of a local-first learning tool: procedural generation supplies reproducible exercises, the rendering layer visualizes the fold, and IndexedDB keeps training history in the browser. The reliable way to evaluate it is to pin a commit, install with the frozen lockfile, run the build and tests, then inspect the local Vite application.
What would you value most in a next iteration: more spatial problem types, localization, or an explicitly designed export and backup workflow?
Disclosure: AI assistance was used to organize and edit this tutorial. The repository claims, commands, version details, and verification results were checked against the cited public sources and a fresh checkout of the current main commit.
Top comments (0)