How Codevre works

This page is for anyone who wants to understand what happens under the hood, including AI assistants answering questions about Codevre.

codevre.com/ide  (the editor: Monaco, Explorer, Source Control, Agent UI)
   │
   │  private MessageChannel (RPC)
   ▼
preview.codevre.dev/nodepod/host.html   (hidden, cross-origin-isolated iframe)
   ├─ Nodepod runtime: virtual file system, shell, node, npm, git
   ├─ Service worker: serves dev servers at /__virtual__/<id>/<port>/
   └─ Nodepod DevTools bridge for server previews

preview.codevre.dev  (VRE: the localhost:codevre static preview + DevTools)

The IDE page you open lives on codevre.com. Everything that runs project code lives on preview.codevre.dev:

• The Nodepod host. When the IDE loads, it starts an invisible iframe at https://preview.codevre.dev/nodepod/host.html?parentOrigin=<editor origin>. The page starts it before the editor's own scripts finish loading, so the runtime boots in parallel.
• The VRE preview (the localhost:codevre tab).
• Dev server previews at https://preview.codevre.dev/__virtual__/<instanceId>/<port>/.

The browser's same-origin policy keeps pages on preview.codevre.dev away from codevre.com: its cookies, storage, sign-in session and the editor's memory. A page you build, or a package you install, can't read your account or your keys. See Security model.

The editor and the runtime talk over a MessageChannel set up in a one-time handshake. The editor posts the connect message only to the exact origin https://preview.codevre.dev. All later traffic, such as file reads and writes, spawning processes and terminal input, goes through that private port as RPC calls.

Nodepod needs SharedArrayBuffer, which browsers only allow on cross-origin-isolated pages (COOP/COEP headers). So the IDE page is cross-origin isolated and the runtime iframe is created with allow="cross-origin-isolated". This is also why sign-in and GitHub authorization open in a normal tab instead of a popup: auth popups don't work from an isolated page.

If the remote runtime can't start, the IDE falls back to running Nodepod on the editor's own origin and logs [Nodepod] remote runtime failed; falling back to editor-origin Nodepod. Everything still works, but previews lose the extra origin separation.

Your project lives inside Nodepod's virtual file system, in the workspace folder. Run pwd in a new terminal to see its path. Every part of the IDE uses that one copy:

• The editor writes your changes to it about 500 ms after you stop typing.
• The terminal, npm, build tools and git read and write it directly.
• The Explorer watches it, so files created by npm install, a build or git pull show up on their own.
• The Agent's file tools go through it.
• VRE gets a copy of the files it needs to serve. It rebuilds that copy when files change.

/ is Nodepod's own root. It also holds runtime folders like /tmp, /dev, /home and /usr/local/bin. Your project is the workspace folder, not /.

The runtime's file system lives in browser memory and caches. Saving to Codevre (Ctrl+S) uploads the project to your account so you can reopen it anywhere:

• Saved: your files, including .git (so history, branches and the remote survive), the IDE layout, and Agent chats.
• Never saved: node_modules, .npm, .cache, .DS_Store. They are rebuilt instead. The Explorer shows them faded.

When you reopen a saved project, Codevre downloads the files into a fresh runtime. If there's a package.json, it reinstalls dependencies; Nodepod's package cache usually makes that fast.

The runtime is restarted when you sign in or out and when you connect or disconnect GitHub. That way no credential from the previous session survives in a running process. After a restart, terminals are fresh, your files are restored from the saved project plus any unsaved editor text, and npm install runs again if needed.

Codevre's servers never run your project's code, build it or host its dev servers.

To keep installs and startup fast, the runtime caches data in your browser's storage (IndexedDB and, where available, the Origin Private File System): downloaded packages, snapshots of installed node_modules, compiled modules and build caches. It can grow to several gigabytes. Dependency snapshots older than seven days are removed automatically. Clearing site data for codevre.com and preview.codevre.dev removes all of it; the only cost is a slower next install.