Installation and Trust

Installation and Trust

One-Bit Bureau installs a shell plugin and its matching theme, fonts, branding, command, and user state as one owned package. It requires a current Omarchy Quattro installation.

Verified install

Open bureau.regionallyfamous.com or the repository README, then paste the complete Verified install block into an Omarchy terminal.

The command is intentionally longer than the retired remote-shell shortcut. It performs five visible stages in order:

1. Downloads the GitHub release record to a temporary file without executing it.
2. Requires the requested version to be a published immutable GitHub Release.
3. Reads the release asset’s published SHA-256 digest, downloads the archive, and rejects any mismatch.
4. Extracts a commit-pinned Git bundle and verifies the bundled tag, full commit, manifest identity, version, and canonical origin.
5. Runs the now-local installer, which validates the staged plugin with Omarchy before installing the matching theme, fonts, branding, command, and plugin state.

Nothing downloaded is piped directly into a shell. The former /install and /i shell endpoints return 410 Gone so old commands fail closed instead of silently preserving the unsafe path.

Audit before activation

The installer source is release/install, the release-packaging source is scripts/build-release-artifact, and every release publishes SHA256SUMS beside the archive.

GitHub automatically creates a cryptographic release attestation when an immutable release is published. An authenticated GitHub CLI can inspect the release and downloaded asset:

gh release verify v1.2.4 --repo RegionallyFamous/one-bit-bureau
gh release verify-asset v1.2.4 /path/to/one-bit-bureau-v1.2.4.tar.gz --repo RegionallyFamous/one-bit-bureau

If an interrupted attempt left a disabled canonical checkout, the verified installer adopts it only when its full commit is exactly the commit recorded in RELEASE.json. A different, dirty, or mutable checkout is refused rather than updated implicitly.

Requirements

One-Bit Bureau relies on the tools supplied by a current Omarchy installation:

• Omarchy’s plugin and theme commands
• python3 with Gio bindings
• hyprctl
• jq
• Git and coreutils
• fontconfig

Run setup as your normal Omarchy user, never as root.

Runtime containment and local state

Every One-Bit Bureau helper runs through a local controller with an explicit total-runtime budget and separate stdout and stderr byte ceilings. On Linux, an independent subreaper guardian establishes the process boundary before releasing the helper, tracks nested descendants even when they create another session, escalates from TERM to KILL on a bounded schedule, and reaps the tree before the tracked controller reports completion. Over-budget output is discarded before it reaches the shared QML shell.

Dock choices and desktop positions live only under ~/.config/omarchy/one-bit-bureau/. One fixed-scope helper opens that private directory through owned no-follow descriptors, rejects symlinks and non-regular or multiply linked files, applies byte/record/key/depth limits, and commits changes with an exclusive private temporary file, file sync, descriptor-relative atomic replacement, and directory sync. The shell does not write these JSON files directly.

Conflicting plugins

Setup refuses to continue while any of these standalone plugins are enabled:

• henri.desktop-icons
• crmne.active-window
• expose.window-overview
• rosakodu.dock

They provide surfaces already owned by One-Bit Bureau. Disable them first so the shell does not load two desktops, docks, overviews, or active-window widgets.

What setup changes

• Installs and enables io.github.regionallyfamous.one-bit-bureau.
• Adds its active-application bar widget after the Omarchy menu.
• Installs and applies the one-bit-bureau theme as an owned link into the same commit-pinned plugin checkout.
• Places the bar at the top and makes it opaque.
• Installs both bundled fonts for the current user and refreshes fontconfig without changing the selected font.
• Backs up and replaces the user-level Omarchy About and screensaver branding.
• Installs the one-bit-bureau coordinator under ~/.local/bin/.
• Creates the configured XDG Desktop directory when it is enabled and missing. If XDG Desktop is explicitly disabled by mapping it to the home directory, setup preserves that state and does not recreate ~/Desktop.

Setup does not rewrite XDG_DESKTOP_DIR, input policy, or Hyprland bindings. Unlock branding ships as theme data and remains an explicit choice in Omarchy’s unlock picker; setup does not run privileged Plymouth or initramfs commands.

Ownership and rollback

Setup records exact ownership under:

~/.local/state/omarchy/plugins/io.github.regionallyfamous.one-bit-bureau/install-state.json

The outer installer removes a checkout it created if staging or setup fails. Once setup begins, its state record is written before each owned mutation, so its rollback can restore theme, bar, branding, fonts, command, and plugin state in reverse order. Removal changes only components that still match the recorded One-Bit Bureau-owned values. A branding file or command edited after installation is preserved instead of being overwritten or deleted.

Ownership records, the installed command, and the optional GTK3 preview use one shared transaction layer. It holds no-follow directory descriptors, validates opened objects by owner, type, mode, link count, identity, and recorded hash, writes through random exclusive temporary files, atomically replaces the validated name, and flushes both the file and directory. JSON and GTK theme trees have hard byte, depth, key, node, file, directory, and entry ceilings before their values can drive a mutation. Tree passes enumerate through a fresh descriptor-relative handle, so a platform-specific directory cursor cannot create an incomplete ownership hash. FIFOs, symlinks, hardlinks, oversized files, malformed state, and concurrently replaced objects fail closed.

Update

one-bit-bureau update

Update requires a clean canonical Git checkout. It reads the ownership record once as a bounded hash-bound snapshot, updates the plugin through Omarchy, updates or reconciles the recorded theme source, verifies that plugin and theme end at the same commit, and reapplies the theme only when it was already active. The command and revised ownership record are replaced only while the exact opened objects still match their recorded identities and hashes.

Remove

one-bit-bureau remove

Removal restores the previous theme, bar position, transparency, and branding only while One-Bit Bureau still owns the active values. It removes the owned plugin, theme, unmodified fonts, command, and ownership record.

Removal deliberately keeps user data:

• Files in the configured Desktop directory
• Dock pins and ordering
• Dock settings
• App-icon choices
• Custom icons
• Desktop object positions

Canonical identity

Item	Value
Repository	https://github.com/RegionallyFamous/one-bit-bureau.git
Plugin ID	io.github.regionallyfamous.one-bit-bureau
Theme	one-bit-bureau
User configuration	~/.config/omarchy/one-bit-bureau/
Ownership record	~/.local/state/omarchy/plugins/io.github.regionallyfamous.one-bit-bureau/install-state.json