How-to & tips

PhoneBox: Turn an Old Android Phone Into a PC Desk Panel Safely

Set up PhoneBox on Windows, Linux or macOS to use a spare Android phone as a stats and control panel, with checksum, USB debugging and network safety checks.

By EpiFive Editorial TeamReviewed/updated 11 min readHow we check our guides
On this page

PhoneBox is a free, open-source app pair that turns a spare Android phone into a touch desk panel for your computer: system stats, music controls, AI coding quotas and your own shortcuts. To set it up, install the PhoneBox agent on your PC, then connect the phone by USB or by paired Wi-Fi. The safe way to do that is to read the install script first, check the download, and keep the agent off the internet.

Who this is for and what you will have

This guide is for anyone with an old Android phone in a drawer and a Windows, Linux or macOS computer: developers who want to see AI coding quotas at a glance, streamers, and home-office users who want a volume and mute panel. By the end you will have the agent running on your computer, the phone showing a panel, and a short list of checks that keep a tool that can run shortcuts on your PC from becoming a risk.

PhoneBox is a third-party project, not a product of Google, Microsoft or Apple. It is young, so details change quickly. This article follows the project's README, release notes and security policy as read on 2026-11-21; check them again before you install.

What PhoneBox is

According to the project README, PhoneBox turns an old Android phone into a desk panel for PC stats, AI coding sessions, music and touch controls. It is MIT licensed, needs no root access, account or cloud service, and connects over USB or Wi-Fi. It ships with 30 templates and 13 interface languages. The widget count is not consistent on the project's own pages: the repository's About box says 124 widgets while the README says 126. Treat either as "over a hundred."

The README lists these requirements:

ItemRequirement
PhoneAndroid 5.0 or newer (Android 6 or later recommended); no iOS version
ComputerWindows 10/11 x64, Linux x64 or ARM64 (glibc), macOS on Apple silicon or Intel
Not supportedWindows ARM and musl-based Linux such as Alpine (no release builds)
USB connectionA data cable (not charge-only) and USB debugging
Wi-Fi connectionNeither a cable nor USB debugging
RuntimeRelease agents bundle .NET, so no separate install

What the agent can do, and why that matters for safety

The widgets cover system stats, media and audio controls, device batteries, and AI coding tools. The README describes quota and reset-time widgets for Claude, Codex and Antigravity, local Claude Code, Codex and OpenCode sessions (including sessions inside WSL), and GitHub review and CI status. Opt-in permission prompts let you press Allow or Deny on the phone for Codex, Claude Code and OpenCode requests.

The project's own security policy states that "PhoneBox can run shortcuts and control local applications." That sentence is the reason for the rest of this guide. Anything that can reach the agent can ask your computer to do things, so the question is always who can reach it. The policy names three intended routes: loopback on the local machine, a key-checked USB tunnel, and an authenticated, pinned-TLS Wi-Fi connection.

Before you start

  1. Pick a phone with a battery in good shape. If the battery is swollen, do not use the phone as an always-plugged panel.
  2. Make sure the phone runs Android 5.0 or newer.
  3. For USB, get a cable that carries data. Charge-only cables are a common reason a phone never appears.
  4. On the computer, use your normal user account. The README tells Linux and macOS users to run the installer as their own user and Windows users to use a normal PowerShell window.
  5. Decide how you want to connect. USB is simplest and charges the phone. Wi-Fi pairing avoids USB debugging, which is the stronger choice if the phone will sit on a stand all day.

Step 1: Read the install script before you run it

The README documents one-line installers. Running a script straight from the internet is convenient and also the habit security guidance warns against, so download it, read it, then run it.

Windows (PowerShell, normal window), documented install command:

irm https://raw.githubusercontent.com/ersinkoc/phonebox/main/setup.ps1 | iex

Instead of piping straight into iex, save the script and open it:

irm https://raw.githubusercontent.com/ersinkoc/phonebox/main/setup.ps1 -OutFile "$env:TEMP\phonebox-setup.ps1"
notepad "$env:TEMP\phonebox-setup.ps1"

Look for what it downloads, from which host, and what it changes. According to the README, the script downloads the latest release, verifies its SHA-256 checksum, offers to install missing dependencies and start-at-login, and opens the settings page. When you are satisfied:

powershell -ExecutionPolicy Bypass -File "$env:TEMP\phonebox-setup.ps1"

That last command bypasses the execution policy for this one file only, so run it only after you have read the script. The README also documents a Scoop route on Windows:

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

Linux and macOS, documented install command (as your own user):

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

Read it first the same way:

curl -fsSL https://raw.githubusercontent.com/ersinkoc/phonebox/main/setup.sh -o /tmp/phonebox-setup.sh
less /tmp/phonebox-setup.sh
bash /tmp/phonebox-setup.sh

The README also lists manual download from the releases page, building from source, and winget manifests in packaging/winget as alternatives.

Expect a warning on Windows

The README warns that Windows release agents are currently unsigned, so SmartScreen or antivirus software may block them. A warning does not prove something is malicious, and it does not prove the file is safe either. Before you click through, make sure the file came from the official ersinkoc/phonebox releases page and that its checksum matches (next step).

Step 2: Verify a manual download with a checksum

If you download the agent or the APK by hand rather than through the script, compare its SHA-256 hash with the value the project publishes. On Windows, Get-FileHash uses SHA256 by default (documented on Microsoft Learn):

Get-FileHash C:\Users\user1\Downloads\PhoneBoxAgent.zip | Format-List

The documented output format is three fields, shown here with Microsoft's own example values rather than a PhoneBox hash:

Algorithm : SHA256
Hash      : 3CBCFDDEC145E3382D592266BE193E5BE53443138EE6AB6CA09FF20DF609E268
Path      : /etc/apt/sources.list

The file name above is a placeholder; use the actual file name from the releases page. On Linux and macOS use sha256sum file (Linux) or shasum -a 256 file (macOS) and compare the result with the published checksum. If you cannot find a published hash for the file you downloaded, do not run it.

Step 3: Connect the phone

Option A: USB

  1. On the phone, enable Developer options. Google's Android developer documentation says to find Build number (on a Google Pixel: Settings > About phone > Build number; on Samsung Galaxy S8 and later: Settings > About phone > Software information > Build number) and tap it seven times until you see You are now a developer!. Menu names vary by maker.
  2. Turn on USB debugging. On Android 9 and higher the documented path is Settings > System > Advanced > Developer Options > USB debugging.
  3. Connect the data cable and accept the authorization prompt on the phone.
  4. Let the setup script install the app, or use Settings > General > Install the phone app in the PhoneBox settings page. The panel opens when the phone connects.

Option B: Wi-Fi pairing (no USB debugging)

  1. Install the APK from the latest release on the phone.
  2. Wi-Fi is off by default. Open the settings page (below), go to General > Wi-Fi & Tailscale, and turn on Let the phone connect without the USB cable. Click Save, then Restart to apply.
  3. Choose Pair a phone over Wi-Fi, scan the QR code with the phone and confirm the check code.

With Wi-Fi only, app updates must be installed manually unless you configure USB later. The README also describes an automatic fallback: enable Wi-Fi and connect over USB once.

Open the settings page

On the computer open http://127.0.0.1:8765 (on Windows you can double-click the tray icon). Under Pages, pick a template, drag and resize widgets on the 12 x 6 grid and click Save. A live preview shows unsaved edits with live data.

Step 4: Safety checks after setup

Authorize USB debugging only on trusted computers

The README says USB debugging should be authorized only on trusted computers. Debugging over USB lets an authorized computer talk to the phone through adb, which is why Android asks you to approve each computer. If you move to Wi-Fi pairing, go back to Developer options and switch USB debugging off.

Keep the agent local

The README lists these ports:

PortPurpose
127.0.0.1:8765Local settings server and pairing endpoints
USBReached through adb reverse on a separate loopback port
8766Optional Wi-Fi HTTPS with a pinned certificate and paired key

Port 8765 is bound to the loopback address, which means only your own computer reaches it. Do not forward it on your router, and do not publish 8766 either. For use away from home, the README's settings section pairs Wi-Fi with Tailscale, a VPN, so use that instead of a port-forward.

On Windows you can check what is listening:

Get-NetTCPConnection -State Listen | Where-Object { $_.LocalPort -in 8765, 8766 }

For port 8765 the LocalAddress column should read 127.0.0.1. If you see 0.0.0.0 on 8765, stop the agent and review your settings.

Update the agent and the phone app together

The v0.9.24 release notes (published 20 November) say the USB connection now answers only the PhoneBox app, and that you should update the agent and the phone app together because older apps cannot use USB with this agent. They also say that if an untrusted app was ever on the panel phone, you should re-pair Wi-Fi, create a new webhook key and renew Home Assistant, Discord and other tokens. The release references advisory GHSA-j6qc-pm3p-fhg7. Do not install anything else on the panel phone that you would not trust next to your PC.

Be careful with the AI-coding permission prompts

Allow and Deny buttons on a phone are convenient, and also easy to tap by mistake. The README describes them as opt-in. Enable them only if you read each prompt, and keep the phone locked down with a screen lock. If you do not need the feature, leave it off.

Look after the battery

A phone that stays plugged in for months can have its battery wear and, in old phones, swell. Remove thick cases, keep it out of direct sun and away from heat, and stop using it if the case bulges. Android's developer options include a Stay awake setting that keeps the screen on while charging; it works for a panel, but consider how long the screen has to stay on. For a related example, see turning an old phone into a security camera.

Troubleshooting

SymptomLikely cause and fix
Phone never shows the authorization promptCharge-only cable, or USB debugging off. Try another data cable and re-check USB debugging.
Windows blocks the agentThe README says Windows agents are unsigned. Confirm the source and checksum before choosing to run it.
USB stopped working after an updateUpdate both the agent and the phone app (v0.9.24 notes).
Wi-Fi pairing does not appearWi-Fi is off by default: enable Let the phone connect without the USB cable, Save, then Restart.
Panel does not open on plug-inThe setting Open PhoneBox when the phone is plugged in is on by default in v0.9.24; check it was not turned off.
Scoop install failsAdd the bucket first, then install both main/adb and phonebox/phonebox, as documented.

See also

What we checked

  • Opened the PhoneBox README on github.com on 2026-11-21 and copied the documented install commands, ports, requirements and the Wi-Fi and USB steps as written.
  • Compared the widget count on the repository's About box (124) with the README (126); they differ, so the article does not give a single number.
  • Opened the v0.9.24 release page on 2026-11-21 and quoted its USB-security note and advisory ID; the page showed "Assets 10" but we did not read asset names or checksum files from it.
  • Opened the project's SECURITY.md on 2026-11-21 and quoted its statement that PhoneBox can run shortcuts and control local applications.
  • Checked Google's Android developer documentation on 2026-11-21 for the Build number tap count (seven), the confirmation message and the USB debugging path on Android 9 and higher.
  • Checked Microsoft Learn's Get-FileHash page on 2026-11-21: the default algorithm is SHA256 and the documented output has Algorithm, Hash and Path fields (the hash shown is Microsoft's example, not a PhoneBox value).
  • Not checked: we did not install PhoneBox, run its scripts or pair a phone; the steps follow the project's documentation as of 2026-11-21. The Get-NetTCPConnection check and the read-first download commands are standard PowerShell and shell usage that we did not run against PhoneBox.

Last tested: 2026-11-21

References

Questions people ask

What is PhoneBox?

PhoneBox is an MIT-licensed open-source project that turns an old Android phone into a desk panel for PC stats, AI coding sessions, music and touch controls. It runs on Windows, Linux and macOS and connects over USB or Wi-Fi without root, an account or a cloud service, according to its README.

Does PhoneBox need USB debugging?

Only for the USB connection. The README says Wi-Fi pairing needs neither a cable nor USB debugging. If you use USB, authorize debugging only on computers you trust, and turn it off again if you move to Wi-Fi only.

Is it safe to run the PhoneBox install script?

The README says the script downloads the latest release and verifies its SHA-256 checksum, and it recommends reading the scripts before running them. The Windows agent is unsigned, so SmartScreen or antivirus may warn. Read the script first and download only from the official repository.

Which phones and computers does PhoneBox support?

The phone needs Android 5.0 or newer (Android 6 or later recommended); there is no iOS version. The computer can be Windows 10 or 11 on x64, Linux on x64 or ARM64 with glibc, or a Mac with Apple silicon or an Intel chip.

PhoneBoxAndroidUSB debuggingWindowsPowerShell