# Development guide [Back to PhoneBox](../README.md) · [Installation and connections](SETUP.md) · [User guide](GUIDE.md) [How it works](#how-it-works) · [Development](#development) ## How it works ```mermaid flowchart LR subgraph Phone["Android phone"] UI["Panel UI
(WebView, assets/www)"] -->|"/agent/*"| Proxy["Native proxy
(AgentLink)"] UI -->|weather, rates, HN| Web(("Public APIs")) end subgraph PC["Windows / Linux / macOS"] Agent["PhoneBox agent
(.NET 10)"] Agent --- Mon["System, GPU, media, volume,
processes, sessions, quotas, GitHub"] Agent --- Set["Settings page &
layout editor"] end Proxy -->|"USB: adb reverse → 127.0.0.1:8765"| Agent Proxy -.->|"Wi-Fi / Tailscale: HTTPS :8766,
pinned certificate + key"| Agent Hooks["Scripts, CI,
Home Assistant"] -->|webhooks| Agent ``` - The WebView never talks to the PC directly: requests to `/agent/*` are intercepted by the app and forwarded over the adb tunnel (or the pinned HTTPS connection), so there are no CORS, mixed-content or local-network issues. - Live events (page switches, notifications, permission prompts) arrive over one server-sent-events stream (`/api/stream`); plain polling remains as the fallback. - The agent samples only what is on screen: process lists and command widgets run only while a phone looks at them. ## Development Contributions are welcome: read [CONTRIBUTING.md](../CONTRIBUTING.md) first (scope, the security model, privacy and tests). Use the .NET 10 SDK for the agent, JDK 17 and Android SDK Platform 35 for Android builds, and Python 3 plus Node.js 22 for the browser tooling. The Gradle wrapper downloads Gradle automatically. Run the following commands from the repository root unless a working directory is shown. ### Local preview ```sh python tools/demo-server.py ``` The server stays running in this terminal. Open or . Use a second terminal for other commands. ### Checks ```sh python tools/check-release.py dotnet test agent/PhoneBox.Agent.Tests ``` Browser tests need Node.js 22 and Chromium: ```sh cd tools/ui-tests npm ci npx playwright install chromium npx playwright test ``` On Linux CI, use `npx playwright install --with-deps chromium`. Playwright starts its own demo on port 8781. ### Build and run On Windows, from the repository root: ```powershell .\scripts\build.ps1 # release APK + five agent archives in dist/ ``` To build only the Android app with API compatibility lint: ```powershell cd android .\gradlew.bat lintDebug assembleDebug ``` Run the Windows agent from the repository root: ```powershell dotnet run --project agent/PhoneBox.Agent -f net10.0-windows10.0.19041.0 ``` On Linux or macOS, run the agent with `dotnet run --project agent/PhoneBox.Agent -f net10.0` and build the APK with `cd android && ./gradlew assembleDebug`. On Windows, the explicit `-f` selects one of the project's two target frameworks. Set `ANDROID_HOME` or `android/local.properties` (`sdk.dir`) to the Android SDK location. ### Demo data and media The demo server needs only Python. It serves the same demo as the [live one](https://ersinkoc.github.io/phonebox/) (made-up data in [`tools/pages/demo.js`](../tools/pages/demo.js)) straight from the sources, so a reload shows your changes. Size the browser window to 780 × 360 (the phone's screen in CSS pixels) and the panel behaves as on the phone, including webhooks: `curl -X POST http://127.0.0.1:8790/api/notify -d hello` (also `/api/push/`, `/api/goto/` and `/api/ask` for a made-up permission prompt). With the demo server running, generate media from a second terminal: ```sh cd tools/ui-tests node media.js shots home system node media.js tour node media.js hero ``` Install the browser tooling above first. The tour also needs FFmpeg. Run `pwsh tools/make-icon.ps1` from the repository root to regenerate the application icon. ### Source layout The panel is plain ES modules: [`main.js`](../android/app/src/main/assets/www/main.js) (core, pages, navigation, data from the agent) and the widgets in [`widgets/`](../android/app/src/main/assets/www/widgets). A widget is a `{ needs, create(box, ctx) → { update(kind) } }` entry in the `W` registry, plus its styles in `style.css` and its catalogue entry (name, size, options) in [`widgets.json`](../agent/PhoneBox.Agent/widgets.json), which drives the settings editor. Templates live in [`templates.json`](../agent/PhoneBox.Agent/templates.json). ### Isolated agent runs To check a development agent beside an installed one, run it with an isolated settings file and port, for example `PhoneBoxAgent.exe --config "D:\test folder\config.json" --port 18765`. Settings and browser checks use `http://127.0.0.1:18765/`; restarts preserve these arguments. The ordinary port remains 8765. Set `deviceSerial` explicitly in the test settings (an unmatched serial disables USB attachment) and turn off automatic updates. USB clients still use phone port 8765; do not assign the same phone to two agents at once. ### Release signing Release APKs are signed with your own key when `PHONEBOX_STORE_FILE`, `PHONEBOX_STORE_PASSWORD`, `PHONEBOX_KEY_ALIAS` and `PHONEBOX_KEY_PASSWORD` are set (in `~/.gradle/gradle.properties` or the environment); otherwise the debug key is used. Debug builds make the WebView debuggable through `chrome://inspect`. To publish a release: bump the version in `PhoneBox.Agent.csproj` and `android/app/build.gradle.kts`, commit, then run `.\scripts\release.ps1`. The script dispatches the gated GitHub release workflow; see [the release checklist](RELEASING.md).