# How Codevre works

> The architecture behind Codevre IDE, covering the editor origin, the Nodepod runtime host, the VRE preview and what Codevre's servers do.

Last updated: October 17, 2026
Source: https://codevre.com/docs/ide/how-codevre-works

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

## The big picture

```
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)
```

## Two origins

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](security-model.md).

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.

### Cross-origin isolation

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.

### Fallback

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.

## One file system

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 `/`.

## Saving to Codevre

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.

## Runtime restarts

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.

## What Codevre's servers do

| Server-side job | Notes |
|---|---|
| Sign-in | Firebase Authentication |
| Load and save projects | Only for signed-in users who choose to save |
| Store your AI provider keys | In your account; used server-side to call the provider |
| Relay AI requests | Firebase functions (`callOpenRouter`, `callProvider`, and completion endpoints) add your key and forward the request |
| Store your GitHub link | The OAuth token is kept server-side and handed only to Git operations you start |

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

## Caches on your device

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.