Overview

PhoneOS is a collection of standalone Preact + HTM web applications that work together as a cohesive mobile experience. No build step required — everything runs directly in the browser.

Your data. Your keys. Your phone.

• Decentralized Identity — Sign in with your Nostr keys (NIP-07 browser extension or raw private key)
• Portable Storage — Data stored on NosDav with DID discovery for custom endpoints
• Solid Compatible — All data uses JSON-LD format for interoperability
• Offline First — Service Worker caching with localStorage fallback
• Zero Build — Pure ESM imports from CDN, works anywhere

Features

| Feature | Description | |---------|-------------| | Android-style Launcher | Home screen with app grid, dock, widgets, and wallpaper customization | | NIP-07/NIP-98 Auth | Seamless authentication via Nostr browser extensions or raw keys | | DID Discovery | Automatic storage endpoint discovery from .well-known/did.json | | PWA Install | Install on any device — Android, iOS, or desktop | | Offline Mode | Full functionality without internet, syncs when back online | | JSON-LD Data | Solid-compatible linked data format for all stored content |

Apps

| App | Description | Storage Path | |-----|-------------|--------------| | Launcher | Android-style home with app grid, dock, widgets | public/startpage/startpage.json | | Bookmarks | Google Bookmarks clone with labels and search | public/bookmark/bookmark.json | | Todo | Task manager with filters, stats, and AI integration | public/todo/todo.json | | Notes | Markdown notes with folders and tags | public/notes/notes.json | | Contacts | Address book with vCard import/export | public/contacts/contacts.json | | Playlists | M3U playlist manager with audio player | public/playlists/playlists.json | | Weather | Forecast using Open-Meteo API | public/weather/weather.json | | Agents | AI agent builder with templates | public/agents/agents.json | | Memory | Memory match card game | public/memory/scores.json |

Installation

As a PWA

Android Chrome:

1. Visit the deployed site
2. Tap menu (⋮) → "Install app" or "Add to Home Screen"

iOS Safari:

1. Visit the deployed site
2. Tap Share → "Add to Home Screen"

Self-Hosted

# Clone the repository
git clone https://github.com/JavaScriptSolidServer/phoneos.git
cd phoneos

# Serve with any static server
npx serve .
# or
python -m http.server 8000

No build step required — just serve the files.

Architecture

Tech Stack

| Layer | Technology | |-------|------------| | UI | Preact + HTM (ESM from esm.sh) | | Crypto | @noble/secp256k1 for Schnorr signatures | | Storage | NosDav (WebDAV-style with Nostr auth) | | Identity | Nostr keys (NIP-07 / raw private key) | | Offline | Service Worker + localStorage |

Authentication Flow

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  NIP-07     │────▶│  Sign Event  │────▶│  NIP-98     │
│  Extension  │     │  (kind:27235)│     │  Auth Header│
└─────────────┘     └──────────────┘     └─────────────┘
                            │
                    ┌───────▼───────┐
                    │   nosdav.net  │
                    │   or custom   │
                    │   endpoint    │
                    └───────────────┘

Data Format

All data uses Solid-compatible JSON-LD:

{
  "@context": { "@vocab": "urn:solid:" },
  "@type": "Bookmark",
  "@id": "#bookmark-123",
  "title": "Example",
  "url": "https://example.com",
  "created": "2025-12-06T00:00:00.000Z"
}

Storage Discovery

PhoneOS uses DID discovery to find your storage endpoint:

1. Check /.well-known/did.json for NosDavStorage or SolidStorage service
2. Use custom endpoint if found
3. Fallback to nosdav.net/{pubkey}

Development

Adding a New App

1. Create newapp.html using existing apps as template
2. Include StorageConfig and NIP-98 auth code
3. Use storage path public/newapp/newapp.json
4. Add to home.html app grid
5. Add to DEFAULT_APPS in start.html
6. Add to CORE_ASSETS in sw.js
7. Bump CACHE_NAME version in sw.js

Project Structure

phoneos/
├── index.html          # Main launcher
├── start.html          # Alternative launcher
├── home.html           # App directory
├── *.html              # Individual apps
├── manifest.json       # PWA manifest
├── sw.js               # Service worker
├── storage-config.js   # Shared storage utilities
├── icons/
│   └── icon.svg        # App icon
└── public/             # User data (JSON-LD)
    ├── todo/
    ├── notes/
    ├── bookmark/
    └── ...

Roadmap

• [ ] Push notifications via Nostr relays
• [ ] Background sync for offline changes
• [ ] App permissions system
• [ ] Theme customization
• [ ] Plugin architecture
• [ ] E2E encryption for private data

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License — see LICENSE for details.