Desktops & the X11 viewer
Podroid includes a built-in VNC viewer that connects to Xvnc running inside the VM on display :0 (port 5900, auto-forwarded). Tap the monitor icon in the terminal's top bar to open it.
Installing a desktop
Alpine ships setup-desktop as part of the alpine-conf package. It is an interactive helper that creates a user and installs a desktop environment of your choice. Run it in the Podroid terminal:
# setup-desktopFollow the prompts to pick a desktop and create a user account. The script handles the apk add steps for you.
The built-in viewer speaks RFB (VNC), so it connects to an X11 display. It cannot show a Wayland compositor. Use Xfce, LXQt, or MATE - they run on X11 and render correctly. KDE Plasma 6, GNOME, and Sway are Wayland on Alpine and will not appear in the viewer, even after launching them.
Launching a desktop
You do not need a display manager. Xvnc is already the X server on :0, and DISPLAY=:0 is preset in the environment. After installing a desktop, start it directly from the terminal:
# Xfce example
$ startxfce4 &
# LXQt example
$ startlxqt &
# MATE example
$ mate-session &Installing lightdm or any other display manager and enabling it with rc-update add will cause it to fight Xvnc for display :0. Xvnc is already the X server; no display manager is needed.
Single GUI apps
You do not need a full desktop to run individual X11 applications. Install any X11 app and launch it directly; DISPLAY=:0 is already exported:
# apk add firefox
$ firefox &The app will appear in the viewer as soon as it opens a window.
Viewer settings reference
Tap the tune/gear icon in the X11 viewer's top bar to open viewer settings.
Resolution
Controls what resolution Xvnc presents to the desktop. Uses the RFB ExtendedDesktopSize extension to resize live without restarting the VM.
- Match viewport - the desktop tracks your screen size exactly, resizing whenever the viewer resizes. Pixel-perfect on most devices.
- Preset - fixed resolutions: 720p, 900p, 1080p, or 1440p. Pick a lower preset for smoother rendering on heavy desktops over a high-DPI display.
- Custom - enter any width and height in pixels.
Touch input
- Direct - tap to click at the point you touch; drag to drag; long-press activates drag-lock. Intuitive for touch-first use.
- Trackpad - relative pointer: your finger position moves the cursor rather than placing it. Sensitivity is adjustable (0.5x to 3.0x) with optional pointer acceleration.
In both modes: two-finger tap sends a right-click; two-finger drag scrolls.
External input
A connected hardware keyboard passes through fully, including Ctrl, Alt, Shift, and composed shortcuts (e.g. Ctrl+L in a browser). An external mouse's scroll wheel scrolls, and all three buttons map to their X11 equivalents.
Other settings
| Setting | Notes |
|---|---|
| Fullscreen | Hides the system UI. Back exits fullscreen. |
| Rotation lock | Auto, Landscape, or Portrait. Auto follows the device sensor. |
| Extra-keys bar | Show or hide the keyboard shortcut bar below the viewer. |
| Server DPI | 96 to 192. Tells Xvnc what DPI to report to apps. Takes effect on the next VM start. |
| Audio | PulseAudio streams PCM from the VM to the app over port 4713. Toggle to enable or disable. |
With an external mouse, right-click currently exits fullscreen instead of reaching the desktop. Android maps the mouse's right button to the Back action. Two-finger touch right-click works correctly as a workaround. A fix is planned.
The viewer currently uses uncompressed Raw encoding (ZRLE was disabled after it desynced on complex content). On a high-DPI phone, selecting the 720p or 900p preset reduces the amount of screen data transferred each frame and noticeably improves smoothness on heavy desktops. See the Performance page for general tuning advice.
Podroid is free software (GPL). Docs for v1.2.1. Found something inaccurate? Open an issue.