Skip to content

README.md

Latest commit

 

History

History
103 lines (82 loc) · 5.54 KB

README.md

File metadata and controls

103 lines (82 loc) · 5.54 KB
Raw

DawnShell documentation

한국어 · Project home · Latest release

This is the documentation home for both first-time users and contributors. If you are installing DawnShell for the first time, follow only the First setup path below.

Read this first

DawnShell requires root. Debian shares Android's kernel and network and is not a fully isolated virtual machine. Prepare an independent recovery path before enabling Docker bridge networking, exclusive USB passthrough, or the unsafe CE override.

First setup path

Step Action Success signal
1 Follow the installation guide to install the APK and approve root. The root result contains uid=0.
2 Save BFU settings and install Debian 13. The install log ends with INSTALL_SUCCEEDED.
3 Configure systemd and SSH. The configuration log ends with CONFIGURE_SUCCEEDED.
4 Export the SSH private key and connect. You log in as debian.
5 Reboot, stay locked, and connect again. SSH works during BFU and survives first unlock.

Use the user manual for routine operation and the troubleshooting guide when a step fails.

Find a task

I want to… Read…
Install DawnShell and prove BFU SSH Installation guide
Understand every app control User manual
Diagnose a specific error Troubleshooting guide
Know what my kernel must support Kernel requirements
Look up an abbreviation Glossary
Use a USB device from Debian USB sharing and passthrough
Run Docker safely Docker
Use H.264/HEVC hardware acceleration FFmpeg hardware codec guide
Understand -hwaccel mediacodec compatibility FFmpeg MediaCodec compatibility
Interpret gsmi Accelerator status monitor
Build or release the app Build and release
Validate a physical device Testing

User guides

Document Covers
Installation Download verification, root approval, Debian setup, SSH key export, first BFU test
User manual Every app section, lifecycle, SSH, accounts, USB, codecs, Docker, logs, removal
Troubleshooting Boot, root, install, SSH, Docker, USB, and codec failure playbooks
Glossary BFU, AFU, DE, CE, rootfs, cgroups, namespaces, and other terms
Kernel requirements Required and optional kernel options, known kernel defects, and when to build your own
FFmpeg hardware codec File conversion, audio copy, HLS, USB webcams, automatic wrappers, raw pipelines
FFmpeg MediaCodec compatibility Accepted upstream syntax, supported options, and fallback rules
gsmi accelerator monitor Reading 3D GPU and video-codec activity separately

Operations and validation

Document Covers
Security model Storage, root, SSH keys, Docker, USB, and codec trust boundaries
Testing BFU/AFU, five boots, networking, USB, Docker, and codec validation
Progress Implemented features, completed device checks, remaining validation

Architecture and development

Document Covers
Architecture Boot flow, storage boundaries, namespaces, cgroups, duplicate prevention
Rootfs installation Embedded tools, signature/hash verification, atomic publication, failure preservation
Debian systemd and SSH Runtime mounts, PID 1, networking, SSH policy, stop and restart
Hardware codec worker protocol memfd/eventfd, wire format, hardware selection, limits
Hardware codec decision record Why the final private-worker design was selected and what remains out of scope
Build and release Local build, parallel jobs, CI, signing, release contents

Licensing and notices

Document Covers
License bundle Licenses shipped in the APK and release obligations
Android dependency notices Gradle-packaged Android library license notices
Embedded runtime notices Native tools, Debian material, and source correspondence

Conventions

  • Replace PHONE_IP with the phone's current address.
  • Replace <version> with the release version being installed.
  • Commands beginning with sudo need Debian root privileges.
  • Bold text names an app control.
  • BFU is the period before the first unlock after reboot; AFU is after it.

Do not copy shell prompt characters ($ or #). A trailing \ means the command continues on the next line.

Reporting a problem

  1. Run the matching section in the troubleshooting guide.
  2. Open the relevant in-app live log and copy the complete output.
  3. Include Android version, CPU ABI, DawnShell version, selected options, and exact reproduction steps.
  4. Remove passwords, SSH private keys, API tokens, and reusable VPN auth keys.