Phosh is a phone shell based on the GNOME stack. It is developed by Purism for their own Linux smartphone, the Librem 5. With postmarketOS, it can be used on various other mobile devices too. We have shipped the PinePhone postmarketOS community edition with Phosh.
- 1 Installation
- 2 Usage
- 2.1 First Boot
- 2.2 Contacts, SMS and calls
- 2.3 Install software
- 2.4 Take a screenshot
- 2.5 Camera
- 2.6 External monitor
- 3 Configuration
- 4 Troubleshooting
- 5 See also
pmbootstrap, Phosh can be installed by selecting it as the UI in
On existing systems, it can be installed by installing the
postmarketos-ui-phosh meta package or
phosh if postmarketOS specific customization is not wanted.
pmbootstrap install to flash a phone or sd card you'll be prompted for a user password. Make sure to only use numeric characters [0-9] in this password as the phosh lock screen uses this password as a pin. On an existing phosh install you can change your user password and pin in the terminal with the standard
As with all other interfaces in postmarketOS, the first boot takes longer than usual: the file system will be resized to use the entire device. The first start of Firefox also takes longer than the following starts.
Install updates and reboot
Unless you have just built your own postmarketOS image a few minutes before doing the installation, it is highly recommended to install updates and then reboot your device. To do that, open the "Software" app, tap the "Updates" button on the bottom right. Then tap "Update All". When the updates are finished, all listed packages will disappear and you will be left with a screen showing only a horizontal line.
Once all updates are installed, reboot so you are actually using the newly installed software and not still the old versions. To do that, tap the top bar between the clock and the battery icon, tap the power symbol and then "Restart". Note that the PinePhone currently takes >30s to power off (pmaports#738).
After rebooting, update the "Software" app once again. If you are running the build that was shipped with the PinePhone, you will immediately see an update for
mobile-config-firefox (apk-polkit#18). Install this one too, so Firefox is configured for mobile. This tiny update does not need a reboot.
Do not report issues unless you have made sure that you have rebooted into an up-to-date system.
SSL handshake failed notification
The notification 'Unable to download updates from "odrs.gnome.org" ... SSL handshake failed' can be ignored. Just tap the "x" at the bottom, so it does not cover the "Update All" button anymore.
This message appears if you have just connected to Wi-Fi, and your device's date was not synced with the Internet yet (see the clock that is visible in the top bar). Then GNOME software will fail to download some software ratings via the secure HTTPS protocol, because it can't verify the server's certificates without knowing the date (as they could have expired). For our use case, this is all irrelevant: we don't need the software ratings right now, we want to do updates. Because these updates are signed with a different mechanism already, we don't use HTTPS, but instead the plain HTTP to download them. So we don't even need to have the date synced.
It's highly recommended to enable and test SSH access to your phone, so you can control your phone from the terminal, transfer files and take part in development.
Contacts, SMS and calls
Unlock SIM card
If your SIM card needs a PIN, Phosh will display a SIM card icon with a question mark on top in the top bar. Open the top menu (tap between clock and battery icon), then tap the bigger SIM card icon again to type in the PIN.
Open the bottom menu, and open the "Contacts" app (blue book with
@ sign). The "Contacts Setup" screen will appear. Select the "Local Address Book" (read below for more options) and "Done". An empty contact list appears.
+ button on the left to add a contact. If you go to the bottom menu (tap the bottom arrow) and open the app again, the "New Contact" screen appears.
Fill out at least the name and phone number, then hit "Add" on the top right.
Synchronization with an online account
For convenience, some people may choose to synchronize their contacts with an online account. In order to do that, close the "Contacts" app (otherwise "Settings" will not open). Then open "Settings" from the bottom menu. Select "Online Accounts" and then add a provider where contact synchronization is supported). After you have added your online account, you should be able to select it in the "Contacts" app.
Note that the online account providers also list services, which are known bad actors in regards of privacy (pmaports#725). From a privacy and anti-mass-surveillance point of view, the best solution is not using contact synchronization at all, or using a self-hosted solution (e.g. with Nextcloud).
Make a call
Either open the "Contacts" app and tap on the call icon next to an existing contact. Or open the "Calls" app, select "DialPad" at the bottom and type in the number (selecting existing contacts from within the "Calls" app is currently not possible: calls#88).
Previously called contacts / typed in numbers and received calls appear in "Recent" and can be called again from there. If you want to avoid typing in a number, consider calling the phone running Phosh from another phone. Then the number will appear in "Recent" as well and can be called back.
Add the target phone number as contact (as described above). Then open the "Chats" app (the one with two message bubbles), hit the "+" on the top right, select the contact and start typing your SMS.
Alternatively, write an SMS from another phone to your phone running Phosh to start a conversation.
The "Software" app doesn't show the applications available in postmarketOS and Alpine yet (pmaports#699). The best way to install new software is currently via SSH with Alpine's package keeper (
apk, no relation to the Android app format). Use
apk search to find software, and
apk add to install it. Read
apk -h for usage information.
To install the PDF reader Evince for example:
$ sudo apk add evince
Take a screenshot
Currently there is no way to take a screenshot directly from the user interface, however you can take a screenshot from the terminal!
First install grim using
sudo apk add grim. Invoking
grim results in a screenshot of the entire screen being saved into the current working directory.
If you need to delay the screenshot for e.g. 10 seconds you can do that as well:
sleep 10 && grim.
If you need to invoke grim from an SSH session you need to first log in as the
user account (
su - user) and then invoke grim with a special environment variable:
If your phone is able to make photos on postmarketOS (if unsure, check the device wiki page), run the Megapixels app to take photos.
If it is not installed already, and it does not show up in the "software" app (pmaports#699), install it via SSH:
$ sudo apk add megapixels
It is also recommended to install
nemo to view and browse the images that were taken. Both can be opened from Megapixels once installed. New installations of postmarketOS with Phosh will come with all three apps installed by default.
Plug in a cable to your external monitor into your phone. Phosh should recognize the screen automatically and you should be able to use it. For the PinePhone, see this demo video.
Need a reminder of keyboard shortcuts to move applications between screens?
postmarketos-ui-phosh is installed, Phosh will be automatically launched via the TinyDM display manager.
It can also be launched manually by running
The Phosh screen may be scaled lower for better compatibility with existing applications. Change the scale by modifying the scale factor variable found in /usr/share/phosh/phoc.ini, which has a default value of 2.
Screen scaling may also be performed on-demand from the command line or by making an application by following the Purism Easy Librem 5 App Development: Scale the Screen blog post. Those instructions work well for devices running Phosh even if written for a Librem5 running PureOS (Debian-based OS). Keep in mind some commands will need to be modified to work on postmarketOS.
If you have trouble configuring everything with the graphical dialogs or just want to use the terminal, read along.
Unlock your SIM card with the PIN:
mmcli -i 0 --pin=12345
Configure your APN for mobile data (example for mobile vikings in Belgium):
mmcli -m 0 --simple-connect='apn=web.be,user=web,password=web,pin=1111'
Firefox looks weird
Firefox should look like this (on the right) after installing all updates. If the address bar is cut off, you don't have
mobile-config-firefox installed. Make sure you have installed all updates, rebooted, and checked for updates again (as described in install updates and reboot above).
If you would like to contribute to mobile-config-firefox, see the related project page.
Reading the log
Phosh related applications are logging to
~/.xsession-errors. It's recommended to only share the relevant piece of the log file, read through it and redact personal information (your phone number!) before sharing. Login via SSH, then read the file:
$ su - user $ tail -f ~/.xsession-errors