Phosh & remote desktop (wayvnc)

Phosh is a touch-first shell (the one used on Linux phones). It suits the 3.2“ touchscreen well. It is optional: the default TypixDeck OS desktop is labwc, like Raspberry Pi OS.

Easiest: the Phosh image

In Raspberry Pi Imager with the TypixDeck repository pick … + Phosh (Beta). It contains everything on this page, plus all the TypixDeck hardware support.

Install on stock Raspberry Pi OS

Start from Raspberry Pi OS Lite (64-bit, Trixie) with the TypixDeck overlays and config.txt block already applied. Phosh brings its own session, so there is no desktop display manager to fight with.

1. Keep Debian’s wlroots

sudo tee /etc/apt/preferences.d/typixdeck-phosh-wlroots >/dev/null <<'EOF'
# phoc is ABI-incompatible with the Raspberry Pi rebuild of libwlroots-0.18
Package: libwlroots-0.18
Pin: release o=Debian
Pin-Priority: 1001
EOF
sudo apt update

Why: the Raspberry Pi archive ships its own libwlroots-0.18 with extra patches. Phosh’s compositor, phoc, is built against Debian’s and crashes with the Raspberry Pi one (stack smashing detected right after Output 'DPI-1' added) - the session bounces straight back to the login screen. labwc uses wlroots 0.19, so phoc is the only user of 0.18 and the pin has no side effects. Priority 1001 also keeps later upgrades on Debian’s build.

2. Install

sudo apt install -y phosh-core phosh-mobile-settings gnome-console dconf-cli wlr-randr grim wayvnc

3. Start Phosh directly - and disable greetd

sudo systemctl disable greetd
sudo rm -f /etc/systemd/system/display-manager.service
sudo systemctl set-default graphical.target
sudo systemctl enable phosh

Why disable greetd: phosh-core pulls in the phrog greeter, which pulls in greetd, and greetd makes itself the display manager. It then wins the console and the device boots into a lock screen instead of the shell - with only the top bar and Settings reachable, and Phosh’s keypad does not fit the 4:3 panel. phosh.service instead starts the shell directly as the first user.

4. Scale, unlocked start, no blanking

sudo mkdir -p /etc/phosh /etc/systemd/user/mobi.phosh.Shell.service.d /etc/dconf/profile /etc/dconf/db/local.d

sudo tee /etc/phosh/phoc.ini >/dev/null <<'EOF'
[core]
xwayland=false

[output:DPI-1]
scale = 1.5
EOF

sudo tee /etc/systemd/user/mobi.phosh.Shell.service.d/typixdeck-unlocked.conf >/dev/null <<'EOF'
[Service]
ExecStart=
ExecStart=/usr/libexec/phosh --unlocked
EOF

[ -f /etc/dconf/profile/user ] || printf 'user-db:user\nsystem-db:local\n' | sudo tee /etc/dconf/profile/user >/dev/null
sudo tee /etc/dconf/db/local.d/10-typixdeck-phosh >/dev/null <<'EOF'
[org/gnome/desktop/screensaver]
lock-enabled=false

[org/gnome/desktop/lockdown]
disable-lock-screen=true

[sm/puri/phosh/lockscreen]
require-unlock=false

[org/gnome/desktop/session]
idle-delay=uint32 0

[org/gnome/settings-daemon/plugins/power]
idle-dim=false
sleep-inactive-ac-type='nothing'
sleep-inactive-battery-type='nothing'

[org/gnome/desktop/interface]
show-battery-percentage=true
EOF
sudo dconf update
sudo reboot

Why:

• Scale 1.5 (a 683×512 logical screen): phoc’s automatic 1.25 is too small to touch on a ~400 ppi panel; 2.0 leaves too little height for Phosh’s lock-screen keypad.
• Unlocked, no lock screen: the keypad does not fit the 4:3 panel, and the deck has a physical keyboard.
• No screen blanking or idle dimming: Phosh cannot switch the DPI panel’s power state, so “blank” only paints black with the backlight still on - it saves nothing and looks off.
• Battery percentage in the top bar, from the battery gauge.

Remote desktop: use wayvnc

Phosh is a Wayland session. RealVNC’s vncserver-x11 cannot show it - it only captures X11 and answers “Cannot currently show the desktop”. Use wayvnc (installed above):

sudo systemctl disable --now vncserver-x11-serviced 2>/dev/null
sudo systemctl enable --now wayvnc
sudo ss -ltnp | grep 5900        # wayvnc listening on *:5900

Raspberry Pi OS’s wayvnc ships /etc/wayvnc/config with authentication on (enable_auth=true, enable_pam=true) and TLS / RSA keys generated at install time. Connect any VNC client to <device-ip>:5900 and log in with your Linux user name and password. It listens on all interfaces - use a strong password.

Troubleshooting

• Only the top bar and Settings work, no app grid: greetd is still the display manager (step 3). Check with systemctl is-active phosh greetd - you want active / inactive.

• Screenshot from SSH (phoc is wlroots-based):

  XDG_RUNTIME_DIR=/run/user/1000 WAYLAND_DISPLAY=wayland-0 grim /tmp/screen.png