Omarchy is a pleasure as a daily driver. It is still a bad place to run a security PoC.

omarchy dev link is how you develop Omarchy: it points the running desktop at a checkout after reboot. Use it. The problem is not the link. The problem is running an untrusted plugin, a lock-screen reproducer, or a half-written shell against the session you are sitting in. If Quickshell dies, you are debugging a black screen with the same machine that just died.

I wanted a second Omarchy I could break, snapshot, and hand to a coding agent. A KVM guest on the same PC, driven from the host over SSH.

flowchart LR
  agent["Host AI
Claude / Codex / Grok"]
  virsh["virsh"]
  ssh["SSH + key"]
  guest["Omarchy lab VM"]

  agent --> virsh
  agent --> ssh
  virsh --> guest
  ssh --> guest
  guest --> pocs["PoCs, patches, tests"]

The host keeps the editor and the agent. The guest is where omarchy dev link and the reproducers run. The agent can start the VM, copy a checkout, run a PoC, take a screenshot, and roll the disk back. A wedged guest is reset. The host session stays up.

Check for KVM

This is the same class of guest the official ISO acceptance harness already uses: OVMF, Q35, cpu host, virtio disk/nic/vga.

Check the host before installing anything:

lscpu | grep -E 'Virtualization|Model name'
ls -l /dev/kvm

You want AMD-V or VT-x, and a /dev/kvm node. Nested KVM is a bonus (cat /sys/module/kvm_amd/parameters/nested or kvm_intel), not a requirement.

1. Hypervisor on the host

On Omarchy:

omarchy pkg add qemu-full libvirt virt-manager virt-viewer dnsmasq edk2-ovmf cdrtools swtpm
sudo usermod -aG libvirt,kvm "$USER"
sudo systemctl enable --now libvirtd.service
sudo virsh net-start default
sudo virsh net-autostart default

Omarchy's host firewall is on by default (INPUT and FORWARD drop). The default NAT lives on virbr0; without an allow, the guest's DHCP never reaches dnsmasq and you get a link-up ethernet with only an fe80: address.

Do not ufw allow in on virbr0 with no port. That lets the guest hit every host service bound on 0.0.0.0 (SSH, epmd, a local Tableau, …). Do not ufw route allow in on virbr0 with no egress interface either: that forwards the guest onto your LAN. Open only DHCP/DNS to the bridge, and forward only toward the uplink (here wlp9s0 — use ip -o route show default):

WAN=$(ip -o route show default | awk '{print $5; exit}')

# DHCP discover is broadcast to 255.255.255.255:67, not 192.168.122.1.
# A destination-restricted rule never matches, and UFW then drops port 67.
sudo ufw allow in on virbr0 proto udp to any port 67 comment 'libvirt dhcp'
sudo ufw allow in on virbr0 to 192.168.122.1 port 53 proto udp comment 'libvirt dns'
sudo ufw allow in on virbr0 to 192.168.122.1 port 53 proto tcp comment 'libvirt dns'
sudo ufw route allow in on virbr0 out on "$WAN" comment 'libvirt nat'

Return traffic is already RELATED,ESTABLISHED. Host → guest SSH is outbound from the host and does not need an extra INPUT rule.

If the guest already booted into that hole, bounce the libvirt network once so NAT masquerade reinstalls, then reconnect ethernet in the guest (nmcli -w 15 device connect enp1s0, or Super+Ctrl+W). For a PoC that should not phone home, skip the route allow and leave FORWARD dropped.

Log out and back in so the groups apply. newgrp libvirt is enough for the current shell.

Unprivileged virsh and virt-install default to qemu:///session, which has no NAT named default. Pin the system URI so they match the network you just started:

mkdir -p ~/.config/libvirt
printf 'uri_default = "qemu:///system"\n' > ~/.config/libvirt/libvirt.conf

Confirm you can talk to system libvirt without sudo:

virsh uri   # qemu:///system
virsh list --all

2. ISO

Pin a release, then check the hash. At the time of writing that is 4.0.2:

mkdir -p ~/VMs/omarchy-lab
cd ~/VMs/omarchy-lab
curl -LO https://iso.omarchy.org/omarchy-4.0.2.iso
curl -LO https://iso.omarchy.org/omarchy-4.0.2.iso.sha256
sha256sum -c omarchy-4.0.2.iso.sha256

Grab a newer ISO from omarchy.org when one ships. The VM shape below does not change.

3. Create the guest

This matches the official unattended-install / ISO-test shape, plus a software TPM:

virt-install is a Python script with #!/usr/bin/env python3. If mise (or pyenv) puts another Python first on PATH, it will fail with No module named 'gi'. Call the system interpreter explicitly:

qemu:///system runs QEMU as libvirt-qemu. A 700 home directory is correct; do not punch a search ACL through it. That user would then be able to read every 644 file under any 755 directory in $HOME (typical with umask 022: ~/.config, ~/.aws, ~/Work, …). Keep the disk and ISO in libvirt's image pool instead:

sudo mkdir -p /var/lib/libvirt/images
sudo qemu-img create -f qcow2 /var/lib/libvirt/images/omarchy-dev.base.qcow2 80G
sudo mv ~/VMs/omarchy-lab/omarchy-4.0.2.iso /var/lib/libvirt/images/

/usr/bin/python3 /usr/bin/virt-install \
  --connect qemu:///system \
  --name omarchy-dev \
  --memory 16384 \
  --vcpus 8 \
  --cpu host-passthrough \
  --machine q35 \
  --os-variant archlinux \
  --boot loader=/usr/share/edk2/x64/OVMF_CODE.4m.fd,loader.readonly=yes,loader.type=pflash,nvram.template=/usr/share/edk2/x64/OVMF_VARS.4m.fd \
  --tpm backend.type=emulator,backend.version=2.0,model=tpm-crb \
  --disk path=/var/lib/libvirt/images/omarchy-dev.base.qcow2,format=qcow2,bus=virtio,cache=writeback,discard=unmap \
  --cdrom /var/lib/libvirt/images/omarchy-4.0.2.iso \
  --network network=default,model=virtio \
  --graphics spice \
  --video virtio \
  --channel spicevmc \
  --input tablet,bus=usb \
  --noautoconsole

Open the console:

virt-viewer --attach omarchy-dev

Give it 8 vCPUs and 16 GiB if the host can spare them. Under-spec guests make Hyprland look broken when the firmware was the actual problem.

Installer settings that matter

Encryption is the right default on a laptop you can lose. It is the wrong default on a disposable VM whose job is "boot, run the PoC, revert."

Walk the wizard, pick a dedicated lab user (lab) and a password you will type once (lab is fine), and stay on the desktop when it reboots. A NAT guest often geo-guesses a nonsense timezone (Africa/Abidjan here); fix it later with timedatectl set-timezone. After a successful install the CDROM is often already empty. Confirm with virsh dumpxml omarchy-dev | grep -A6 cdrom. If the ISO is still attached:

virsh change-media omarchy-dev --eject --path /var/lib/libvirt/images/omarchy-4.0.2.iso || true

The --tpm flag is libvirt starting swtpm. After first boot you should have /dev/tpm0 and /dev/tpmrm0. tpm2-tools is not on a stock ISO; install it in the guest if you need tpm2_getcap. Do not pass through the host's /dev/tpm0. Emulator state lives under /var/lib/libvirt/swtpm/ on the host. omarchy-lab reset does not wipe that directory.

4. SSH that an agent can use

The guest should still be on the desktop from step 3. If you already powered it off, virsh start omarchy-dev and log in as lab.

Stock Omarchy ships OpenSSH disabled and the port closed. That is correct on a real machine. On the lab it is the whole point of the guest.

Inside the guest, once, as the lab user:

mkdir -p ~/.ssh
chmod 700 ~/.ssh
# paste the host's lab key, not your GitHub key
nano ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

echo "$USER ALL=(ALL) NOPASSWD: ALL" | sudo tee /etc/sudoers.d/lab
sudo chmod 440 /etc/sudoers.d/lab

sudo systemctl enable --now sshd
sudo ufw allow from 192.168.122.1 to any port 22 proto tcp

Passwordless sudo is a lab convenience. Agents hang on a password prompt. Do not copy this to the host.

Unencrypted Omarchy still stops at SDDM. For an agent that reboots the guest, autologin the lab user (encrypted installs already do this; LUKS is the gate):

printf '[Autologin]\nUser=lab\nSession=omarchy.desktop\n' | sudo tee /etc/sddm.conf.d/autologin.conf

That is lab-only. A machine without LUKS and with autologin is unlocked on the couch.

On the host, a key that exists only for this VM:

ssh-keygen -t ed25519 -f ~/.ssh/omarchy-lab -C omarchy-lab -N ""

Put ~/.ssh/omarchy-lab.pub in the guest authorized_keys you just edited. Then a host SSH config:

Host omarchy-lab
  User lab
  IdentityFile ~/.ssh/omarchy-lab
  IdentitiesOnly yes
  StrictHostKeyChecking accept-new
  UserKnownHostsFile ~/.ssh/omarchy-lab.known_hosts
  ControlMaster auto
  ControlPath ~/.ssh/cm-%r@%h:%p
  ControlPersist 10m

Leave HostName out until you know the lease. Then:

virsh domifaddr omarchy-dev --source lease

Add HostName 192.168.122.N once it is stable, or let the wrapper below fill it in.

The installer can do the key and sshd part for you if you attach a cidata volume with authorized_keys. That is the unattended install path. For a single lab VM, pasting one key by hand is less work than synthesizing a valid user_configuration.json.

5. Gold image, then throwaway overlays

Do not freeze gold until SSH, passwordless sudo, and autologin all work. That packaged disk is what reset returns — not a checkout. Then shut the guest off and keep omarchy-dev.base.qcow2. virsh shutdown will not do it: Omarchy sets HandlePowerKey=ignore, so use sudo systemctl poweroff in the guest or virsh destroy from the host. Each experiment then dev links the checkout under test on an overlay, and reset returns you to stock.

Every experiment is an overlay, the same trick the ISO test harness uses. Create it through libvirt so you do not need sudo on /var/lib/libvirt/images. The pool name is whatever owns that path (images-1 on this host — check with virsh pool-list and virsh pool-dumpxml):

virsh vol-create-as images-1 omarchy-dev.qcow2 80G --format qcow2 \
  --backing-vol omarchy-dev.base.qcow2 --backing-vol-format qcow2

Point the domain at the overlay (guest must be off):

virsh dumpxml omarchy-dev > /tmp/omarchy-dev.xml
# change the disk source file to omarchy-dev.qcow2
virsh define /tmp/omarchy-dev.xml
virsh start omarchy-dev

After that, reset is omarchy-lab reset, which deletes and recreates the overlay volume.

A wrecked compositor, a half-applied patch, a plugin that wedged Quickshell: delete the overlay. The gold image does not move.

6. What the guest is allowed to see

This is the security-sensitive part. A shell plugin on Omarchy runs as your user. If you virtiofs-share $HOME into the guest, a PoC that reads files is reading the host.

Rules that have held up:

• Do not share the host home, ~/.config, ~/.ssh, ~/.gnupg, or 1Password sockets.
• Do not run the reproducer against the host session, even if that session is also dev linked.
• Do not bridge the guest onto the LAN. libvirt NAT is one-way enough: the guest can fetch packages, nothing on the LAN can dial in.
• Do not put your GitHub org key in the guest. A deploy key limited to your Omarchy fork, or HTTPS + a fine-grained token, is enough.
• Do not turn Tailscale on in the guest while you are running a network-facing reproducer.
• Share at most one directory: a dedicated checkout, for example ~/Work/omarchy-lab on the host. rsync is simpler and easier to reason about than virtiofs.

Copy work in, run it, copy artifacts out. That is the whole data path.

7. A wrapper the host AI can call

Agents are good at running a small CLI and bad at improvising libvirt XML. Put this on the host as ~/VMs/omarchy-lab/bin/omarchy-lab and symlink it onto PATH:

#!/usr/bin/env bash
# Drive the disposable Omarchy KVM from the host.
set -euo pipefail

NAME=omarchy-dev
CONNECT=qemu:///system
USER=lab
KEY="${HOME}/.ssh/omarchy-lab"
POOL="${POOL:-}"
BASE_VOL=omarchy-dev.base.qcow2
OVERLAY_VOL=omarchy-dev.qcow2
SCREEN_DIR="${HOME}/VMs/omarchy-lab/screens"

virsh() { command virsh --connect "$CONNECT" "$@"; }

if [[ -z $POOL ]]; then
  while read -r p; do
    [[ -n $p ]] || continue
    if virsh pool-dumpxml "$p" 2>/dev/null | grep -q '/var/lib/libvirt/images</path>'; then
      POOL=$p
      break
    fi
  done < <(virsh pool-list --all --name)
fi
[[ -n $POOL ]] || { echo "no libvirt pool for /var/lib/libvirt/images" >&2; exit 1; }

guest_ip() {
  virsh domifaddr "$NAME" --source lease 2>/dev/null \
    | awk '/ipv4/ { split($4, a, "/"); print a[1]; exit }'
}

ssh_opts=(
  -i "$KEY"
  -o IdentitiesOnly=yes
  -o StrictHostKeyChecking=accept-new
  -o UserKnownHostsFile="${HOME}/.ssh/omarchy-lab.known_hosts"
  -o BatchMode=yes
  -o ConnectTimeout=5
)

lab_ssh() {
  local ip
  ip=$(guest_ip)
  [[ -n $ip ]] || { echo "guest has no lease yet" >&2; return 1; }
  ssh "${ssh_opts[@]}" "${USER}@${ip}" "$@"
}

wait_ssh() {
  local n=0
  until lab_ssh true 2>/dev/null; do
    (( n++ < 60 )) || { echo "SSH did not come up" >&2; return 1; }
    sleep 2
  done
}

wait_off() {
  local n=0
  until virsh list --all | awk -v name="$NAME" '$2==name && $3=="shut" {found=1} END{exit !found}'; do
    (( n++ < 30 )) || return 0
    sleep 1
  done
}

wait_hypr() {
  local n=0
  until lab_ssh 'ls /run/user/$(id -u)/hypr 2>/dev/null | grep -q .'; do
    (( n++ < 45 )) || { echo "Hyprland did not start (autologin?)" >&2; return 1; }
    sleep 2
  done
}

session_env='
  export XDG_RUNTIME_DIR=/run/user/$(id -u)
  export DBUS_SESSION_BUS_ADDRESS=unix:path=$XDG_RUNTIME_DIR/bus
  export HYPRLAND_INSTANCE_SIGNATURE=$(ls -t $XDG_RUNTIME_DIR/hypr 2>/dev/null | head -1)
  export WAYLAND_DISPLAY=$(find $XDG_RUNTIME_DIR -maxdepth 1 -name "wayland-*" ! -name "*.lock" -printf "%f\n" 2>/dev/null | head -1)
  [ -f /etc/omarchy.conf ] && . /etc/omarchy.conf
  export OMARCHY_PATH="${OMARCHY_PATH:-/usr/share/omarchy}"
  export PATH="$OMARCHY_PATH/bin:$PATH"
'

cmd="${1:-help}"
shift || true

case "$cmd" in
  start)
    virsh start "$NAME"
    wait_ssh
    wait_hypr
    echo "up $(guest_ip)"
    ;;
  stop)
    lab_ssh "sudo systemctl poweroff" 2>/dev/null || virsh destroy "$NAME"
    wait_off
    ;;
  destroy)
    virsh destroy "$NAME" || true
    wait_off
    ;;
  ip)
    guest_ip
    ;;
  ssh)
    wait_ssh
    lab_ssh "$@"
    ;;
  session)
    wait_ssh
    wait_hypr
    lab_ssh "bash -lc $(printf '%q' "$session_env $*" )"
    ;;
  reset)
    virsh destroy "$NAME" 2>/dev/null || true
    wait_off
    virsh vol-delete --pool "$POOL" "$OVERLAY_VOL"
    virsh vol-create-as "$POOL" "$OVERLAY_VOL" 80G --format qcow2 \
      --backing-vol "$BASE_VOL" --backing-vol-format qcow2 >/dev/null
    virsh start "$NAME"
    wait_ssh
    wait_hypr
    echo "reset $(guest_ip)"
    ;;
  push)
    wait_ssh
    src="${1:?usage: omarchy-lab push SRC [DST]}"
    dst="${2:-/home/${USER}/omarchy}"
    src="${src%/}/"
    rsync -az --delete --exclude .git \
      -e "ssh -i ${KEY} -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new -o UserKnownHostsFile=${HOME}/.ssh/omarchy-lab.known_hosts -o BatchMode=yes" \
      "$src" \
      "${USER}@$(guest_ip):${dst}/"
    ;;
  screenshot)
    mkdir -p "$SCREEN_DIR"
    local_ppm="${SCREEN_DIR}/$(date +%Y%m%d-%H%M%S).ppm"
    virsh screenshot "$NAME" "$local_ppm"
    if command -v magick >/dev/null; then
      magick "$local_ppm" "${local_ppm%.ppm}.png"
      rm -f "$local_ppm"
      echo "${local_ppm%.ppm}.png"
    else
      echo "$local_ppm"
    fi
    ;;
  send-key)
    virsh send-key "$NAME" "$@"
    ;;
  viewer)
    virt-viewer --connect "$CONNECT" --attach "$NAME"
    ;;
  help|*)
    cat <<'EOF'
usage: omarchy-lab <command>

  start         start the VM and wait for SSH
  stop          graceful shutdown
  destroy       power off
  reset         new overlay from the gold image, then boot
  ip            print the NAT lease
  ssh [cmd]     SSH as the lab user
  session cmd   SSH with Hyprland session env
  push SRC DST  rsync a checkout into the guest
  screenshot    capture the virtio display
  send-key ...  virsh send-key (e.g. KEY_LEFTMETA KEY_ENTER)
  viewer        attach virt-viewer
EOF
    ;;
esac

chmod +x ~/VMs/omarchy-lab/bin/omarchy-lab
ln -sfn ~/VMs/omarchy-lab/bin/omarchy-lab ~/.local/bin/omarchy-lab

session is the important one. A login SSH session does not inherit the graphical environment. Without XDG_RUNTIME_DIR and HYPRLAND_INSTANCE_SIGNATURE, hyprctl and any PoC that talks to the running shell will look at an empty bus and report a lie. Guest omarchy capture screenshot waits for a region (and will hang an agent). omarchy capture screenshot fullscreen save writes ~/Pictures/screenshot-*.png in the guest. The reliable host-side capture is omarchy-lab screenshot (virsh). omarchy-lab send-key KEY_LEFTMETA KEY_SPACE opens the Omarchy menu.

8. Guest workflow: one checkout, one link

On a fresh overlay, copy a host checkout (do not pass a host-expanded ~/omarchy as the destination — the default is /home/lab/omarchy):

omarchy-lab push ~/Work/omarchy
omarchy-lab ssh 'omarchy dev link /home/lab/omarchy --no-reboot && sudo reboot'

Wait for SSH and Hyprland (autologin), then:

omarchy-lab session 'omarchy version'
omarchy-lab session 'omarchy dev status'

push excludes .git, so omarchy version reports dev, not dev (<sha>). Clone with git inside the guest if you need the SHA. Plain omarchy-lab ssh 'omarchy version' can still print the packaged version because that shell has not sourced /etc/omarchy.conf.

Or the agent can edit over SSH. I prefer host-side edits: the tools, the git identity, and the review all stay on the machine I trust, and the guest only ever runs the tree.

9. How the host AI is supposed to work

Claude Code, Codex, Grok, whatever you already run on the Omarchy host: they already have a shell. They do not need a special MCP server for this. They need instructions that make the lab the default place to execute a PoC, and the wrapper so they reboot the guest instead of the machine you are using.

Drop something like this in the host agent's project instructions, or in AGENTS.md of the checkout you are about to patch:

`omarchy dev link` belongs in the guest. Run reproducers there too.

The disposable guest is `omarchy-dev`, driven by `omarchy-lab` on PATH.

- Reproduce, test, and run PoCs only inside the guest.
- `omarchy-lab reset` before an untrusted reproducer.
- `omarchy-lab push .` after edits, then
  `omarchy-lab ssh 'omarchy dev link /home/lab/omarchy --no-reboot && sudo reboot'`.
- Graphical checks: `omarchy-lab screenshot`.
- Menu: `omarchy-lab send-key KEY_LEFTMETA KEY_SPACE`.
- If the guest is wedged: `omarchy-lab reset`. Do not debug it on the host.

That is enough. A competent agent will then do roughly:

1. omarchy-lab reset
2. Push the unpatched tree, link, reboot
3. Copy the reporter's reproducer into /tmp in the guest, not into the host home
4. Run it with omarchy-lab session ...
5. omarchy-lab screenshot plus journalctl --user -u omarchy-shell
6. Push the patch, reboot, run the same reproducer, expect it to fail closed
7. Reset the overlay so the next task does not inherit a dirty shell

For a compositor-level check you still want virt-viewer once with your own eyes. Screenshots catch "the menu opened" and "the lock stayed up." They do not catch "this animation is 8 fps."

10. A patch loop that does not leak

Concrete shape I use for a shell-boundary fix. No payload, just the moving parts.

# 1. Clean guest, unpatched checkout
omarchy-lab reset
omarchy-lab push ~/Work/omarchy
omarchy-lab ssh 'omarchy dev link /home/lab/omarchy --no-reboot && sudo reboot'
omarchy-lab ssh true   # wait

# 2. Reproducer lives in the guest only
omarchy-lab ssh 'mkdir -p /tmp/repro'
scp -F none -i ~/.ssh/omarchy-lab \
  /path/to/reporter-repro.sh lab@$(omarchy-lab ip):/tmp/repro/
omarchy-lab session 'bash /tmp/repro/reporter-repro.sh' || true
omarchy-lab screenshot
omarchy-lab ssh 'journalctl --user -u omarchy-shell -b --no-pager | tail -n 80'

# 3. Apply the patch on the host, push, relink
# (edit ~/Work/omarchy-lab, commit there)
omarchy-lab push ~/Work/omarchy
omarchy-lab ssh 'sudo reboot'
omarchy-lab ssh true

# 4. Same reproducer, now against the patched shell
omarchy-lab session 'bash /tmp/repro/reporter-repro.sh'
omarchy-lab screenshot

# 5. Forget the overlay
omarchy-lab reset

The host never executes the reproducer. The gold image never keeps it. The screenshot directory on the host is the only durable artifact, and it is a picture of a VM display, not a copy of the payload.

If the finding is network-facing, freeze outbound traffic for the run:

omarchy-lab ssh 'sudo ufw default deny outgoing && sudo ufw allow out 22'
# ...run the reproducer...
omarchy-lab reset

Reset is simpler than remembering to re-open the firewall.

11. Things that will waste an afternoon

No module named 'gi' from virt-install. Mise/pyenv Python is ahead of /usr/bin/python3. Prefix with /usr/bin/python3 /usr/bin/virt-install (same for virt-manager from that shell).

Network not found: default. virt-install used qemu:///session. The default NAT lives on qemu:///system. Pass --connect qemu:///system, or set uri_default in ~/.config/libvirt/libvirt.conf.

Cannot access storage file … Permission denied (uid 946). libvirt-qemu cannot traverse a 700 $HOME. Do not setfacl search on $HOME — under umask 022 that exposes every 644 file in 755 trees (.config, .aws, Work, …). Put the disk and ISO in /var/lib/libvirt/images/ instead.

Guest ethernet up, no IPv4, NetworkManager stuck on "getting IP configuration". Host UFW is dropping DHCP. Allow UDP 67 on virbr0 to any (discovers are broadcast), plus DNS 53 to 192.168.122.1, and forward virbr0 out the uplink. Then reconnect ethernet in the guest.

SeaBIOS / "BIOS" firmware. The configurator never looks right. Recreate the domain with OVMF_CODE.4m.fd and OVMF_VARS.4m.fd.

QXL or stdvga. Hyprland wants virtio-vga. The official ISO test uses -device virtio-vga. Match it.

LUKS on the lab. The agent reboots, hits Plymouth, and you think SSH is broken.

virsh shutdown leaves the guest running. Omarchy ignores the ACPI power key. Use sudo systemctl poweroff in the guest, or virsh destroy from the host.

Sharing $HOME. A user-level plugin PoC that "only reads files" now reads the host. rsync a checkout. Nothing else.

Password SSH or your personal GitHub key in the guest. The guest is where untrusted QML and shell snippets run. Give it a key that can push one fork and nothing else.

Resizing the SPICE window during early boot. The ISO harness even warns about this: a resize can wedge virtio-gpu before KMS takes over. Pick a size, leave it.

12. Optional: faster graphics later

virtio-vga is enough for CLI tests, plugin boundaries, theme work, and most screenshots. It is not a 5090.

If you have a spare iGPU in its own IOMMU group and the host already displays on a discrete GPU, VFIO of that iGPU into the guest is the next step. That is a different post: iommu=pt, vfio-pci, unbinding amdgpu or i915, and usually Looking Glass. Skip it until the lab is boring.

Why this is worth the disk

A 80 GiB overlay on a machine that already runs Omarchy is cheap. Reproducing a lock-screen finding on the session you are staring at is not.

The split is simple enough to keep in your head: the host agent writes the patch, the guest dev links it and runs the PoC, reset forgets the rest. Once omarchy-lab ssh works, every coding agent you already use on Omarchy can smash a second Omarchy without taking down the first.

If your first notification after idle is still clipped or silent on HDMI, see:

How to Fix HDMI First-Notification Clipping in Omarchy (mako)

1) Create a notification sound script

mkdir -p ~/.local/bin
cat > ~/.local/bin/omarchy-notification-sound <<'BASH'
#!/bin/bash

# Optional custom sound:
# ~/.local/share/sounds/notification.oga

custom_sound="${XDG_DATA_HOME:-$HOME/.local/share}/sounds/notification.oga"
default_sound="/usr/share/sounds/freedesktop/stereo/message.oga"

if [[ -f "$custom_sound" ]]; then
  if command -v paplay >/dev/null 2>&1; then
    paplay "$custom_sound" >/dev/null 2>&1 &
    exit 0
  fi
  if command -v pw-play >/dev/null 2>&1; then
    pw-play "$custom_sound" >/dev/null 2>&1 &
    exit 0
  fi
fi

if [[ -f "$default_sound" ]]; then
  if command -v paplay >/dev/null 2>&1; then
    paplay "$default_sound" >/dev/null 2>&1 &
    exit 0
  fi
  if command -v pw-play >/dev/null 2>&1; then
    pw-play "$default_sound" >/dev/null 2>&1 &
    exit 0
  fi
fi

if command -v canberra-gtk-play >/dev/null 2>&1; then
  canberra-gtk-play -i message -d mako >/dev/null 2>&1 &
fi
BASH
chmod +x ~/.local/bin/omarchy-notification-sound

2) Tell mako to run it on each notification

Omarchy links your live mako config to:

~/.config/omarchy/current/theme/mako.ini

Add:

on-notify=exec ~/.local/bin/omarchy-notification-sound

If an app already plays its own sound (for example Slack), exclude it to avoid double audio:

[app-name=Slack]
on-notify=none

Reload:

makoctl reload

Test:

notify-send "Test" "Notification sound check"

3) Native sound options you can use

Common event IDs from the built-in Freedesktop theme:

• message
• message-new-instant
• dialog-information
• dialog-warning
• dialog-error
• complete
• bell
• camera-shutter
• device-added
• device-removed
• network-connectivity-established
• network-connectivity-lost
• phone-incoming-call
• power-plug
• power-unplug
• service-login
• service-logout
• window-attention
• trash-empty

Try a sound by event ID:

canberra-gtk-play -i message -d mako
canberra-gtk-play -i complete -d mako

List all local sound IDs dynamically:

ls /usr/share/sounds/freedesktop/stereo | sed 's/\.oga$//'

4) Keep the setting after theme changes

Omarchy rewrites theme files when you switch themes. Re-apply the on-notify line with a hook.

Create ~/.config/omarchy/hooks/theme-set:

#!/bin/bash
set -euo pipefail

mako_theme="$HOME/.config/omarchy/current/theme/mako.ini"
sound_rule='on-notify=exec ~/.local/bin/omarchy-notification-sound'
slack_app='[app-name=Slack]'
slack_rule='on-notify=none'

if [[ -f "$mako_theme" ]] && ! grep -Fxq "$sound_rule" "$mako_theme"; then
  printf '\n%s\n' "$sound_rule" >> "$mako_theme"
fi

if [[ -f "$mako_theme" ]] && ! awk '
  /^\[app-name=Slack\]$/ {
    getline
    if ($0 == "on-notify=none") found=1
  }
  END { exit(found ? 0 : 1) }
' "$mako_theme"; then
  printf '\n%s\n%s\n' "$slack_app" "$slack_rule" >> "$mako_theme"
fi

makoctl reload >/dev/null 2>&1 || true

Then:

chmod +x ~/.config/omarchy/hooks/theme-set

At this point notification sound is wired. If HDMI still clips the first one after idle, use the dedicated HDMI fix post linked above.

In most setups, it is HDMI audio sink auto-suspend.

Why it happens

With PipeWire + WirePlumber, idle outputs can be suspended to save power. HDMI sinks are especially noticeable here.

When a short notification sound plays after idle:

1. The sink wakes up.
2. The stream starts immediately.
3. The beginning of the sound can be clipped during wake-up.

That is why repeated notifications a few seconds apart sound normal: the sink is already awake.

Confirm this is your issue

Check your default sink:

pactl info | grep "Default Sink"

List sinks:

wpctl status

If your default sink is HDMI and first-hit clipping matches your symptoms, disable suspend for that sink.

Fix: disable suspend timeout for your HDMI sink

Create a WirePlumber override:

mkdir -p ~/.config/wireplumber/wireplumber.conf.d
cat > ~/.config/wireplumber/wireplumber.conf.d/51-disable-hdmi-suspend.conf <<'CONF'
monitor.alsa.rules = [
  {
    matches = [
      {
        node.name = "alsa_output.pci-0000_01_00.1.hdmi-stereo"
      }
    ]
    actions = {
      update-props = {
        session.suspend-timeout-seconds = 0
      }
    }
  }
]
CONF

Restart user audio services:

systemctl --user restart wireplumber pipewire pipewire-pulse

Verify:

wpctl inspect @DEFAULT_AUDIO_SINK@ | grep session.suspend-timeout-seconds

Expected:

session.suspend-timeout-seconds = "0"

Notes

• Replace node.name with your actual sink name if different.
• You can get exact node names from wpctl inspect <sink-id>.
• If you still hear clipping, verify the fix applied to the active default sink and confirm session.suspend-timeout-seconds = "0" on that sink.

For the base notification-sound setup in mako, see:

Omarchy: Enable Notification Sound in mako

This guide is the product of real-world troubleshooting. This was tested with Omarchy 3.0, Windows 11, and an NVIDIA GPU. Includes specifics for ASUS motherboards and NVIDIA graphics.

Assumptions:

• You have already installed Windows 10 or 11.
• You have successfully installed Omarchy alongside it.
• You are logged into your Omarchy desktop.

Phase 1: BIOS Setup

Before we touch Omarchy's configuration, let's set the firmware in Setup Mode.

1. Reboot and Enter your BIOS/UEFI. (Usually by pressing Del or F2 on startup).
2. Disable CSM: Navigate to the "Boot" tab and ensure CSM (Compatibility Support Module) is set to Disabled. Secure Boot requires a pure UEFI environment.
3. Enter Setup Mode:
   • Find the "Secure Boot" menu.
   • Select the option to "Clear Secure Boot Keys" or "Delete All Secure Boot Variables".
   • Do not select any option to "Install default keys" afterwards.
4. Save and Exit, booting directly back into Omarchy.

Phase 2: Key Management

Now, we'll install the keys for both of your operating systems.

1. Install sbctl:

   sudo pacman -S sbctl
   

2. Create Keys: This command generates your secure keys and saves them locally.

   sudo sbctl create-keys
   

3. Enroll Your Keys (and Microsoft's): Now, enroll the keys. The -m flag includes Microsoft's keys as well.

   sudo sbctl enroll-keys -m
   

4. Sign the Limine Bootloader: We need to sign the bootloader binary itself so the firmware will trust it.

   sudo sbctl sign -s /boot/EFI/limine/limine_x64.efi
   # Also sign the fallback path
   sudo sbctl sign -s /boot/EFI/BOOT/BOOTX64.EFI
   

Phase 3: Configuring Omarchy boot

1. Get Your Partition IDs: We need two unique IDs (the next step automates retrieving them):

   • The LUKS Partition UUID: This is the UUID of the physical partition labeled crypto_LUKS (e.g., /dev/nvme2n1p2).
   • The BTRFS Root UUID: This is the UUID of the filesystem inside the LUKS container, labeled btrfs and mounted at /.

2. Create the Limine Configuration File: (Remove nvidia_drm.modeset=1 if you don't have NVIDIA)

   LUKS_UUID=$(lsblk -no UUID,FSTYPE | awk '$2=="crypto_LUKS"{print $1; exit}') && \
   BTRFS_UUID=$(lsblk -no UUID,FSTYPE,MOUNTPOINT | awk '$2=="btrfs" && $3=="/" {print $1; exit}') && \
   [ -n "$LUKS_UUID" ] && [ -n "$BTRFS_UUID" ] || { echo "Could not auto-detect required UUIDs" >&2; exit 1; } && \
   echo "Detected LUKS UUID: $LUKS_UUID" && echo "Detected BTRFS root UUID: $BTRFS_UUID" && \
   sudo tee /etc/default/limine <<EOF
   TARGET_OS_NAME="Omarchy"
   ESP_PATH="/boot"
   KERNEL_CMDLINE[default]="cryptdevice=UUID=$LUKS_UUID:root root=UUID=$BTRFS_UUID rootflags=subvol=@ quiet splash nvidia_drm.modeset=1"
   ENABLE_UKI=yes
   ENABLE_LIMINE_FALLBACK=yes
   FIND_BOOTLOADERS=yes
   BOOT_ORDER="*, *fallback, Snapshots"
   MAX_SNAPSHOT_ENTRIES=5
   SNAPSHOT_FORMAT_CHOICE=5
   EOF
   

3. Create the Plymouth Hook File: This tells the system to build the graphical splash screen into the boot image.

   sudo tee /etc/mkinitcpio.conf.d/omarchy_hooks.conf <<EOF
   HOOKS=(base udev plymouth keyboard autodetect microcode modconf kms keymap consolefont block encrypt filesystems fsck btrfs-overlayfs)
   EOF
   

Phase 4: Restoring Plymouth

The Omarchy installer includes a script to set up a theme and a smooth transition to your desktop. We need to re-run its logic.

1. Find and run the script located in your user's Omarchy directory: ~/.local/share/omarchy/install/login/plymouth.sh.

   chmod +x ~/.local/share/omarchy/install/login/plymouth.sh
   ~/.local/share/omarchy/install/login/plymouth.sh
   

Phase 5: Going Live (Building, Signing, and Enabling)

Now we apply all our configurations.

1. Run Limine Update: This will read your new config files, build a new Unified Kernel Image (UKI), and sbctl will automatically sign it for you.

   sudo limine-update
   

   The output will confirm the UKI was created and signed. The warning about Secure Boot being disabled is normal here.

2. Add Windows to the Boot Menu:

   sudo limine-scan
   

   Select the number corresponding to "Windows Boot Manager" and press Enter.

3. Reboot into your UEFI/BIOS.

4. Enable Secure Boot: These are specific instructions for Asus but something similar should work for other motherboards.

   • Navigate to the "Secure Boot" menu.
   • Set OS Type to Windows UEFI mode. (This is key to making Windows report correctly while still allowing Omarchy to boot).
   • Ensure Secure Boot Mode is set to Custom.
   • Finally, set the main Secure Boot option to Enabled.
   • Save Changes and Exit.

Phase 6: Verification

Your system will now boot to the Omarchy splash screen.

1. Verify Secure Boot Status:

   • In Omarchy, run sbctl status. It must say Secure Boot: ✓ Enabled.
   • Reboot and select Windows from the Limine menu. Open msinfo32. It must say Secure Boot State: On.

This post walks you through the setup: installing wayvnc and Tailscale, handling resolution toggling for ultrawide monitors, and connecting from macOS.

Step 1: Install wayvnc and Tailscale

On your Omarchy (or Hyprland on Arch) machine:

For Tailscale, the recommended way is to use the Omarchy menu:

Menu: Install → Service → Tailscale

This will handle the installation and setup for you.

For wayvnc:

yay -S wayvnc tailscale

Enable and start Tailscale:

sudo systemctl enable --now tailscaled
sudo tailscale up

Tailscale gives you a secure private IP (something like 100.x.y.z) that works anywhere, without opening firewall ports.

Step 2: Find Your Monitor Name and Resolution

On your Omarchy (Hyprland) machine, open a terminal and run:

hyprctl monitors

This will list all connected monitors, their names (e.g., DP-3), and their current resolutions (e.g., 5120x1440@240). Note your main monitor's name and its native resolution.

Step 3: Find Your Client (Mac) Resolution and Customize the Toggle Script

On your Mac, open Terminal and run:

system_profiler SPDisplaysDataType | grep Resolution

This will output something like:

Resolution: 3456 x 2234 Retina

For Retina displays, divide both numbers by 2 to get the actual pixel resolution. For example, 3456 / 2 = 1728 and 2234 / 2 ≈ 1117, so use 1728x1117.

Now, create ~/toggle-resolution.sh on your Omarchy machine, customizing the monitor name and resolutions for your setup. Here’s my example for a Samsung Odyssey G9 (5120x1440) and a MacBook Pro 16" M1 (1728x1117):

#!/bin/bash
MONITOR="DP-3"

CURRENT=$(hyprctl monitors | awk -v mon="$MONITOR" '
    $2 == mon {getline; print $1}' )

if [[ "$CURRENT" == 5120x1440* ]]; then
    echo "Switching to MacBook-friendly resolution (1728x1117@60)..."
    hyprctl keyword monitor "$MONITOR,1728x1117@60,0x0,1"
elif [[ "$CURRENT" == 1728x1117* ]]; then
    echo "Switching back to Odyssey G9 native resolution (5120x1440@240)..."
    hyprctl keyword monitor "$MONITOR,5120x1440@240,0x0,1"
else
    echo "Current mode is $CURRENT — defaulting to Odyssey G9 native."
    hyprctl keyword monitor "$MONITOR,5120x1440@240,0x0,1"
fi

Make it executable:

chmod +x ~/toggle-resolution.sh

(Optional) Add a Hyprland keybinding in ~/.config/hypr/bindings.conf:

bindd = SUPER SHIFT, R, Toggle Resolution, exec, ~/toggle-resolution.sh

Now you can switch between ultrawide native and MacBook-friendly resolution with a hotkey or by running the script directly.

Step 4: Connect from macOS

On your Mac:

1. Install a VNC client on your Mac (e.g. TigerVNC Viewer or RealVNC Viewer).
2. On your Mac, click the Tailscale icon in the top bar, find your Omarchy machine in the device list, and click it this copies its Tailscale IP address to your clipboard.
3. Open your VNC viewer and connect to your Omarchy’s IP (e.g. 100.115.92.30:5900).
4. If needed, use your toggle script (or hotkey) to adjust the remote resolution for your Mac’s screen.

Conclusion

With Omarchy (Hyprland on Arch), wayvnc, and Tailscale, you can have a secure, practical remote desktop setup. Add a simple resolution toggle script, and you’ll have the flexibility to use an ultrawide monitor at your desk and a laptop-friendly resolution when you connect remotely.

TL;DR

The Problem: When a Key Isn't Just a Key

The first step in fixing a problem is understanding it. In our case, the Print Screen key on a Keychron K3 in "Mac mode" wasn't sending a simple Print signal. To figure out what it was sending, we used keyd's built-in diagnostic tool.

After installing keyd, we ran its monitor command (sudo keyd monitor). When we pressed the problematic key, the monitor showed us the truth: a single press was sending a sequence of three keys at once: leftshift, leftmeta, and 4.

This is the standard macOS shortcut to take a screenshot of a selected area. The keyboard's firmware was literally typing a Mac shortcut, which our Linux system didn't know what to do with.

The Solution: keyd, the Universal Translator

Simple remapping tools couldn't fix this, as they struggled to intercept a multi-key combination. The solution was to use keyd, a powerful, low-level daemon that can remap keys and combinations before your desktop environment even sees them.

Here’s how we used it to translate the macOS shortcut into a proper Print Screen event.

Step 1: Install and Enable keyd

First, we installed keyd and enabled its background service.

sudo pacman -S keyd
sudo systemctl enable --now keyd

Step 2: Get Your Keyboard's Info with keyd monitor

Next, we need to find the keyboard's hardware ID and diagnose the key press. The keyd monitor command does both at the same time.

sudo keyd monitor

The monitor will list all connected devices. Look for your keyboard in the list. The output will look like this:

device added: 05ac:024f:f110753b Keychron Keychron K3 (/dev/input/event4)

From this single line, we get the vendor and product ID: 05ac:024f.

With the monitor still running, press the problematic key to confirm what it sends.

Step 3: Create the Configuration File

Now, create a configuration file in /etc/keyd/. It's good practice to name it after the device.

sudo nvim /etc/keyd/your-keyboard.conf

Step 4: Write the Remapping Rule

This is where the magic happens. Inside the file, we set up two sections:

• [ids]: Tells keyd which device(s) this rule applies to. We use the ID from keyd monitor.
• [main]: Defines the actual remapping.

We tell keyd to look for the leftmeta+leftshift+4 combination and replace it with sysrq, which is the kernel's internal name for the Print Screen key.

# /etc/keyd/your-keyboard.conf
# (Run: sudo keyd monitor to discover <vendor>:<product> and the exact combo)

[ids]
<vendor>:<product>    # optional – delete this whole block to apply globally

[main]
leftmeta+leftshift+4 = sysrq

Step 5: Reload and Test

With the configuration saved, a final command applies the changes without needing a reboot:

sudo keyd reload

And just like that, the Print Screen key will start working perfectly, triggering all the screenshot hotkeys already configured on your system.

Why This Works

This method is so effective because keyd works at a very low level. It intercepts the raw input from the keyboard, finds a match in your configuration, and sends a new, corrected event to the rest of the OS. To your desktop and all other applications, it looks as if you pressed a normal Print Screen key all along.

Step 1: Clone the Oh My Zsh Repo

First, we'll need the plugin files. Clone the repository to a folder in your home directory:

git clone https://github.com/ohmyzsh/ohmyzsh.git ~/.oh-my-zsh

Step 2: Safely retrieve aliases

We'll add a small script at the bottom of our ~/.bashrc to load the plugins we want.

# ===================================================================
# Dynamically Load Aliases from Oh My Zsh Plugin Files
# ===================================================================

# 1. Set the path to your Oh My Zsh installation
export OMZ_DIR="$HOME/.oh-my-zsh"

# 2. List the plugins you want to load aliases from
OMZ_PLUGINS=(
  git
  kubectl
  elixir
  bundler
  # Add other plugins here, e.g., docker, systemd, etc.
)

# 3. Loop through the plugins and load ONLY the simple alias definitions
for plugin in "${OMZ_PLUGINS[@]}"; do
  if [ -f "$OMZ_DIR/plugins/$plugin/$plugin.plugin.zsh" ]; then
    # Use grep to find lines starting with 'alias ', then use eval
    # to execute them as if they were written here.
    # This is safe for simple aliases like alias a='b'.
    eval "$(grep "^alias " "$OMZ_DIR/plugins/$plugin/$plugin.plugin.zsh")"
  fi
done

# Unset variables to keep the environment clean
unset OMZ_DIR
unset OMZ_PLUGINS

Step 3: Reload your shell

To make the aliases available in your current session reload your .bashrc file.

source ~/.bashrc

Your new aliases are now ready to use in your bash shell. Enjoy!

Update Aug. 26 2025

If you also want completions for your git and kubectl aliases this code makes it work although it's more complicated.

Step 1

Install bash-completition

yay -S bash-completition

source /usr/share/bash-completion/bash_completion

# ===================================================================
# Dynamically Load Aliases from Oh My Zsh Plugin Files
# ===================================================================

# 1. Set the path to your Oh My Zsh installation
export OMZ_DIR="$HOME/.oh-my-zsh"

# 2. List the plugins you want to "borrow" aliases from
OMZ_PLUGINS=(
  git
  kubectl
  elixir
  bundler
)

# --- Completion helpers ----------------------------------------------------
__omz_load_kubectl_completion() {
  [[ -n ${__OMZ_KC_LOADED:-} ]] && return 0
  command -v kubectl &>/dev/null || return 0
  declare -F __start_kubectl >/dev/null || source <(kubectl completion bash)
  __OMZ_KC_LOADED=1
}

__omz_load_git_completion() {
  [[ -n ${__OMZ_GIT_LOADED:-} ]] && return 0
  command -v git &>/dev/null || return 0
  if ! (declare -F __git_wrap__git_main >/dev/null || declare -F _git >/dev/null || declare -F __git_main >/dev/null); then
    for f in /usr/share/bash-completion/completions/git /etc/bash_completion.d/git; do [[ -r $f ]] && . "$f" && break; done
  fi
  __OMZ_GIT_LOADED=1
}

# Unified completion function for git & kubectl aliases.
# 1. Look up full expansion
# 2. Inject its tokens in front of user input so native completion sees real command
# 3. Delegate to command-specific completion
__omz_alias_complete() {
  local name=${COMP_WORDS[0]}
  local expansion=${__omz_alias_map[$name]}
  [[ -n $expansion ]] || return 0

  # Fast path: single-word alias (rare for our target, but cheap to check)
  if [[ $expansion != *' '* ]]; then
    case $expansion in
      kubectl) __omz_load_kubectl_completion; __start_kubectl 2>/dev/null; return ;;
      git)     __omz_load_git_completion;   ;; # Git's main completion entry already handles base command
    esac
  fi

  # shellcheck disable=SC2206
  local base_tokens=( $expansion )          # expansion split safely by IFS=space semantics
  local oc=$COMP_CWORD                      # original cursor index
  local rest=( "${COMP_WORDS[@]:1}" )      # original args after alias word
  COMP_WORDS=( "${base_tokens[@]}" "${rest[@]}" )
  COMP_CWORD=$(( oc + ${#base_tokens[@]} - 1 ))

  case ${base_tokens[0]} in
    kubectl)
      __omz_load_kubectl_completion
      __start_kubectl 2>/dev/null
      ;;
    git)
      __omz_load_git_completion
      # Provide variables some git completion variants expect
      words=( "${COMP_WORDS[@]}" ); cword=$COMP_CWORD; cur=${COMP_WORDS[COMP_CWORD]}; prev=${COMP_WORDS[COMP_CWORD-1]}
      if declare -F __git_wrap__git_main >/dev/null; then __git_wrap__git_main; \
      elif declare -F _git >/dev/null; then _git; \
      elif declare -F __git_main >/dev/null; then __git_main; fi
      # Fallback: suggest remotes immediately after push if none yet
      if [[ ${COMP_WORDS[1]} == push && $COMP_CWORD -eq 2 && ${#COMPREPLY[@]} -eq 0 ]]; then
        mapfile -t COMPREPLY < <(git remote 2>/dev/null | sed 's/$/ /')
      fi
      ;;
  esac
}

###############################################
# Parse Oh My Zsh plugin alias definitions
# (idempotent; only captures kubectl/git aliases for completion)
###############################################
if [[ -z ${__OMZ_ALIAS_MAPS_LOADED:-} ]]; then
  declare -gA __omz_alias_map
  for plugin in "${OMZ_PLUGINS[@]}"; do
    plugin_file="$OMZ_DIR/plugins/$plugin/$plugin.plugin.zsh"
    [[ -f $plugin_file ]] || continue
    while IFS= read -r line; do
      [[ $line == alias\ * ]] || continue
      name=${line#alias }      # strip leading 'alias '
      name=${name%%=*}
      value=${line#*=}
      q=${value:0:1}
      if [[ $q == "'" || $q == '"' ]]; then
        value=${value:1:${#value}-2}       # remove surrounding quotes
      fi
      printf -v quoted '%q' "$value"
      eval "alias $name=$quoted" 2>/dev/null || true
      case $value in
        kubectl*|git*) __omz_alias_map[$name]="$value" ;;
      esac
    done < "$plugin_file"
  done
  unset name value q quoted
  __OMZ_ALIAS_MAPS_LOADED=1
fi

# Attach unified completion (re-runnable)
for a in "${!__omz_alias_map[@]}"; do complete -F __omz_alias_complete "$a" 2>/dev/null || true; done

1. Install mkcert

First, we'll use Homebrew to install mkcert, a simple tool for making locally-trusted development certificates:

brew install mkcert

2. Set up mkcert

Now, let's set up mkcert on your system:

mkcert -install

This command creates a local certificate authority on your machine.

3. Create a certificates folder

We'll create a dedicated folder in your home directory to store the certificates, this will make it easier to run on different projects and domains:

mkdir ~/.certs
cd ~/.certs

4. Generate certificates

Generate certificates for localhost:

mkcert localhost 127.0.0.1 ::1

This creates two files in your .certs folder: localhost+2.pem (the certificate) and localhost+2-key.pem (the key).

5. Run local-ssl-proxy

Now, we'll use npx local-ssl-proxy to run our local server with HTTPS.

npx local-ssl-proxy --cert ~/.certs/localhost+2.pem --key ~/.certs/localhost+2-key.pem --source 443 --target 4000

This command starts a proxy server that will serve your local content over HTTPS. If you're running something on port 4000 you can now see it at https://localhost

Note: The --source flag specifies the port where the HTTPS server will run, and the --target flag specifies the port where your actual application is running.

Bonus: Custom Domain Names

This method also works for custom domain names. If you want to use a domain like my.x.com, follow these steps:

1. Modify your /etc/hosts file (using sudo vim /etc/hosts) and add this to the end:

127.0.0.1 my.x.com

2. Generate a certificate for your custom domain:

cd ~/.cert
mkcert my.x.com

3. Run local-ssl-proxy with the new certificate:

npx local-ssl-proxy --cert ~/.certs/my.x.com.pem --key ~/.certs/my.x.com-key.pem --source 443 --target 4000

Now you can access your local site at https://my.x.com!

You should run everything you can with arm version of python. Only use the intel version if you are having trouble.

If you've previously tried installing python with any other method, be sure to fully remove it.

We'll start setting up our arm and intel environments by setting up a Rossetta-Terminal, which runs on intel. Follow the Create a Rosetta Terminal{:target="_blank"} tutorial.

Python3 ARM Installation

These two steps must be run in the regular Terminal (arm)

1. Install brew{:target="_blank"} in Terminal.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Install python3 running brew install python3.

Hombrew keeps x86 binaries in /usr/local and uses /opt/homebrew for their ARM binaries.

Python3 Intel Installation

All the steps below should be run in Rosetta-Terminal

1. Install brew{:target="_blank"} in Rosetta-Terminal.
2. Create alias in ~/.zprofile for intel brew alias ibrew='arch -x86_64 /usr/local/bin/brew'. Your ~/.zprofile should look like this.

eval "$(/opt/homebrew/bin/brew shellenv)"
alias ibrew='arch -x86_64 /usr/local/bin/brew'

4. Load alias running

source ~/.zprofile

5. Install intel python3

ibrew install python3

You can specify a version like this:

ibrew install python@3.7

This previous step will give you where python is installed, e.g. /usr/local/opt/python@3.7/bin/python3

You should now have installed both arm and intel versions of python. Whenever you need to use intel python, be sure to open the Rosetta-Terminal and load the intel python. For example, if you use pipenv for managing virtual envs and packages, run this in your project folder:

pipenv shell --python /usr/local/opt/python@3.7/bin/python3

SimpleDelegator

A concrete implementation of Delegator, this class provides the means to delegate all supported method calls to the object passed into the constructor and even to change the object being delegated to at a later time with #__setobj__.

I like the decorators to behave like they are the class that's been decorated. To acheive this let's create a class Decorator which inherits from SimpleDelegator.

class Decorator < SimpleDelegator
  def component
    @component ||= __getobj__
  end

  def class
    component.class
  end
end

As you can see we created the method component which will return the object it's decorating and the method class which will return the component class.

Now let's create a UserDecorator that inherits from Decorator.

class UserDecorator < Decorator
  def pirate_name
    "Ahoy! #{first_name}"
  end
end

Great! But how do we use this decorator?

decorated_user = UserDecorator.new(current_user)
decorated_user.pirate_name # => Ahoy! Adrian

So decorating objects allows you to avoid having view logic on your model.

Luckily there's an easy way around this which is based on how the portal allows some devices in and the other not.

Every device that connects to a network has a MAC address this address is embedded in your device and is unique. This is what the Hotspot checks to see if you are allowed to access the internet or not.

What we are going to do is called 'MAC Address Spoofing'. Doing this will help us impersonate another device on the network which hopefully does have internet access.

Open Terminal

We need the MAC address we are going to impersonate. To get all MAC address in you ARP cache run

arp -na | sort -u -t' ' -k4,4

This will give you a list of ip address with their corresponding MAC addresses. Save this list we will be using it later.

Now we have to change our MAC address to one of the list and luckily will get internet access. To change(spoof) your MAC address run

sudo ifconfig en0 ether 00:00:00:00:00:00

where 00:00... is the MAC address to spoof.

Now just turn off and on your WiFi try and access http://acrogenesis.com if you face a Hotspot login try another MAC address from the list, if not you are already connected to the internet!

If running arp -na didn't give you results or the MAC addresses you tried didn't give you internet connectivity you will have to ping all devices with nmap here is how to do it:

To ping all devices on the network with nmap you need to have installed nmap on your mac the easiest way is thru brew which if you don't have installed you have to install it to.

After installing brew  run

brew install nmap

Now we need to know which addresses and netmask we are going to ping. So run

ifconfig | grep inet

and look for one that starts with 192.168.X.X, 172.X.X.X or 10.X.X.X like:

inet 192.168.2.156 netmask 0xffffff00 broadcast 192.168.2.255

To convert the hexadecimal netmask to decimal look it up at http://www.pawprint.net/designresources/netmask-converter.php

Mine is /24

Now let's ping all the devices, depending on the address and netmask you got is what you will ping.

Examples:

For 192.168.2.156 netmask 24

nmap -sn 192.168.2.0/24

for 172.16.0.156 netmask 16

nmap -sn 172.16.0.0/16

for 10.5.4.2 netmask 8

nmap -sn 10.0.0.0/8

Now run again

arp -na | sort -u -t' ' -k4,4

The list will now have all devices connected to the network.

To add this aliases and functions to your terminal simply run bash vim ~/.bash_profile if it doesn't exit it will create a new one.

Git

alias psh="git push origin" #push to origin specifying branch, ex. psh master
alias pll="git pull origin" #pull from origin specifying branch, ex. pll master
alias cmm="git commit -m" #commit
alias cmma="git commit -am" #commit and add modified files
rgc() {
  git commit -m"`curl -s http://whatthecommit.com/index.txt`" #get a random commit message from whatthecommit.com
}
function gc() { git clone "$1" && cd `echo "'$1'" | cut -d/ -f2 | cut -d. -f1`; } # clones git repository and cd's into it

Files and Folders

alias dev="cd ~/Copy/Development" #cd to my development folder
alias editbash="mvim ~/.bash_profile" #open my bash_profile in MacVim (you can change this to the editor you wish)
function mcd() { mkdir -p "$1" && cd "$1";} #mkdir a folder and cd into it

DNS

alias cleardns="sudo killall -HUP mDNSResponder" #clear dns on 10.8+

Changing Mac Address(I'm using en0 check which interface you use running ifconfig)

alias mac="sudo ifconfig en0 ether" #specify a mac address, ex mac 11:22:33:44:55:66
alias mymac="sudo ifconfig en0 ether 11:22:33:44:55:66" #revert back to my mac address, you have to check you mac address first.
alias chkmac="ifconfig en0 |grep ether" #check the mac I currently use
alias ranmac="openssl rand -hex 6 | sed 's/\(..\)/\1:/g; s/.$//'" # generate a random mac address
rmac(){
  sudo ifconfig en0 ether `ranmac`; #apply a random mac address
}

Beautiful Terminal (when on a git repository it show the branch you are on)

# Git branch in prompt.
parse_git_branch() {
  git branch 2> /dev/null | sed -e '/^[^*]/d' -e 's/* \(.*\)/ (\1)/'
}
function prompt {
  local GRAY="\[\033[0;37m\]"
  local WHITE="\[\033[1;37m\]"
  local GREEN="\[\033[0;32m\]"
  local CYAN="\[\033[0;36m\]"
  local MAGENTA="\[\033[0;35m\]"
  local RED="\[\033[0;31m\]"
  local BLACK="\[\033[0;30m\]"
  local YELLOW="\[\033[0;33m\]"
  local BLUE="\[\033[0;34m\]"
  export PS1="${GREEN}\u@${WHITE}mbp:${RED}acrogenesis${WHITE}\$(parse_git_branch) \w \`if [ \$? = 0 ]; then echo -e '\[\e[01;32m\]\n\xF0\x9F\x9A\x80'; else echo -e '\[\e[01;31m\]\n\xF0\x9F\x9A\x80'; fi\` \[\e[01;34m\]\[\e[00m\] "
  export CLICOLOR=1
  export LSCOLORS=GxFxCxDxBxegedabagaced
}
prompt

[gallery columns="2" link="none" type="slideshow" ids="48,47"]

First of all let’s create a shell script (.sh) (I’ll be doing the example for the wunderground API) and add some code (I use VIM, the vim command will create the file)

vim getWeather.sh

#!/bin/bash
cd /home/user/pathto/weatherapi
wget -O http://api.wunderground.com/api/heregoeskey/forecast/lang:SP/q/Mexico/Monterrey.json

This script works as follows: It goes to the path where you created the getWeather.sh  get’s the json from the API we are trying to bypass restrictions.

Now instead of calling api.wunderground.com on your website call mywebsite.com/pathto/weatherapi/Monterrey.json this will give us the same file but locally bypassing the amounts of calls done to the api server.

Now we need to refresh the file we made locally so for this we make a cronjob, to make a cronjob type

crontab -e

This will open the cron editor, just add the following and we should be refreshing our local json every hour

0 * * * * /home/user/pathto/weatherapi/getWeather.sh

The api call to the service will only be done every hour instead of every hit on your website. Now we are good to go!

Good luck! @acrogenesis

Thanks /u/Cixis for some suggestions