PennyOS guide

Server setup

Everything to install on your server, in the order that gets apps working soonest. Each step is optional after the first.

The server can be any always-on Mac or Linux computer with SSH, Python 3 and rsync. Paths below use /home/you; on a Mac that is /Users/you. Throughout the device's screens, this computer is called "the mini".

1. SSH and the vault

• Turn on SSH. On macOS, System Settings > General > Sharing > Remote Login.
• Have an Obsidian vault with wiki/, index.md, index-entities.md, index-concepts.md, index-sources.md, profile.md and CLAUDE.md at its root. Those are the names the sync pulls; create empty ones if your vault does not use them, or sync reports an error.
• Create inbox/pennyos/journal/ inside it.
• Install the gate and add the device's key.

Working now: Vault, and sync for Notes and Journal.

2. Claude Code, for Ask

• Install Claude Code and sign in, from a normal terminal on the server.
• Make sure claude is on the PATH for non-interactive SSH sessions. With zsh on macOS, put the PATH line in ~/.zshenv. Test from another computer with ssh you@server 'command -v claude' using an ordinary key.

Working now: Ask.

3. The console, for Glance and Usage

Glance and Usage read a small web service you run on the server, answering /glance and /usage behind a token cookie. PennyOS does not include it; Working with Obsidian describes what it must answer. Run it on your private network and note where its token file lives. Set glance_url and console_token_path in the device's config, and the matching URLs in the gate. The token is read on the server inside the gate and never sent to the device.

Working now: Glance, Usage, the overdue count on Home, and the amber LED.

4. Mail

On the server

install -m 755 tools/mail_reader.py ~/.local/bin/pennyos-mail
cp tools/mail.conf.example ~/.config/pennyos/mail.conf
chmod 600 ~/.config/pennyos/mail.conf

Fill in the account, then follow the sign in steps on the Mail page.

5. Search

On the server

install -m 755 tools/osint_search.py ~/.local/bin/pennyos-osint

For the email and domain kinds, install MailAccess in its own virtual environment at ~/.local/share/mailaccess-venv. If its backend will not start, install greenlet into that environment as well. Optional API keys go in ~/.config/pennyos/<name>.key.

6. Chat

Install Ollama, pull a model, and bind Ollama to a private address such as your Tailscale IP. Put a retrieval script at tools/local_ask.py in your vault. PennyOS does not include one. Set ollama_model on the device if you use direct mode.

7. Store's dig

On the server

install -m 755 tools/storefront_dig.py ~/.local/bin/pennyos-storefront

It uses Claude Code with web search and web fetch only, and San Francisco data from the property lookup.

8. Away from home

Put the server and the device on the same Tailscale tailnet, and list both names in mini_host: local name first, tailnet name second. See Offline and away.

9. Optional: open the card at home without the PIN

The server can hold a second key for the device's encrypted card. At boot, while the PIN screen waits, the device asks the server for it every three seconds for about a minute, and at home the card opens by itself once Wi-Fi is up. The shell still asks for your PIN before it unlocks. The trade is described on Security.

Checklist