PostmarketOS Installation Guide

Headless Setup for Xiaomi Poco F1 (xiaomi-beryllium)

Complete guide for installing PostmarketOS on a Poco F1 headless server use with SSH access right from first boot. This process works even if your display is broken/disconnected.

Prerequisites

Device Requirements

Xiaomi Poco F1 (codename: beryllium)
Unlocked bootloader (critical!)
USB cable
Device can boot to fastboot mode

Host Computer Requirements

Linux computer (Ubuntu/Debian recommended)
Git installed
Fastboot tools installed
USB connection

PART 1: Install pmbootstrap

Step 1: Clone pmbootstrap Repository

Refer to Wiki: https://wiki.postmarketos.org/wiki/Pmbootstrap/Installation

PART 2: Initialize pmbootstrap

Step 2: Run pmbootstrap init

# Start initialization
pmbootstrap init

Answer the prompts:

Use default values for all, except the below options:

Vendor: xiaomi
- Type: xiaomi when asked for vendor
Codename: beryllium
- Type: beryllium when asked for device codename
User interface: none
- Important: Select none since this is a headless server (this is only if you dont want to use the screen/display)
Username: Enter your desired username
- Example: heeth
- This will be your SSH login username

PART 3: Install PostmarketOS with Required Packages

Step 3: Install with SSH and Networking

# Install PostmarketOS with required packages
pmbootstrap install --add openssh --add networkmanager --add avahi

Optional param: --fde i.e Full Disk Encryption

What this does:

openssh: Enables SSH server for remote access
networkmanager: Manages network connections
avahi: Enables mDNS for discovery (optional but helpful)

This step will take several minutes as it downloads and builds packages.

PART 4: Configure the System (Critical for Headless Setup)

Step 4: Enter the Rootfs Chroot

# Enter the device's filesystem (NOT the build environment)
pmbootstrap chroot -r

You should see a prompt like: / #

Step 5: Enable Required Services

# Enable SSH service
systemctl enable sshd

# Enable NetworkManager
systemctl enable NetworkManager

# Enable Avahi (optional, for mDNS discovery)
systemctl enable avahi-daemon

Step 6: Configure SSH to Allow Root Login

# Edit SSH config to allow root login
echo "PermitRootLogin yes" >> /etc/ssh/sshd_config

# Verify it was added
cat /etc/ssh/sshd_config | grep PermitRootLogin

Step 7: Configure WiFi (Optional)

Skip this step if using USB networking only.

If you want WiFi as backup:

# Create NetworkManager connection directory
mkdir -p /etc/NetworkManager/system-connections/

# Create WiFi connection file
cat > /etc/NetworkManager/system-connections/WiFi.nmconnection << 'EOF'
[connection]
id=MyWiFi
type=wifi
autoconnect=true

[wifi]
ssid=YourNetworkSSID
mode=infrastructure

[wifi-security]
key-mgmt=wpa-psk
psk=YourWiFiPassword

[ipv4]
method=auto

[ipv6]
method=auto
EOF

# Set correct permissions (CRITICAL!)
chmod 600 /etc/NetworkManager/system-connections/WiFi.nmconnection

Replace:

YourNetworkSSID with your actual WiFi network name
YourWiFiPassword with your actual WiFi password
wpa-psk with your Wifi type (WPA2/WPA3)

Note: WiFi on Poco F1 has some issues. USB networking is more reliable.

Step 8: Exit Chroot

# Exit the chroot environment
exit

You should be back to your regular terminal.

PART 5: Flash to Device

Step 9: Flash PostmarketOS (via fastboot mode)

# Navigate to pmbootstrap directory if not there
cd ~/pmbootstrap

# Flash the root filesystem
pmbootstrap flasher flash_rootfs

# Wait for completion...

# Flash the kernel
pmbootstrap flasher flash_kernel

# Wait for completion...

This process will:

Erase existing data on the device
Flash PostmarketOS rootfs
Flash the Linux kernel
Take several minutes

IMPORTANT: Do not disconnect the device during flashing!

Step 10: Reboot Device

# Reboot the device
fastboot reboot

Or manually:

Hold Power button for 10 seconds to force reboot

PART 6: First Boot and Connection

Step 11: Wait for First Boot

The device will reboot
First boot takes 1-2 minutes
The screen will be blank (no display)
USB networking should initialize automatically

Step 12: Identify USB Network Interface on Host

# Check for new USB network interface
ip link show

# Look for interface like: enx9e2b191eb8c7 or similar
# Should have an IP like 172.16.42.2

# Check IP address
ip addr show | grep 172.16

Step 13: First SSH Connection

# Try connecting (replace 'heeth' with your username)
ssh heeth@172.16.42.1

# Or if you set up root:
ssh root@172.16.42.1

# If using mDNS/avahi:
ssh heeth@postmarketos.local

If connection fails:

Wait another minute (device might still be booting)
Check USB cable connection
Verify USB interface exists: ip link show
Try IP: ping 172.16.42.1

PART 7: Post-Installation Setup (Run on Device via SSH)

Once you've successfully connected via SSH, run these commands:

Step 14: Fix DNS Resolution

# Remove systemd-resolved symlink
sudo rm /etc/resolv.conf

# Create static DNS configuration
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
echo "nameserver 8.8.4.4" | sudo tee -a /etc/resolv.conf

Step 15: Add Default Route

# Add default route for internet access
sudo ip route add default via 172.16.42.2

Step 16: Enable Internet Sharing on Host Computer

On your host computer (not the device), run:

# Enable IP forwarding
sudo sysctl -w net.ipv4.ip_forward=1

# Set up NAT (replace wlp3s0 with your internet interface)
# Find your interface with: ip route | grep default
sudo iptables -t nat -A POSTROUTING -o wlp3s0 -j MASQUERADE
sudo iptables -A FORWARD -i enx9e2b191eb8c7 -o wlp3s0 -j ACCEPT
sudo iptables -A FORWARD -i wlp3s0 -o enx9e2b191eb8c7 -m state --state RELATED,ESTABLISHED -j ACCEPT

Step 17: Test Internet Connection

Back on the device:

# Test IP connectivity
ping -c 3 8.8.8.8

# Test DNS (might fail due to IPv6)
ping -c 3 google.com

Step 18: Update System & Install Essential Tools

# Update package index
sudo apk update

# Upgrade all packages
sudo apk upgrade

# Install commonly needed packages
sudo apk add nano vim git curl wget htop

heethjain21/postmarketos-xiaomi-beryllium.md

Select an option

No results found