Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 94 additions & 0 deletions .github/workflows/setup.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
name: setup

# Runs the one-step installers (setup.ps1, setup.sh) for real against the published release:
# download, checksum, dependencies, install, start, and a second run that updates a running agent.
on:
pull_request:
paths: [setup.ps1, setup.sh, .github/workflows/setup.yml]
push:
branches: [main]
paths: [setup.ps1, setup.sh, .github/workflows/setup.yml]
schedule:
- cron: '17 6 * * 1' # weekly: the latest release against current winget, Homebrew and distribution packages
workflow_dispatch:

permissions:
contents: read

jobs:
lint:
name: Lint
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
with:
persist-credentials: false # the jobs run downloaded programs and need no Git access
- name: shellcheck
run: |
bash -n setup.sh
shellcheck setup.sh
- name: PSScriptAnalyzer
shell: pwsh
run: |
Install-Module PSScriptAnalyzer -Scope CurrentUser -Force
$issues = Invoke-ScriptAnalyzer -Path setup.ps1 -Severity Error, ParseError
$issues | Format-Table -AutoSize | Out-String -Width 200
if ($issues) { throw "PSScriptAnalyzer: $($issues.Count) error(s)" }

windows:
name: setup.ps1 (Windows PowerShell 5.1)
runs-on: windows-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false # the jobs run downloaded programs and need no Git access
- name: First install
shell: powershell
run: '& ([scriptblock]::Create((Get-Content -Raw .\setup.ps1))) -Yes -NoPhone -AllowAdministrator'
- name: Check the running agent
shell: powershell
run: |
$info = Invoke-RestMethod http://127.0.0.1:8765/api/info
"version $($info.version), adb $($info.adb)"
if (-not $info.adb) { throw 'setup did not install adb' }
if (-not (Test-Path "$env:LOCALAPPDATA\PhoneBox\app\PhoneBoxAgent.exe")) { throw 'agent not in the install folder' }
if (-not (Test-Path ([Environment]::GetFolderPath('Startup') + '\PhoneBox.lnk'))) { throw 'no Startup shortcut' }
- name: Second run replaces a running agent
shell: powershell
run: |
& ([scriptblock]::Create((Get-Content -Raw .\setup.ps1))) -Yes -NoPhone -AllowAdministrator
Invoke-RestMethod http://127.0.0.1:8765/api/info | Select-Object version, os
- name: Stop the agent
if: always()
shell: powershell
run: Get-Process PhoneBoxAgent -ErrorAction SilentlyContinue | Stop-Process -Force

unix:
name: setup.sh (${{ matrix.os }})
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, ubuntu-24.04-arm, macos-latest]
runs-on: ${{ matrix.os }}
env:
HOMEBREW_NO_AUTO_UPDATE: '1'
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false # the jobs run downloaded programs and need no Git access
- name: First install (piped, as with curl | bash)
run: cat setup.sh | bash -s -- --yes --no-phone
- name: Check the running agent
run: |
curl -fsS http://127.0.0.1:8765/api/info | tee /tmp/info.json; echo
python3 -c 'import json; i = json.load(open("/tmp/info.json")); assert i["adb"], "setup did not install adb"'
- name: Second run replaces a running agent
run: |
bash setup.sh --yes --no-phone --no-extras
curl -fsS http://127.0.0.1:8765/api/info >/dev/null
- name: Stop the agent
if: always()
run: |
launchctl unload "$HOME/Library/LaunchAgents/net.oxog.phonebox.agent.plist" 2>/dev/null || true
systemctl --user stop phonebox.service 2>/dev/null || true
pkill -x PhoneBoxAgent || true
16 changes: 16 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,21 @@
# Changelog

## Unreleased

**Setup**
- One-step installers: `irm https://raw.githubusercontent.com/ersinkoc/phonebox/main/setup.ps1 | iex` on Windows,
`curl -fsSL https://raw.githubusercontent.com/ersinkoc/phonebox/main/setup.sh | bash` on Linux and macOS. They
download the latest release and check its checksum (and its build provenance with a signed-in GitHub CLI). They
install adb and the optional helpers when missing, after asking, then the agent and start at login. They can also
put the app on a phone over USB, with step-by-step help for USB debugging, and finally start PhoneBox. Warnings
cover the unsigned build, antivirus, USB debugging, firewall, Linux USB permissions and macOS prompts. Running
setup again updates or repairs PhoneBox and keeps the settings; `-DryRun` / `--dry-run` changes nothing. A CI workflow runs
both installers on Windows, Linux x64/ARM64 and macOS every week.

**Docs**
- The README quick start is rewritten around setup: what it does, its options and warnings, connecting the phone
over USB or Wi-Fi only, other ways to install, and how to uninstall.

## 0.9.8 — 2026-11-15

Pair a phone over Wi-Fi without a USB cable: the computer shows a QR code, the phone scans it with its camera and
Expand Down
1 change: 1 addition & 0 deletions PRIVACY.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,7 @@ identifies your GitHub account to GitHub.
| OSC controls (Control Deck) | The OSC host and port you configure, over UDP | The control value |
| Antigravity quota through its CLI | Whatever the Antigravity CLI contacts with its own sign-in (PhoneBox only starts it) | Decided by the CLI |
| Webhooks | Inbound only: scripts and services you set up post to the agent | Nothing is sent out |
| Setup scripts (`setup.ps1`, `setup.sh`), when you run them | `raw.githubusercontent.com` (the script), `api.github.com` and `github.com` (release info and downloads); only for what is missing and after asking: winget, Homebrew or your distribution's package servers, or `dl.google.com` (adb) | The requests themselves; nothing about you or the computer. With `gh` 2.93.0 or later signed in, the GitHub CLI checks the build provenance with its own sign-in, which also contacts `tuf-repo.github.com` and Sigstore's servers (`tuf-repo-cdn.sigstore.dev`) |

When the phone has no internet connection of its own, the agent can fetch the public widget feeds above (Open-Meteo,
Hacker News, Frankfurter, CoinGecko) on its behalf. Only those hosts are allowed, and the same data is sent.
Expand Down
171 changes: 138 additions & 33 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,54 +69,159 @@ These screenshots use made-up demo data. See the [changelog](CHANGELOG.md) for a

## Quick start

**[Download the latest PhoneBox release](https://github.com/ersinkoc/phonebox/releases/latest)** — signed Android APK and
agents for Windows x64, Linux x64/ARM64 and macOS Apple Silicon/Intel. From 0.9.7 the agent is a single
self-contained program: unzip and run it, no .NET to install (0.9.6 and earlier need the .NET 10 runtime, the Desktop
Runtime on Windows). The release includes SHA-256 checksums and build provenance.
Existing users can update from Settings; existing layouts and pairing settings are retained.
### 1. Install PhoneBox on the computer

For a phone that will only use Wi-Fi, install the APK from the release on the phone and pair with a QR code (see
[Wi-Fi & Tailscale](#wi-fi--tailscale)); app updates then come from the release page instead of over USB.
**Windows 10/11**: open PowerShell (a normal window, not *Run as administrator*) and paste:

Over USB, you need an Android 9+ phone with [USB debugging](https://developer.android.com/studio/debug/dev-options) turned on,
the [.NET 10 SDK](https://dotnet.microsoft.com/download) and `adb`.
The source installers below build the agent locally. To build the phone app, also install **JDK 17** and
**Android SDK Platform 35** (for example through Android Studio), set `JAVA_HOME`, and point `ANDROID_HOME` or
`android/local.properties` (`sdk.dir`) at the SDK. The installers can use a release APK from `dist/`; the Windows
installer rebuilds it when Android sources are newer, or when `-BuildApk` is supplied.
```powershell
irm https://raw.githubusercontent.com/ersinkoc/phonebox/main/setup.ps1 | iex
```

**Windows 10/11**
**Linux and macOS**: open a terminal and paste (run it as yourself, not with `sudo`):

```powershell
winget install Microsoft.DotNet.SDK.10 Google.PlatformTools # .NET 10 and adb
git clone https://github.com/ersinkoc/phonebox
cd phonebox
.\scripts\install.ps1 -Apk -Autostart # agent + phone app, start with Windows (add -Serial <id> if several devices are connected)
```sh
curl -fsSL https://raw.githubusercontent.com/ersinkoc/phonebox/main/setup.sh | bash
```

Or install just the agent with **Scoop** and let it put the app on the phone (settings › General › *Install the
phone app*, with the phone plugged in):
Setup installs the [latest release](https://github.com/ersinkoc/phonebox/releases/latest) and anything missing:

1. **Checks the computer**: Windows x64; Linux x64 / ARM64 with glibc; macOS on Apple silicon or Intel.
2. **Downloads and checks the agent**: the download must match the release's SHA-256 checksums. With the
[GitHub CLI](https://cli.github.com) signed in, it also verifies the build provenance (`gh attestation verify`).
No .NET to install: the agent is one self-contained program.
3. **Installs adb if it is missing**, after asking. adb is the USB link to the phone. Setup gets it from winget, Homebrew or
your distribution (apt, dnf, pacman, zypper), or from Google's download as a fallback.
4. **Offers optional helpers** for more widgets. On Linux: `playerctl` for Now Playing, `pactl` for volume, and `xprintidle`.
On macOS: `nowplaying-cli`.
5. **Installs the agent for your user only**:

| | Program | Settings (kept on reinstall) |
|---|---|---|
| Windows | `%LOCALAPPDATA%\PhoneBox\app` | `%APPDATA%\PhoneBox` |
| Linux | `~/.local/share/PhoneBox/app` | `~/.config/PhoneBox` |
| macOS | `~/Library/Application Support/PhoneBox/app` | `~/Library/Application Support/PhoneBox` |

Then it asks whether to start PhoneBox at login: a Startup-folder shortcut on Windows, a systemd user service
on Linux, a launchd agent on macOS.
6. **Puts the app on the phone over USB**, if you want. It shows how to turn on USB debugging and waits for the phone.
7. **Starts the agent** and opens its settings at <http://127.0.0.1:8765>.

Setup needs no administrator rights. On Linux it uses `sudo` only to install packages, and asks first. Run it again
any time to update or repair PhoneBox; settings and pairings are kept. Read [`setup.ps1`](setup.ps1) or
[`setup.sh`](setup.sh) before you run it if you like. With `-DryRun` / `--dry-run` it downloads and checks everything
and changes nothing.

<details><summary><b>Setup options</b></summary>

| Windows (`setup.ps1`) | Linux / macOS (`setup.sh`) | |
|---|---|---|
| `-Yes` | `--yes` | Take the default answer to every question (unattended) |
| `-NoPhone` | `--no-phone` | Do not install the app over USB (for a Wi-Fi-only phone) |
| `-Serial <id>` | `--serial <id>` | The phone to use when several are connected (`adb devices`) |
| `-NoAutostart` | `--no-autostart` | Do not start PhoneBox at login |
| `-NoStart` | `--no-start` | Install only |
| — | `--no-extras` | Do not offer the optional helpers |
| `-Version 0.9.8` | `--version 0.9.8` | Install that release instead of the latest |
| `-DryRun` | `--dry-run` | Download and check, change nothing |

To pass options:

```powershell
scoop bucket add phonebox https://github.com/ersinkoc/phonebox
scoop install phonebox/phonebox # needs adb (scoop install main/adb); 0.9.6 and earlier also the .NET 10 Desktop Runtime
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/ersinkoc/phonebox/main/setup.ps1))) -NoPhone
```

```sh
curl -fsSL https://raw.githubusercontent.com/ersinkoc/phonebox/main/setup.sh | bash -s -- --no-phone
```

A winget package (`ersinkoc.PhoneBox`) is prepared in [`packaging/winget`](packaging/winget) for submission to
winget-pkgs; once accepted it installs with `winget install ersinkoc.PhoneBox`.
</details>

<details><summary><b>Before you run it: warnings</b></summary>

- **The Windows agent is not code-signed yet.** The [SignPath Foundation](#code-signing-policy) application is pending.
Windows SmartScreen or an antivirus may warn about a new, unsigned program, and some antivirus engines have flagged
it ([#69](https://github.com/ersinkoc/phonebox/issues/69)). Setup only installs a file that matches the release
checksum. If your antivirus removes `PhoneBoxAgent.exe`, setup says so; restore it from quarantine or report it.
- **Smart App Control** (Windows 11) blocks programs that are neither signed nor known to Microsoft. The release
agent has run with it on, while agents built from source can be blocked. Setup tells you when it is on. If it
blocks PhoneBox, don't turn it off for PhoneBox: it cannot be turned back on without resetting Windows. Report
the message in [#69](https://github.com/ersinkoc/phonebox/issues/69) instead.
- **USB debugging gives a computer you allow control over the phone.** Allow only your own computers. You can
withdraw them on the phone under *Developer options › Revoke USB debugging authorisations*.
- **Wi-Fi is off until you turn it on.** Until then the agent listens only on this computer (`127.0.0.1:8765`).
When you turn it on, Windows asks to let PhoneBox through the firewall: allow *Private* networks only. On Linux
with ufw or firewalld, open TCP port 8766 for your local network. Every connection PhoneBox makes is listed in
the [privacy policy](PRIVACY.md).
- **Linux USB permissions**: if `adb devices` shows `no permissions`, adb also needs udev rules. Install
`android-sdk-platform-tools-common` on Debian/Ubuntu or `android-udev` on Arch. Some systems also need the
`plugdev` group (`sudo usermod -aG plugdev $USER`, then log out and in). Setup points this out when it happens.
- **On macOS**, the agent is signed ad hoc, not with an Apple Developer ID. The first time, macOS may ask whether
it may control Music or Spotify (for Now Playing), or accept incoming connections (with Wi-Fi on).
- **Windows USB drivers**: if the phone never appears, Windows may need its USB driver. Google phones use the
Google USB Driver; other brands have one on their support site.
- **Scoop users**: setup stops if PhoneBox is installed with Scoop, so two copies don't fight over the same port.
Keep using `scoop update phonebox`, or `scoop uninstall phonebox` first and then run setup.
- **Windows on ARM** and **musl Linux** (Alpine) have no release build yet.

</details>

### 2. Connect the phone

**Linux** (Ubuntu, Debian, Fedora, Arch…) **and macOS**
- **Over USB** (recommended): it wakes the phone on plug-in, updates the app and falls back to USB when Wi-Fi drops.
The phone needs Android 9 or later with USB debugging turned on:
1. *Settings › About phone*: tap *Build number* seven times.
2. *Developer options*: turn on *USB debugging*. On Xiaomi, Redmi and POCO, also turn on *Install via USB*.
3. Plug the phone in with a data cable and answer *Allow USB debugging?* with *Allow*.

Setup installs the app, or use *Settings › General › Install the phone app* later. Then the phone wakes up and
opens the panel whenever it is plugged in.
- **Over Wi-Fi only**, with no developer options or adb: install the APK from the
[release page](https://github.com/ersinkoc/phonebox/releases/latest) on the phone. Then on the computer turn on
*Settings › General › Wi-Fi & Tailscale*, click **Pair a phone over Wi-Fi** and scan the QR code (see
[Wi-Fi & Tailscale](#wi-fi--tailscale)).

The settings are at <http://127.0.0.1:8765>, on Windows also from the tray icon.

### Other ways to install

- **Manual download**: the [release](https://github.com/ersinkoc/phonebox/releases/latest) has the signed Android
APK and agents for Windows x64, Linux x64/ARM64 and macOS Apple silicon/Intel, with SHA-256 checksums and build
provenance. Unzip the agent and run it. It can update itself only from the install folder in the table above.
- **Scoop** (Windows), which can then put the app on the phone from *Settings › General › Install the phone app*:

```powershell
scoop bucket add phonebox https://github.com/ersinkoc/phonebox
scoop install main/adb phonebox/phonebox
```

- **winget**: a package (`ersinkoc.PhoneBox`) is prepared in [`packaging/winget`](packaging/winget) for
winget-pkgs. Once it is accepted, `winget install ersinkoc.PhoneBox` will install it.
- **From source** (for development): needs the [.NET 10 SDK](https://dotnet.microsoft.com/download) and `adb`. To build
the phone app it also needs **JDK 17** and **Android SDK Platform 35** (for example through Android Studio), with
`JAVA_HOME` set and `ANDROID_HOME` or `android/local.properties` (`sdk.dir`) pointing at the SDK.

```powershell
git clone https://github.com/ersinkoc/phonebox; cd phonebox
.\scripts\install.ps1 -Apk -Autostart # add -Serial <id> with several devices; -BuildApk always rebuilds the app
```

```sh
git clone https://github.com/ersinkoc/phonebox && cd phonebox
./scripts/install.sh --apk --autostart # systemd user service (Linux) or launchd agent (macOS)
```

### Uninstall

```powershell
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/ersinkoc/phonebox/main/scripts/uninstall.ps1))) # add -Purge -Apk
```

```sh
sudo apt install adb playerctl # Fedora: android-tools playerctl · macOS: brew install android-platform-tools nowplaying-cli
git clone https://github.com/ersinkoc/phonebox
cd phonebox
./scripts/install.sh --apk --autostart # agent + phone app; systemd user service (Linux) or launchd agent (macOS)
curl -fsSL https://raw.githubusercontent.com/ersinkoc/phonebox/main/scripts/uninstall.sh | bash -s -- # add --purge --apk
```

Plug the phone in: it wakes up and opens the panel. The settings are at <http://127.0.0.1:8765> (on Windows also
from the tray icon). `scripts/uninstall.ps1 [-Purge] [-Apk]` / `scripts/uninstall.sh [--purge] [--apk]` remove
everything again.
Without options it removes the program and the start-at-login entry and keeps the settings. `-Purge` / `--purge` also
deletes the settings, and `-Apk` / `--apk` removes the app from the connected phone.

<details><summary><b>What works where</b></summary>

Expand Down
Loading
Loading