PennyOS guide

Configuration

Every setting PennyOS reads, where it lives, and which ones must match your server.

Two files

/etc/pennyos.conf is written from pennyos.conf.example on first install and edited by you. Nothing in it is a secret.
local.conf in the data directory is written by Settings and wins over the first file. Delete a line there to fall back to /etc/pennyos.conf.

Both are key = value, one per line. PENNYOS_CONF in the environment points at a different file, which is how the simulator runs.

Key	Example	Meaning
`mini_host`	`server.local, server`	Names to try in order. The first that answers on port 22 is used.
`mini_user`	`you`	Your login on the server.
`vault_path`	`/home/you/vault`	The vault on the server. Must match the gate's `VAULT`.
`glance_url`	`http://server:8787/glance`	The console's glance route. Must be in the gate's list.
`console_token_path`	`/home/you/vault/.claude/console-token`	Where the token lives on the server. Read there, never sent.
`mail_reader`	`/home/you/.local/bin/pennyos-mail`	The mail reader on the server.
`osint_search`	`/home/you/.local/bin/pennyos-osint`	The Search script on the server.
`storefront_dig`	`/home/you/.local/bin/pennyos-storefront`	The Store dig script on the server.
`ask_permission_mode`	`default`	Passed to Claude Code. The gate forces `default` regardless.
`chat_direct`	`false`	Chat straight to Ollama, without the vault.
`ollama_url`, `ollama_model`	`http://server:11434`, `qwen3:8b`	For direct mode only.

Key	Meaning
`link_url`	The Link hub. Defaults to the project's hub.
`news_url`	The News API. Defaults to the project's API.
`usage_url`	The console's usage route, as the gate knows it.

Key	Default	Meaning
`data_dir`	`/var/lib/pennyos`	Notes, journal, the mirror and caches. The encrypted volume mounts here.
`lat`, `lon`, `place`		The fix. Settings > Location writes these to `local.conf`.
`idle_minutes`	`3`	Quiet minutes before the clock face. `0` turns it off.
`tty`, `terminal_vt`	`/dev/tty2`, `1`	The shell's tty, and the terminal's virtual console.
`fb_device`	empty	The framebuffer. Empty finds the Sharp display by name.
`width`, `height`	`400`, `240`	The canvas. Every layout reads these.
`notes_open_last`	`false`	Open Notes on the last file instead of the list.

You rarely need to edit these by hand.

Key	Values
`display`	`white on black`, `black on white`, `auto`
`font_weight`, `font_size`	`regular` or `bold`; three sizes
`home_theme`	`grid`, `os8`, `win95`, `terminal`
`icon_size`	`large`, `small`
`light_off`	`10 s` to `5 min`, or never
`touch`, `touch_mode`	`slower`, `normal`, `faster`; `default`, `always on`, `enter only`
`auto_sync`	`15 min`, `30 min`, `60 min`, never
`lock_after`	immediately, `30 s`, `1 min`, `3 min`, `5 min`, never
`clock_hours`, `clock_face`	`24 h` or `12 h`; `full` or time only
`link_monitor`, `link_auto_fix`	`true`, `false`
`storefront_radius`	metres, default `300`