Your Files & Sync
What’s inside your folder: canvas-data.json & board.json
Open your connected folder in Finder or Explorer and you’ll find a tidy structure that mirrors your canvas. Here’s what every file is — and which one is the boss.
More in Your Files & Sync
The layout
canvas-data.json — the master file
This single file at the top level is the authoritative copy of your entire workspace: every folder, every element, every position, text and arrow. It’s what visualOS loads on startup and what syncs between devices. Treat it with respect — it’s the one file you never want to edit or delete by hand.
board.json — one per folder, for humans and tools
Next to the master file, visualOS additionally mirrors your structure into something you can browse: every folder on your canvas becomes a real folder on disk, and each one contains a board.json describing just that folder’s canvas — its elements, texts and connections, self-contained and readable. Rename a folder in the app and the folder on disk is renamed with it; move an image into another folder and the file moves too.
Why? So a folder is meaningful on its own. You can zip a single project folder and send it to someone, feed it to an AI agent, or grep through it — without dragging your whole workspace along. If two sibling folders share the same name, their on-disk names get a short suffix so they never collide.
The board.json files and .md documents are a readable export, not an input. Edits you make to them outside the app are overwritten by the next save from canvas-data.json. Read them freely — but make changes in the app. (Exception: new images and PDFs you drop into a folder are picked up — via the New Items pool.) Details in Editing files outside visualOS.
Documents and images
Long-form documents are stored as plain Markdown files (.md) in the folder where they live on the canvas. Images, PDFs and other files keep their ordinary formats, right next to the board.json of their folder. Everything opens with any tool, today and in twenty years.
The hidden extras
.versions/— rolling snapshots of your master file, kept automatically (about 30 of them). This powers version history.canvas-data.conflict-….json— if two devices ever collide, the “losing” version is preserved as a file like this, never discarded. See When two devices edit at once.
Because everything is ordinary files, any backup tool that covers the folder — Time Machine, cloud sync, a plain copy — backs up your whole workspace.