Foam

Last reviewed Aug 26, 2026 · 798 words

Foam is not a server. There is nothing to deploy, no port, no database. It is a VS Code extension plus a set of conventions applied to a folder of Markdown files, and "self-hosting" it means one thing: owning the git remote those files sync to. If you already run a git forge, you already run the only backend Foam will ever need, and that is the whole appeal.

Where Foam sits in a stack

The pieces are a Markdown folder, the Foam extension in VS Code, and a remote repository. Foam adds wiki-style [[links]] with autocompletion, a backlinks panel, a graph view of the connections, daily notes, and link-aware rename. Everything it knows is derived from the files at open time; there is no index to corrupt and no proprietary format to export from. Sync is git push. A Forgejo instance on a Raspberry Pi is more than enough, and the same repo doubles as the backup, the history, and the multi-machine sync without any extra tool. That is the trade Foam makes against Obsidian: fewer polished features, in exchange for a system that is plain text and git all the way down.

Setup is 5 minutes and one template

Install the extension (foam.foam-vscode in the marketplace), then either open any folder of Markdown or clone the project's starter template, which ships a sample structure and recommended companion extensions for Markdown preview and link handling. Two settings are worth changing on day one: set the daily note directory so journal entries do not litter the root, and decide on a link format (wikilinks by default, or standard Markdown links for portability). Then commit and push. A note is a file, a folder is a section, and there is nothing else to learn before writing.

It runs in the browser through code-server

The self-hoster's angle most guides miss: because Foam is a VS Code extension, it runs inside code-server, which gives you a browser-based notes workspace on your own server with the repo mounted as the workspace. Install the extension from the Open VSX registry inside code-server, open the notes folder, and you have Foam from any machine with a browser, behind your usual reverse proxy and SSO. This fills the gap that a desktop-only tool would otherwise leave, at the cost of code-server's own RAM, which is well above Foam's 256 MB on its own.

Publishing the graph is a static site problem

Foam files are ordinary Markdown, so publishing is a static site generator pointed at the folder. The template includes a Jekyll configuration for GitHub Pages, but any generator that understands wikilinks, or a small preprocessing step that rewrites them, produces a browsable site. The graph view itself is an editor feature and does not publish; what you publish is the notes and their links. For a private wiki, build the site in a CI job on the forge and serve the output from a static file server behind authentication.

Foam against Obsidian and Logseq

The honest read: Obsidian is more polished, has phones covered, and its files are just as portable. Foam wins if you live in VS Code, want the editor you already use for code to be the editor for notes, and refuse a proprietary app in the loop. The notes apps you own piece compares the wider field.

The mobile gap is real

There is no Foam phone app and there will not be one. Options are a Markdown editor on the phone that syncs to the same git repo, or code-server in a mobile browser, which works but is fiddly for a quick capture. If most of your notes are written away from a keyboard, this alone should send you to Obsidian or Logseq.

What I'd do

Developers who write notes at the same desk they write code: use Foam, push to Forgejo, and stop thinking about it. Add code-server if you want browser access from a second machine. Anyone who captures ideas on a phone first: pick Obsidian with the vault in a synced folder, and keep the files in the same plain Markdown so a later move to Foam costs nothing but a git init.