# T1Bridge prerelease: agent setup guide for Omarchy

> [!CAUTION]
> **STOP BEFORE PARTITIONING: PRESERVE THIS MAC'S APPLE EFI DATA.**
> Keep the Apple EFI partition and verify a separate backup on another device
> contains `EFI/APPLE/EMBEDDEDOS/FDRData`, before installing Linux or formatting
> partitions. Normal Touch ID setup needs original or recovered same-Mac data. Another Mac's data, reinstalling packages, and re-enrolling
> fingerprints are not substitutes.
>
> **Recovery is possible:** restore macOS on this Mac through a complete first
> boot to regenerate the data. Merely booting Recovery or downloading an installer
> is not enough. Verify and back up `EFI/APPLE/EMBEDDEDOS/FDRData` before returning
> to Linux. Obtain owner approval and back up Linux data first; restoration can
> erase it.

Updated September 20, 2026. Give this document to the coding agent running on the target Mac.

## Mission and boundaries

Take a working Omarchy installation on a supported T1 Mac from package access to a working default Touch Bar and verified Touch ID. Configure Omarchy integration separately. Preserve password access throughout.

T1Bridge is open source at [standardagents/t1bridge](https://github.com/standardagents/t1bridge). Downloads are public: no token, Cloudflare account or GitHub access is needed. Install the existing signed packages; do not rebuild them. The [README](https://github.com/standardagents/t1bridge#readme) lists official support and installation instructions. Exact corresponding source and recipes are also available beside the packages.

Proceed independently through inspection and downloads. Ask before rebooting, starting a fingerprint scan, changing authentication policy or making a destructive change. For scans, name the finger/action and wait for readiness before starting the timer. Maintain a short local checkpoint log so reboot or context loss does not restart the investigation.

Never share EFI contents, calibration, keybags, xART records, biometric data, serials or private keys. Never copy another Mac's machine data. Do not erase enrollments, reset USB, hot-unload T1 modules or install a historical PoC as a repair shortcut.

v0.1.6 includes the binary-plist import fix, enrollment authorization troubleshooting, and automatic relay restart backoff from 2s to 60s. The backoff reduces a persistent restart storm; it does not establish a fix for the underlying SEP failure or change the downstream lock-screen retry timer.

v0.1.7 adds opt-in relay keystore reply diagnostics for #14: the supported operation selector and validated remote error status, without handles or payloads. This is evidence collection, not a root-cause fix. Enable diagnostics for the next normal service start or planned boot; do not trigger repeated authentication or hardware resets to reproduce the failure. See [the diagnostic guide](https://github.com/standardagents/t1bridge/blob/main/docs/diagnostics.md#sustained-keybag-relay-restarts).

v0.1.9 fixes enrollment when the keybag relay is already in systemd's failed
state. It still requires successful bootstrap and an active relay; it does not
resolve #14's native keystore errors. Optional integration 0.2.1 rejects foreign
or ambiguous sensors and discards stale readings after sensor/proxy changes,
lock/unlock and monitor backlog.

v0.1.10 fixes the reproduced automatic-import mount-namespace failure without weakening the service sandbox. It also ships display-off handling for compatible Touch Bar desktop providers, held-input cancellation, failed-resume reprobe handling, and SEP cleanup diagnostics. These changes do not establish system suspend or dark-panel recovery. Reporter confirmation of the import fix remains pending. See [release notes](https://github.com/standardagents/t1bridge/blob/v0.1.10/docs/release-0.1.10.md).

v0.1.12 packages experimental native online recovery, with no external restore
stack. Preserve and import local EFI or a verified same-Mac backup first.
Online recovery is attended, never runs during installation/upgrades, and
requires a machine already in recovery mode. Real-device acceptance remains
open in [#43](https://github.com/standardagents/t1bridge/issues/43).
See [native recovery](https://github.com/standardagents/t1bridge/blob/v0.1.12/docs/linux-recovery.md).

v0.1.11 frees a display-information buffer after failed sends and adds opt-in,
fixed-field display reply diagnostics. Optional integration 0.2.2 supplies
automatic graphical-session startup. Display timeouts, dark-panel recovery and
cold-login acceptance remain open; these packages do not establish those
hardware outcomes. See the [v0.1.11 release notes](https://github.com/standardagents/t1bridge/blob/v0.1.11/docs/release-0.1.11.md).

## 1. Inspect the target

Use the owner's normal account in the local graphical session, not root or SSH alone:

```bash
id -un
uname -m
uname -r
cat /sys/class/dmi/id/product_name
cat /etc/os-release
dkms status
pacman -Q t1bridge t1bridge-dkms libfprint-t1bridge fprintd-t1bridge
systemctl --failed --no-pager
```

Missing packages are expected initially. These packages target **x86_64 Arch Linux/Omarchy with systemd**, not Ubuntu/Mint and not T2 Macs. Hardware targets: MacBookPro13,2, MacBookPro13,3, MacBookPro14,2 and MacBookPro14,3 — 2016/2017 Intel Touch Bar models. Success is confirmed on two MacBookPro13,3 machines. A MacBookPro13,2 tester confirmed Touch Bar, two-finger enrollment/verification, reboot persistence and configured PAM consumers on v0.1.1. A MacBookPro14,3 tester confirmed enrollment after permitting private xART traffic and a full shutdown/power-on on the unchanged packaged build; broader coverage is not established. A [MacBookPro14,2 tester](https://github.com/standardagents/t1bridge/issues/2#issuecomment-5563782774) reported Touch Bar, enrollment/verification, sudo and lock authentication on v0.1.1. Camera was not tested; lid resume failed and a relay restart loop remains unresolved. See the public README for exact limits; do not assume all T1 functions have passed on every model.

Read local machine instructions. Check AC power, disk backup, boot-partition free space, kernel/header packages, existing T1 services/DKMS overrides, firewall and PAM. If another stack owns the T1, identify it and plan a safe transition; do not blindly remove DKMS modules or rebind the device live.

Locate this Mac's preserved Apple EFI partition or a backup containing `EFI/APPLE/EMBEDDEDOS/FDRData`. Preserve it. If it is missing, restoring macOS on this Mac through a complete first boot can regenerate it; an installer archive alone is not a calibration backup. Arrange that recovery with the owner rather than initiating it automatically. Missing Apple data blocks Touch ID, but not necessarily Touch Bar-only testing.

**Stop** on unsupported hardware, an unresolved competing stack, missing recovery/password access, or failed prerequisites. Do not proceed through the remaining steps hoping they repair it.

## 2. Verify the key and configure pacman

Expected primary signing fingerprint:

```text
35B166F78B063B04DE1E3D913E6C4216EB03D371
```

Confirm this fingerprint against the maintainer's trusted handoff, not merely the downloaded key's name. From a normal shell:

```bash
candidate_dir=$(mktemp -d)
cd "$candidate_dir"
repo_url=https://linux.standardagents.ai/arch/standardagents/x86_64
curl -fSLo t1bridge-signing-key.asc "$repo_url/t1bridge-signing-key.asc"
gpg --show-keys --with-fingerprint t1bridge-signing-key.asc
```

Only after an exact primary-fingerprint match:

```bash
sudo pacman-key --add t1bridge-signing-key.asc
sudo pacman-key --lsign-key 35B166F78B063B04DE1E3D913E6C4216EB03D371
```

Back up `/etc/pacman.conf`; add this stanza once without removing existing repositories:

```ini
[standardagents]
SigLevel = Required DatabaseRequired
Server = https://linux.standardagents.ai/arch/$repo/$arch
```

Keep `$repo` and `$arch` literal: pacman expands them. Never disable signature checks, use `TrustAll`, or request signing secrets/download credentials.

## 3. Install the matched candidate

| Package | Version | Purpose |
| --- | --- | --- |
| t1bridge | 0.1.12-1 | Services, importer, broker, default Touch Bar, experimental native recovery |
| t1bridge-dkms | 0.1.12-1 | Configuration, display, network, camera and guarded recovery reset |
| libfprint-t1bridge | 1.94.100-20 | T1Bridge fingerprint driver |
| fprintd-t1bridge | 1.94.5-17 | Matched daemon, tools and pam_fprintd |

The fingerprint pair replaces distro libfprint/fprintd **system-wide** and must stay matched. Do not install stock or `-git` replacements afterward. Only the first two packages are needed for Touch Bar-only use.

Obtain owner approval for the full system update, which may update the kernel and other packages. On Omarchy, use its updater first; the direct `pacman -Syu` guard is intentional:

```bash
omarchy update
sudo pacman -S --needed linux-headers t1bridge t1bridge-dkms libfprint-t1bridge fprintd-t1bridge
```

Proceed to installation only after the updater succeeds. On plain Arch with the standard `linux` kernel, use `sudo pacman -Syu --needed linux-headers t1bridge t1bridge-dkms libfprint-t1bridge fprintd-t1bridge`. Never substitute `pacman -Sy`.

For another kernel, choose its actual matching headers first; other kernels are outside the current hardware-tested claim. Read replacement prompts: replacing stock libfprint/fprintd is intended, unrelated removal is not. Do not force conflicts with `--noconfirm`, `--overwrite` or dependency-skipping flags. Do not perform a partial system upgrade.

DKMS compiles modules for the target kernel during normal installation; this is not rebuilding the published packages. Verify both DKMS and initramfs/UKI hooks, not only pacman's exit code:

```bash
pacman -Q t1bridge t1bridge-dkms libfprint-t1bridge fprintd-t1bridge
sudo pacman -Qkk t1bridge t1bridge-dkms libfprint-t1bridge fprintd-t1bridge
dkms status
```

Record versions. If a newer candidate is offered, obtain its updated notes rather than treating it as these exact artifacts. Stop on signature, dependency, DKMS or boot-image failure; do not reboot into a knowingly broken boot image.

## 4. Enable the hardware stack, then reboot

From the normal account:

```bash
sudo systemd-sysusers /usr/lib/sysusers.d/t1bridge.conf
sudo systemd-tmpfiles --create /usr/lib/tmpfiles.d/t1bridge.conf
sudo usermod -aG t1bridge "$(id -un)"
sudo systemctl daemon-reload
sudo systemctl enable t1-touchbar-hw.service t1-touchid-auth.socket t1bridge-fingerprint.socket
```

Save the checkpoint and arrange an owner-approved reboot. Do not substitute a USB reset or live driver swap. After the owner returns to the local graphical session:

```bash
id -nG
systemctl --user daemon-reload
systemctl --user enable --now t1-touchbar.service
sudo t1bridge status
systemctl --failed --no-pager
```

Require `t1bridge` group membership. Read every status row: selected USB configuration and ready DRM/NCM/xART/Touch Bar are expected. A successful status exit does not mean all rows are ready. On a fresh machine, `keybag: not-enrolled` is legitimate before first enrollment. An idle socket-activated broker need not run continuously.

NCM/xART are device-driven. Do not enable the keybag relay as an unconditional boot service; first enrollment bootstraps it. Compare loaded `/sys/module/MODULE/srcversion` with `modinfo -F srcversion MODULE` for `t1_cfgsel`, `appletbdrm`, `apple_t1_ncm` and `uvcvideo`. Services should execute `/usr/lib/t1bridge/` binaries, not a checkout or temporary override. Preserve existing custom renderer selection; ask before replacing it with the default.

One shared-keybag preparation failure followed by a successful configured relay restart has been observed. Record it. A restart loop or continued failure is not a pass.

**Before enrollment, inspect the xART firewall prerequisite.** The dynamically discovered private T1 NCM interface needs IPv6 TCP 61500 inbound from the validated T1 peer. Never open that port globally or copy another machine's interface/address into a rule. Keep IPv6 enabled on this link. A default-deny firewall caused first-attempt enrollment timeouts and subsequent immediate failures for testers even while `xart: ready` was reported. Service readiness is not proof of network reachability. With opt-in diagnostics enabled, `xart-admission` reports evidence from this boot. v0.1.3 distinguishes missing or capped xART logs from a recorded attempt without admission. Enabling broker logging does not enable an already-running xART process. Missing logs do not prove a firewall failure; do not change working rules or restart hardware just to obtain logs.

## 5. Import this Mac's Apple data

No fingerprint operation should be active. For an attached preserved Apple EFI partition:

```bash
sudo systemctl start t1bridge-import.service
sudo systemctl status t1bridge-import.service --no-pager
sudo journalctl -u t1bridge-import.service -n 30 --no-pager
```

The sandboxed oneshot reads matching EFI data without modifying the source. A successful oneshot may subsequently be inactive; inspect its exit result. It stores only a live-sensor-matched record under root-only `/var/lib/t1bridge/machine-data/`.

For a backup, substitute its actual absolute path:

```bash
sudo t1bridge machine-data import --from /absolute/path/to/efi-backup
```

The directory must contain `EFI/APPLE/EMBEDDEDOS/FDRData`; passing that file directly also works. A read-only mounted preserved EFI filesystem is acceptable. No symlink component, special file, compressed backup or installer/disk-image container is accepted. Do not repartition or format anything to obtain a source.

Do not pass the intermediate `EMBEDDEDOS` directory: pass the EFI-tree root or the actual `FDRData` file. Successful import returns silently with exit status 0. v0.1.2 fixed the service's temporary-directory sandbox mismatch. v0.1.4 introduced a private read-only view for already-mounted ESPs; v0.1.5 fixes opening that view under the packaged service's syscall restrictions. Original mount flags remain unchanged. v0.1.6 also accepts valid binary plists with three-byte offsets (PR #16), fixing a separate FDRData parsing failure. v0.1.10 refreshes the storage root after EFI discovery changes mount namespaces, fixing the reproduced exit-30 temporary-file failure. The explicit same-machine backup route remains available; do not repartition or delete data to work around an import failure.

Stop on wrong-machine or conflicting data. A busy/unavailable sensor is not permission to overwrite calibration: wait for the active fingerprint operation to finish and retry while idle. Do not delete protected state or invent missing records.

## 6. Enroll and verify using standard fprintd

Use the normal target account and its desktop Polkit agent, not root:

```bash
fprintd-list "$(id -un)"
```

If prints already exist, preserve them and verify one; enrollment is not required just to check a box. Otherwise ask which finger to enroll. After readiness, for example:

```bash
fprintd-enroll -f right-index-finger
```

Authorization may require the account password. Explain when authorization ends and capture begins. Repeatedly lift and touch the same chosen finger. The backend allows three identities for one Linux owner. Duplicate/full responses are not permission to clear storage or change owners.

If `EnrollStart failed: Timeout was reached` appears, inspect `journalctl -b -u fprintd --since "5 minutes ago" --no-pager` locally for `Authorization denied`. Enrollment needs an interactive Polkit agent; retry from a graphical desktop terminal and complete its authorization prompt before changing firewall rules. Do not use sudo enrollment to bypass policy or share full journals.

Require `enroll-completed`, then confirm the label with `fprintd-list`. Arrange a separate ready window and verify the actual enrolled label:

```bash
fprintd-verify -f right-index-finger
```

Require **`verify-match`**, not merely exit 0 or a Touch Bar checkmark. To cancel verification, press the visible prompt on the OLED Touch Bar, not the separate physical sensor. v0.1.3 sends cancellation on finger-down, not again on release. Record cancellation/failure honestly. Do not use direct development enrollment/matching commands or legacy recovery utilities for setup.

**Omarchy wizard trap:** installed versions may fail to detect T1, request stock libfprint/fprintd or always enroll another finger. Inspect the installed setup command before using it. Do not blindly run it after installing this matched pair. The standard tools above are the fallback. The custom enrollment TUI and menu improvements are not included in these packages.

## 7. Enable sudo, Polkit and lock-screen authentication safely

This is a separate owner-approved policy change. fprintd enrollment does not configure PAM automatically. Follow the [Omarchy Quickshell unlock instructions](https://github.com/standardagents/t1bridge/blob/v0.1.10/docs/setup.md#omarchy-lock-screen-unlock) for the separate fingerprint PAM service and password-fallback checks.

Back up the exact PAM files, prove password authentication and keep a persistent root recovery shell open in another terminal. Cached sudo, passwordless sudo and running as root do not prove password fallback. Preserve existing valid configuration.

Prefer the installed Omarchy setup path only after confirming it preserves the matched packages and does not force duplicate enrollment. Otherwise, using `man pam_fprintd` and the actual installed stacks:

- Add fingerprint as an optional successful authentication path for sudo and `/etc/pam.d/polkit-1`, preserving password, account, session and access checks. The usual line is `auth sufficient pam_fprintd.so`; inspect ordering first, never replace the entire stack with it.
- Retain Omarchy's lid-closed skip only when its installed helper exists and the skip count matches the resulting stack. Do not duplicate gates or fingerprint prompts. A legacy `pam_t1_touchid` configuration requires a reviewed, password-safe migration, not another module stacked on top.
- Inspect the actual lock implementation. Current Quickshell Omarchy uses separate `omarchy-lock-fingerprint` and `omarchy-lock-password` PAM services. The former uses `auth required pam_fprintd.so` and `account include system-local-login`. Preserve the password service. Older implementations may use different names.
- Stage complete files, review the diff, preserve ownership/mode and replace each atomically. Use bounded attempts/timeouts; a serial PAM conversation can delay password entry until fingerprint times out.

With the owner ready, test sudo fingerprint, a real Polkit authorization and lock/unlock separately. Test password fallback separately for each with the broker unavailable under a bounded recovery plan. Keep the root shell, prevent broker socket reactivation as well as stopping the service during that test, and always restore prior unit states afterward. Never stop the graphical session or reset T1 hardware for it.

Do not close recovery access until both password and fingerprint paths work. If downstream lock support is incompatible, retain password login and report the missing integration rather than claiming fprintd success proves lock support. Screen-blank/wake prompt behavior also needs its own test.

## 8. Connect Omarchy controls and HUDs

Install the official optional package after the approved system update:

```bash
sudo pacman -S --needed t1bridge-omarchy
```

The package installs its own desktop provider and a user-service drop-in. It
preserves custom renderer selection and does not replace Omarchy commands, PAM
or user configuration. Inspect existing user drop-ins for provider overrides.

Version 0.2.2 uses package-owned XDG autostart after graphical-session readiness.
It skips a renderer start with an absent/empty display environment, then starts
or restarts only an enabled renderer. Disabled/masked units stay disabled.
No per-user hook is required. Cold-login hardware acceptance remains pending.

After upgrading, log out and back in, or run from the active graphical session:

```bash
/usr/lib/t1bridge-omarchy/session-start --autostart
/usr/lib/t1bridge-omarchy/desktop-provider v1 status
```

If you created the old manual hook, inspect it with
`readlink "$HOME/.config/omarchy/hooks/post-boot.d/40-t1bridge-omarchy"`.
Remove it with `unlink` only if it points to
`/usr/lib/t1bridge-omarchy/session-start`, to avoid a second login restart.
Keep unrelated hooks.
Read `/usr/share/doc/t1bridge-omarchy/README.md` for current integration details.

With the owner ready, test actual Touch Bar buttons: volume/mute, display and
keyboard brightness, Fn/F-keys, hold-repeat and the corresponding HUDs. Test
media with a real player. Check again after the next approved reboot/login;
a command-triggered popup or one service restart does not prove persistence.

## 9. Handoff and recovery

Keep a short checklist: model/kernel/package versions, signed installation and boot-hook results, candidate drivers/services after reboot, import result, preserved/new enrollment, standard match, each PAM consumer and its password fallback, physical controls/HUDs and next-login behavior. Camera capture is a separate test requiring owner awareness. Mark every untested item pending.

Diagnose using `sudo t1bridge status`, service status, `dkms status` and bounded relevant journals. Share only redacted logs, not machine identifiers or protected data. Stop guessing on failure; do not invoke USB-cycle, deletion or legacy commands as generic repairs.

For rollback, keep the working password/root shell, restore reviewed PAM backups and a trusted prior matched package set through pacman, then let DKMS/boot-image hooks finish before an approved reboot. Preserve `/var/lib/t1bridge` and Apple EFI data. Never disable signatures to force rollback.

## Exact candidate and source references

Release source: signed tag `v0.1.12`. See the [release page](https://github.com/standardagents/t1bridge/releases/tag/v0.1.12)
for the exact source commit and validation evidence.

The same download directory contains the public key, signed packages/databases,
`SHA256SUMS` and its signature, matching PKGBUILDs, fingerprint patches,
`t1bridge-0.1.12.tar.gz` and `t1bridge-omarchy-0.2.2.tar.gz`. Verify the manifest
signature with the trusted key, then source checksums before extracting as a
normal user. The signed manifest also covers this guide. Read source
`docs/setup.md`, `docs/interfaces.md`, `docs/touch-id.md` and
`docs/hardware-validation.md`.

Record the actual checks completed on the target machine; publication does not
prove every hardware or desktop configuration.

## Ambient-light sensing and optional automatic brightness

T1Bridge 0.1.8 and later require the stock `iio-sensor-proxy` package for standard
desktop light-sensor discovery. On the tested MacBookPro13,3 the stock HID/IIO
sensor driver works in T1 USB configuration 2. There is no additional Apple
ALS module to install. Use `monitor-sensor --light` to inspect readings.

The official repository now also contains `t1bridge-omarchy 0.2.2-1`. Install
it for optional media/HUD integration and automatic panel brightness:

```bash
sudo pacman -S --needed t1bridge-omarchy
systemctl --user enable --now t1bridge-auto-brightness.service
```

Automatic brightness is a user preference and is not enabled by package
installation. Disable it with
`systemctl --user disable --now t1bridge-auto-brightness.service`.
It starts from current brightness, moves gradually with ambient light and
adopts manual changes as a new reference after a 30-second pause. The reference
is not persisted across boots. It controls panel brightness only.

Attended local tests confirmed dim/brighten response, manual 100% retention,
healthy operation after lock/unlock, and automatic service startup after reboot.
The locked interval itself, other models, and concurrent camera/authentication
acceptance are not established. T1 system suspend and runtime power saving
remain unsupported. See the package's installed README for media/HUD session
setup and exact behavior; no PAM or user configuration is replaced.

The optional package's corresponding source is `t1bridge-omarchy-0.2.2.tar.gz`
and its recipe is `t1bridge-omarchy.PKGBUILD`, served beside the signed packages.
The repository index and signed SHA256SUMS cover the complete five-package
cohort. Keep all entries when publishing future core or optional updates.