PennyOS guide

How PennyOS works with Obsidian

PennyOS is the pocket end of an Obsidian vault kept on an always-on computer you own. Here is what each side does, what crosses between them, and what your vault needs.

The idea

Obsidian keeps your notes as plain markdown files in a folder called a vault, linked with [[wikilinks]]. PennyOS reads those same files. Put the vault on an always-on computer, and the Beepy becomes a pocket window onto it: it reads your pages offline, asks Claude questions inside the vault, and files new notes back into it.

Obsidian itself does not need to run on the server, and PennyOS is not an Obsidian plugin. What matters is the folder of files. Keep editing the vault in Obsidian on your computer or phone however you already do.

The division of labour

This split is why losing the device is survivable. It is a remote control and a notebook, not a copy of your accounts.

What your vault needs

• A wiki/ folder at the vault root. This is what Vault mirrors onto the card. Put the pages you want in your pocket there. Everything outside it stays on the server.
• Catalogue files at the root: index.md, index-entities.md, index-concepts.md and index-sources.md, plus profile.md and CLAUDE.md. Vault opens on index.md. If your vault has no use for the others, create them empty, or sync reports an error.
• An inbox: inbox/pennyos/ and inbox/pennyos/journal/.

The .obsidian settings folder and .git are never copied to the device.

A vault PennyOS can read

My Vault/
├── wiki/                  mirrored to the Beepy
│   ├── people/
│   └── projects/
├── inbox/
│   └── pennyos/           notes from the Beepy land here
│       └── journal/       journal entries land here
├── index.md               Vault opens on this page
├── index-entities.md      may be empty
├── index-concepts.md      may be empty
├── index-sources.md       may be empty
├── profile.md             may be empty
├── CLAUDE.md              may be empty; Claude Code reads it
└── .obsidian/             never copied

What crosses between them

Every request the device makes to the server is an SSH command, and a gate script on the server checks it against a short list before running it.

Anything else is refused with a JSON error and logged with the command. See The gate.

The loop, end to end

1. You jot a note on a bus with the radio off. It is on the card.
2. You get home. The device joins Wi-Fi, sees the server, and syncs: the note goes to inbox/pennyos/, a fresh mirror of wiki/ comes back, and Mail, News and Glance refresh.
3. The note appears in Obsidian on your computer. You file it, or have Claude Code work it into your pages.
4. Next morning, the updated page is in Vault on the device, and Ask can answer from it.

Nothing in that loop needs you, the device and the server online at the same moment.

Pieces PennyOS does not include

Three apps talk to things on the server that you provide. If one is missing, that app says it cannot answer and nothing else is affected.

• A console, for Glance and Usage. A small web service on your private network that answers /glance with a few plain text lines about overdue items, and /usage and /usage/refresh with Claude usage as JSON, accepting a token in a ktoken cookie.
• A retrieval script, for Chat. tools/local_ask.py in the vault, which takes a question and recent turns, finds matching sections of your pages, asks a local model, and streams back the pages it read and the answer as JSON lines.
• Keeping the vault current. PennyOS delivers notes to the inbox. Whether you file them by hand or with an agent is up to you.

Without a server

PennyOS runs fine alone. Notes, Journal, Keys, Clock, Solitaire, Weather, Field, News, Store and Link all work. Add a server later with Server setup.

Which pieces each app needs