omarchy-dev-bootstrap

Provision a fresh Omarchy install with my dev tooling. Standalone and Omarchy-focused — independent of my ~/dotfiles (which targets ML4W).

What it does

Runs eighteen idempotent modules (default order):

1. remove — uninstall unwanted Omarchy default package apps (config/remove-apps.txt) and web apps (config/remove-webapps.txt).
2. webapps — install selected Omarchy web app launchers (config/webapps.txt).
3. packages — install the few prerequisites Omarchy lacks (config/packages.txt) with pacman and AUR entries from config/aur-packages.txt with yay/paru, link the vendored Emacs config, and verify the preinstalled Docker.
4. shell — link the tracked dotfiles/.bashrc (aliases, prompt, tool launchers) over ~/.bashrc, backing up any existing file. Runs before ssh-agent so that module finds its fallback already in the tracked file.
5. ssh-agent — install openssh and enable a persistent socket-activated user agent (ssh-agent.socket plus ssh-add-keys.service), pointing every session at it via environment.d with a .bashrc fallback for plain ttys. Runs before repos because cloning needs GitHub SSH; a machine with no key yet still completes, with instructions to generate one and re-run.
6. docker-rootless — run a per-user Docker daemon (rootlesskit, slirp4netns, AUR docker-rootless-extras, a subordinate id range, then Docker's own setup tool) so container root maps to this user. pi-docker and kev-router use it. An existing user docker.service is left as it is and only enabled.
7. rclone — install/verify rclone, prepare ~/.config/rclone, link the current rclone-bisync user timer (~/Documents/dDocs ↔ gd_vault:myDocuments every 30 min), and optionally enable mounts listed in config/rclone-remotes.txt.
8. repos — clone my personal repositories (config/repos.txt, needs GitHub SSH), then symlink Pi agent skills from ~/Documents/10-repos/11-gitRepo/my-skills/skills/ into ~/.pi/agent/skills/.
9. claude-lifeos — graft the private Pcsf/claude-lifeos repository onto the ~/.claude that Claude Code creates on first run: system prompt, Algorithm, hooks, skills and settings.json. Credentials and history are excluded by design, so sign in normally afterwards.
10. pi-lifeos — build/link the pi-docker harness, install the host-owned private pi-lifeos package, and reuse an existing Claude LifeOS or fetch the pinned standalone public payload on a fresh machine. Copies the Pi extensions that jd loads from llama-model-manager/pi/extensions into ~/.pi/agent/extensions (copied, since a symlink dangles inside pi-docker).
11. lifeos-user — link the personal data tree cloned by repos at ~/.claude/LIFEOS/USER and ~/.claude/LIFEOS/MEMORY, so both agents read and write one tree.
12. hermes — restore the tracked Hermes configuration (hermes/) with bin/hermes-config-sync push, install the gateway user unit, and enable it once ~/.hermes/.env exists. The hermes-agent checkout itself is upstream code and is recorded in hermes/AGENT_PIN rather than vendored.
13. docker-envs — build the Dockerized FPGA/embedded dev-envs (stm32-dev, altera-dev-env, xilinx-dev-env, docker-files). License-gated vendor installers (Vivado/Quartus) are detected; builds are skipped with guidance when they are missing.
14. omarchy-plugins — install the Omarchy shell plugins listed in config/omarchy-plugins.txt (needs GitHub SSH), place each one in the bar, and restart the shell. Already-installed plugins are skipped, but the enable step always runs, so a reset shell.json gets its bar entries back.
15. llm — install llama.cpp-vulkan, run the versioned llama-model-manager installer, and enable the llama-server user service when registered models are found under ~/ai/models/managed (serves http://localhost:8080/). Also links the tracked voxtype drop-in that pins Whisper to the 890M iGPU, so the R9700 stays free for llama-server.
16. kev-router — serve the calibrated Kev-0.8B request router on the CPU: pin the Kev clone to 5920c5f, build kev-router:cpu from Pcsf/kev-router in the rootless daemon, fetch the base model with plain curl (sysOne-devOS/bench/src/hf-fetch.ts; the Hugging Face client stalls here), link the unit from the kev-router clone with a tracked paths drop-in, enable it, and switch router.enabled on in ~/.pi/agent/pi-lifeos.json and pi-devos.json. Answers on http://127.0.0.1:8009.
17. interpreter — serve the PT/NL/EN voice interpreter from the Pcsf/interpreter clone and publish it. Fetches Whisper ggml-large-v3-turbo.bin into voxtype's model directory directly (voxtype setup model would also switch the dictation daemon's model), installs Piper 2023.11.14-2 with pt-BR, nl-NL and en-GB voices into ~/.local/share/piper, runs bun install, and enables the app's user unit (127.0.0.1:3000). Translation uses the llama-server iGPU lane on :8081. Then links the tracked tunnel config and unit and starts Cloudflare Tunnel home (https://interpreter.ficagna.net, behind Cloudflare Access) when its credentials are present, and runs tailscale serve (https://home.<tailnet>.ts.net) once Tailscale is logged in. Re-run it after supplying either credential.
18. jarvis -- serve JARVIS, the Pi Durable chat agent from the Pcsf/pi-durable-bun clone: bun install, link its jarvis-web user unit, and start it once ~/.config/jarvis/web.env exists (the first start builds the jarvis-runtime image for its rootless container). It answers on http://127.0.71.1:3171 and, through the tunnel home started by interpreter, at https://jarvis.ficagna.net behind Cloudflare Access. Re-run it after restoring web.env.

Usage

On a machine with no credentials, read docs/CREDENTIALS.md first. The SSH key it describes is what git clone below needs, and what every later module depends on.

git clone [email protected]:Pcsf/omarchy-dev-bootstrap.git
cd omarchy-dev-bootstrap

./bootstrap.sh --dry-run        # preview everything, change nothing
./bootstrap.sh                  # run all modules
./bootstrap.sh --only llm       # run a single module
./bootstrap.sh --only webapps   # install selected custom web app launchers
./bootstrap.sh --only rclone    # install rclone and prepare/enable remote mounts
./bootstrap.sh --only pi-lifeos # build Pi and install the LifeOS package
./bootstrap.sh --only jarvis    # serve JARVIS once ~/.config/jarvis/web.env exists
./bootstrap.sh --skip remove    # run everything except removal

Customising

• config/remove-apps.txt — package apps to remove (@preinstalls removes all Omarchy defaults at once). All entries are commented out by default.
• config/remove-webapps.txt — web app launchers to remove by name (@webapps removes all Omarchy web apps at once). All entries are commented out by default.
• config/webapps.txt — web app launchers to install with omarchy-webapp-install. Omarchy defaults are listed but commented; custom launchers detected from this machine are active so a new install recreates them.
• config/packages.txt — extra pacman packages to install (only if missing).
• config/aur-packages.txt — extra AUR packages to install with yay/paru (only if missing).
• config/repos.txt — url dest-relative-to-$HOME [submodules]. The my-skills repo is expected at Documents/10-repos/11-gitRepo/my-skills so its skill directories can be linked into ~/.pi/agent/skills/. The llama-model-manager repo is cloned before the LLM module links its commands and user service. pi-lifeos is cloned at the same base path and installed as a local Pi package, so its source remains outside the Pi Docker image.
• config/rclone-remotes.txt — rclone remote names to mount at ~/cloud/<remote>. All entries are commented by default because ~/.config/rclone/rclone.conf contains secrets and is never stored in this repo.
• dotfiles/.bashrc — the interactive shell config, symlinked to ~/.bashrc, so editing ~/.bashrc edits this repo. Keep paths $HOME-relative. Edit it with a normal editor or >>: sed -i replaces the symlink with a plain file and silently drops it out of tracking.
• dotfiles/.config/emacs/ — vendored Emacs config linked into ~/.config/emacs/.
• dotfiles/.config/systemd/user/rclone-bisync.service + .timer and dotfiles/.local/bin/rclone-ddocs-bisync — current bidirectional sync from ~/Documents/dDocs to gd_vault:myDocuments every 30 minutes, with a guarded automatic --resync-mode path1 fallback only when the local folder is not empty.
• dotfiles/.config/systemd/user/[email protected] — reusable user-service template for mounting configured rclone remotes.

Pi + LifeOS setup

Three modules restore LifeOS, in order. claude-lifeos grafts the private Pcsf/claude-lifeos repository onto ~/.claude, which Claude Code creates on first run: the system prompt, the Algorithm, the hooks that enforce it, the skills and settings.json. Credentials, conversation history and caches are excluded by design, so sign in normally afterwards. lifeos-user clones the personal data tree to ~/.config/LIFEOS/USER and links it at ~/.claude/LIFEOS/USER and ~/.claude/LIFEOS/MEMORY; that one tree is the single source of truth both agents read and write, which is why a knowledge note written from Pi lands in the same file Claude reads.

The pi-lifeos module builds the pi-sandbox image when it is absent, links ~/.local/bin/pi-docker, and runs the private package's idempotent installer. On a new machine it also fetches the pinned public LifeOS runtime and creates an additive USER scaffold; existing ~/.claude/LIFEOS installations are reused and never upgraded automatically.

Launch Pi normally; pi-docker reads pi-lifeos.json and mounts the package, runtime, skills, and USER context read-only into the restricted sandbox:

pi-docker

Use pi-docker --local when Pulse on host port 31337 is needed. Then verify it inside Pi:

/lifeos doctor

Hermes setup

~/.hermes is 2.2 GB, and almost none of it is ours. hermes/ in this repository tracks the part that is: config.yaml, cron/jobs.json, the two personal scripts, and the whole skills library — about 9 MB.

Everything else is deliberately absent. The hermes-agent checkout is upstream code, so hermes/AGENT_PIN records its remote and commit instead of vendoring 1.9 GB. Conversation state, logs, caches and the installed binaries regenerate. Credentials never enter a repository — see docs/CREDENTIALS.md.

Configuration moves by copy, not by symlink, because Hermes rewrites config.yaml in place; a symlink at that path would be replaced by a regular file on the first rewrite and tracking would silently stop.

bin/hermes-config-sync status     # what differs between host and repository
bin/hermes-config-sync pull       # host -> repository, after changing settings
bin/hermes-config-sync push       # repository -> host, on a restored machine
bin/hermes-config-sync pin        # re-record the hermes-agent commit

Restoring on a new machine: install hermes-agent per the instructions in hermes/AGENT_PIN, then ./bootstrap.sh --only hermes. The module pushes the tracked configuration, installs the gateway unit, and enables the service only once ~/.hermes/.env exists — without it the gateway would crash-loop.

Rclone setup

This repo installs rclone and ships the current systemd user units, but it does not commit rclone.conf because that file can contain OAuth tokens.

Current mirrored usage from this machine:

• remote: gd_vault (drive)
• bisync: ~/Documents/dDocs ↔ gd_vault:myDocuments
• timer: 5 minutes after boot, then every 30 minutes
• recovery: if a normal timer sync fails, the helper retries with --resync-mode path1 only when ~/Documents/dDocs is non-empty; if the local folder is empty, it refuses the fallback to avoid deleting remote data.

On a new mini-PC:

# Option A: configure interactively
rclone config

# Option B: import an existing config from USB/secure backup
RCLONE_CONFIG_SOURCE=/path/to/rclone.conf ./bootstrap.sh --only rclone

To enable the mirrored dDocs bisync timer after gd_vault exists:

RCLONE_ENABLE_BISYNC=1 ./bootstrap.sh --only rclone

That command asks how to initialize the first bisync run:

• download — prefer/download gd_vault:myDocuments into ~/Documents/dDocs first; recommended for a new mini-PC.
• clean — prefer the current local ~/Documents/dDocs on initial resync; use carefully because it can overwrite/delete remote content.
• skip — link units only, do not enable the timer.

For non-interactive setup, set the answer explicitly:

RCLONE_ENABLE_BISYNC=1 RCLONE_BISYNC_INIT=download ./bootstrap.sh --only rclone

Optional mounts: uncomment remote names in config/rclone-remotes.txt and run ./bootstrap.sh --only rclone. Each active remote is mounted as ~/cloud/<remote> using systemctl --user enable --now rclone-mount@<remote>.service.

Prerequisites you must supply

Every credential below is covered in docs/CREDENTIALS.md — what it is, where it lives, and how to obtain or recreate it.

• GitHub SSH access (for repos, including the private Pcsf/pi-lifeos repository).
• Rclone remote credentials in ~/.config/rclone/rclone.conf (for mounted cloud remotes).
• Vivado/Vitis installed into ~/dev/fpga/xilinx_tools/ (for the Xilinx image).
• Quartus QuartusLiteSetup-*.run + *.qdz placed in the altera-dev-env repo (for the Altera image).
• GGUF model files registered through llama-model-add under ~/ai/models/managed/ (for the LLM). If none are found, the bootstrap skips starting llama-server until a model is added.
• Cloudflare Tunnel credentials in ~/.cloudflared/ and a Tailscale login (for the interpreter module to publish the app). The Cloudflare Access application lives in the Zero Trust dashboard, not on this machine.