# Pocket / Arch Linux ARM phone project A new Linux-based direction for your phone: a minimal console Arch Linux ARM system, Phosh/Phoc Wayland session, a custom native GTK4 home and settings app, styled graphical login, and a prebuilt application installer. **Status: source and deployment starter, not a bootable OS image.** The old bare-metal kernel is not used. Backend tests and the separate design preview were checked on Windows. GTK/Phosh, package installation, boot, physical radios and calls still require testing inside a Linux ARM target. ## See the design on Windows Open `preview/index.html` in your browser. Navigate Home, Apps, Settings, and the login concept. It works without a server and uses no external assets. This is an interactive visual mockup: its controls do not change your computer, install apps, authenticate or make calls. The native application lives in `app/`. ## Everyday defaults and customization The default home uses a soft Dawn wallpaper, a compact four-column app grid, a rounded dock and original app artwork. The layout takes inspiration from familiar phone interfaces while retaining Pocket's own design. Open **Settings → Appearance** to choose Light/Dark, Dawn/Ocean/Night wallpapers, Blue/Mint/Violet accents, three/four grid columns, three icon sizes, app labels, and reduced motion. Select **Choose icon** beside an app to import your own PNG/JPEG/WebP/SVG; **Restore** returns to the original. **Restore appearance defaults** resets the launcher style and all icon overrides. Installed Linux apps supply their desktop-entry icons through Gio and the installed icon theme. YouTube/Discord web shortcuts use official site favicons and remain labeled Web. Preview artwork is copied unmodified from upstream; see `preview/assets/CREDITS.md` and the included license notices. Linux preferences live in `$XDG_CONFIG_HOME/pocket-os/appearance.json` (normally `~/.config/pocket-os/appearance.json`). Imported icons are copied into that folder so removing the original image does not break them. Preview choices save in browser local storage and are independent of Linux preferences. These settings style Pocket Home. Phosh's multitasking/lock screen, the login greeter, and other apps have their own appearance configuration. The login preview is a visual concept rather than an exact gtkgreet screenshot. ## What the actual Linux stack does | Component | Purpose | | --- | --- | | Arch Linux ARM, AArch64 | ARM64 Linux base, kernel and native package repositories | | Phosh + Phoc | Mobile session, multitasking, touch input, compositor and lock screen | | Squeekboard | On-screen keyboard in the Phosh session | | Pocket Home, GTK4/Python | Custom touch-friendly launcher, app search, settings front end | | greetd + gtkgreet + Cage | PAM-authenticated graphical login with custom CSS | | NetworkManager | Wi-Fi and mobile data connection management | | BlueZ | Bluetooth controller and device management | | ModemManager + GNOME Calls | Modem management and calling UI | | Chatty | SMS and supported messaging services | | PipeWire + WirePlumber | Audio services; physical modem audio needs board configuration | | GNOME Software + Flatpak/Flathub | Existing graphical app installer and Linux app catalog | The custom launcher is a regular native app that auto-starts **inside Phosh**. It does not replace the compositor, multitasking UI or secure lock screen. It reads real service status and launches installed desktop applications. Missing hardware is reported as unavailable rather than simulated as connected. ## Deploy inside a fresh ARM64 Linux installation 1. Choose a bootable Arch Linux ARM target appropriate for the board or emulator. Follow the upstream platform instructions. This project does not partition disks, install a bootloader, download a root filesystem, or choose a device tree. 2. Use the terminal-only base first. Initialize the Arch Linux ARM keyring, update, replace the default root/alarm passwords and create your own non-root user. 3. Copy this project into that target. Keep terminal/serial access for recovery. 4. Run the profile as root, substituting your existing account name: ```bash sudo bash scripts/install.sh youruser ``` This installs the graphical phone stack and custom launcher, configures network services for the next boot, and adds Flathub. It does not start/stop the current network connection or reboot automatically. It enables NetworkManager and disables systemd-networkd for next boot so both do not manage the same devices. systemd-resolved handles DNS. Review local resolver configuration on your target. To also configure the styled graphical login on a **fresh** system: ```bash sudo bash scripts/install.sh youruser --login ``` The installer refuses to replace a different enabled display manager. Existing greetd configuration is backed up before changes. No default passwords, automatic login or password storage are introduced. Initial gtkgreet login requires a physical/virtual keyboard; touch-only first-login text entry has not been implemented or tested. Phosh's session lock screen and Squeekboard are retained. Without the login option, log into the terminal as your non-root user and run: ```bash /usr/local/bin/pocket-session ``` The installer uses signed repository packages and a full `pacman -Syu` upgrade. Package names are recorded in `profiles/packages.txt`; rolling-release changes can require updating that list. It deliberately does not install every GNOME package, but Phosh's real dependency set is larger than a console-only base. ## Terminal and public downloads **Terminal** is a custom GTK4/VTE app that opens your real account shell through a pseudoterminal. It supports installed Arch commands and interactive programs, scrollback, font zoom, copy/paste, and touch shortcut keys. The profile includes Fastfetch and a pinned source build of areofyl/fetch packaged as `pocket-fetch`. See `docs/TERMINAL.md` for installation and native validation requirements. The public preview includes an explicitly labeled terminal demo and a Downloads page. `tools/build_release.py` creates a source ZIP and a SHA-256 release manifest. There is no bootable OS image yet. The homemade phone remains the main physical target; existing Android phones require individual Linux ports and images. See `docs/RELEASES.md` for the device-specific release plan. Device profiles now live in `profiles/devices/`. The release catalog identifies exact hardware targets and blocks image publication until core test results, validation evidence and public first-boot account setup are present. Only the QEMU ARM64 development profile is configured; no physical phone is supported. `scripts/build-qemu-image.sh` creates a local candidate on an AArch64 Linux builder using prebuilt kernel packages. `tools/run_emulator.py` launches that candidate with 2 GiB RAM by default. The workflow has not been executed here. See `docs/EMULATOR.md` and `docs/DEVICE_PORTS.md` for prerequisites and release gates. ## Internet and apps Connect using system Wi-Fi settings, then open **App Store**. GNOME Software provides the UI and Flatpak provides the app installation backend. Apps must be published for **aarch64**; an x86_64 binary does not become ARM-compatible because the OS uses ARM. Native installed apps are discovered using Gio desktop entries. YouTube and Discord buttons open their websites in the installed browser. They are not promises of native Android apps, Google Play services or every browser feature. Native Android app support is not part of this profile. A future Waydroid experiment needs compatible kernel features and app/service compatibility checks. ## Physical phone work still required Wi-Fi, Bluetooth, touch, GPU acceleration, SIM, voice/audio, suspend, charging and battery reporting need supported hardware plus firmware and drivers. A SIM slot alone does not provide modem support. Calls need modem voice/VoLTE support, carrier service and correct microphone/speaker routing. QEMU cannot validate those parts. Your goals remain approximately 6 inches, 256 GB storage and 32 GB RAM if feasible. No board is selected, and these capacities are not yet hardware commitments. See `docs/HARDWARE.md` for the acceptance checks before choosing components. ## Checks On Windows or Linux, test the pure Python service adapters: ```text python -m unittest discover -s tests -v ``` These tests cover missing tools, denied operations, argument-vector execution, timeouts, preference persistence/reset, malformed settings, and icon import. They do not test GTK or real radio drivers. Inside the Linux target: ```bash bash scripts/doctor.sh /usr/local/bin/pocket-home ``` Manually test login, touch/keyboard input, lock/unlock, app installation, real networking, Bluetooth pairing, sound and calls. `doctor.sh` is read-only. Its status output does not certify physical voice calling or emergency calling. ## References checked for this starter - [Arch Linux ARM generic AArch64 base](https://archlinuxarm.org/platforms/armv8/generic) - [Phosh ARM64 package](https://archlinuxarm.org/packages/aarch64/phosh) - [GNOME Software ARM64 package](https://archlinuxarm.org/packages/aarch64/gnome-software) - [Flatpak ARM64 package](https://archlinuxarm.org/packages/aarch64/flatpak) - [GNOME Calls ARM64 package](https://archlinuxarm.org/packages/aarch64/gnome-calls) - [Chatty ARM64 package](https://archlinuxarm.org/packages/aarch64/chatty) - [gtkgreet style and login options](https://man.archlinux.org/man/gtkgreet.1.en) - [ModemManager documentation](https://modemmanager.org/docs/) Custom project source is MIT licensed; installed upstream software retains its own licenses. The project name is a placeholder you can rename. Vendored areofyl/fetch retains its ISC license in `third_party/fetch/LICENSE`.