phonebox README

项目的 README,来自 github.com/ersinkoc/phonebox。合并为一个 markdown 文件:README.md。

PhoneBox icon

PhoneBox

English · Türkçe · Deutsch · Français · Español · Italiano · Português · Nederlands · Polski · Русский · 中文 (简体)

Turn an old Android phone into a desk panel for your computer.
PC stats, AI coding sessions, music and touch controls over USB or Wi-Fi.
Windows, Linux and macOS. No root, PhoneBox account or cloud service required.

Try the live demo · Download · Quick start

Build status Latest release Windows, Linux, macOS; .NET 10 Android 7+ MIT license

PhoneBox on three phones showing automation, home and planner pages
Example layouts with demo data.

PhoneBox pairs a full-screen Android app with a small desktop agent. Build your panel in a browser-based visual editor: 120 widgets, 30 templates, multiple pages and a live preview. Connect several phones with their own layouts, or switch one phone between paired computers.

What you can do

Use it for What appears on the phone
PC monitoring CPU, GPU, RAM, disks, network and ping; charts, GPU details and process controls
AI coding Claude, Codex and Antigravity quotas, reset times and burn-rate forecasts; local Claude Code and Codex sessions; GitHub reviews and CI status
Touch controls App and URL shortcuts, key combinations and macros; application audio, microphone, media, OBS and system controls through Control Deck
Everyday use Now Playing, internet radio, clocks, weather, calendars, notes, checklists, pomodoro and timers
Automation Webhook values and notifications, Home Assistant controls and rules that react to activity on the computer

Tap an AI session for its model, timing and token details. Opt in to Claude Code permission prompts to answer Allow or Deny from the phone. Optional CodexBar integration adds quota providers and a cost overview.

PhoneBox tour showing notifications, a Claude Code permission prompt and automatic page switching
A tour with demo data: notifications, permission prompts and automatic page switching. Watch the MP4

Quick start

You need an Android 7+ phone and a supported computer. USB uses a data cable and USB debugging; Wi-Fi pairing works without either. Release agents include .NET, so you do not need to install the runtime.

1. Install the desktop agent

Windows 10/11 x64 — paste into a normal PowerShell window:

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

Linux or macOS — run as your own user:

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

Setup downloads the latest release, checks its SHA-256 checksum, offers missing dependencies and start-at-login, and opens the settings at http://127.0.0.1:8765. It can also install the Android app over USB. Run setup again to update or repair the installation while keeping settings and pairings.

Windows signing: release agents are currently unsigned while the SignPath Foundation application is pending. SmartScreen or antivirus software may warn or block them. See the code signing policy and installation warnings. USB debugging should be authorized only on computers you trust.

Read the scripts before running them: Windows · Linux/macOS. The installation guide covers options, dependencies, install paths, troubleshooting and uninstalling.

2. Connect the phone

USB Wi-Fi only
Enable Developer options → USB debugging, connect a data cable and accept the phone's authorization prompt. Let setup install the app, or use Settings → General → Install the phone app. Install the APK from the latest release. Enable Settings → General → Wi-Fi & Tailscale, restart the agent when asked, then choose Pair a phone over Wi-Fi. Scan the pairing QR code and confirm the matching check code.
Wakes and opens the panel on connection; supports app updates over adb. No adb or developer options needed; install app updates manually unless you later configure USB.

For automatic USB/Wi-Fi fallback, enable Wi-Fi and connect the phone over USB once. Connection details and Tailscale setup →

3. Make it yours

Open http://127.0.0.1:8765 (or double-click the Windows tray icon). Under Pages, choose a template, drag and resize widgets, then Save. Use Live preview to see unsaved edits with live data. Swipe, tap the page dots or use the phone's volume keys to move between pages.

Other installation methods
  • Manual download: unzip the agent for your system from the release page and run it. Install the APK on the phone. Checksums and build provenance accompany the release assets.

  • Scoop (Windows):

    scoop bucket add phonebox https://github.com/ersinkoc/phonebox
    scoop install main/adb phonebox/phonebox
    
  • From source: see the installation guide and development guide.

  • winget: manifests are prepared in packaging/winget; see the installation guide for details.

Pages & templates

Start with Home, System, AI quotas, Sessions, Music, Planner, Automation or a Control Deck template, then adapt the 12 × 6 grid to your phone. Portrait and landscape layouts are supported. Smart Stack puts up to 12 widgets in one slot.

Home AI sessions
Clock, weather, media and PC metrics Coding sessions and GitHub activity
System Layout editor
CPU, GPU, memory and network charts Pages and widget settings in the visual editor

Screenshots use demo data. Browse the template gallery and widgets. Change fonts, size, spacing, corners and surfaces globally or for one page or widget with the appearance guide.

Platform support

Windows Linux macOS
Release builds x64 x64 / ARM64, glibc Apple silicon / Intel
CPU, RAM, disks, network, processes ✓ ✓ ✓
GPU data Windows counters; NVIDIA via nvidia-smi; extra sensors via LibreHardwareMonitor NVIDIA / AMD; Intel clock Apple silicon, when exposed by macOS
Media System media sessions playerctl nowplaying-cli; Spotify / Music fallback
Volume Native wpctl / pactl System output; availability varies by device
Agent interface Tray icon + browser settings Browser settings Browser settings

Widgets depend on the host's hardware, installed tools and permissions. Advanced Control Deck features have their own platform requirements. Windows ARM and musl Linux (such as Alpine) do not have release builds. See the full compatibility table.

Documentation

Guide Contents
Installation and connections Setup options, warnings, manual and source installs, USB, Wi-Fi, Tailscale, updates, uninstall and troubleshooting
User guide Template gallery, widgets, AI integrations, editor, Claude Code prompts, webhooks and automation rules
Appearance Fonts, surfaces, presets, inheritance and live preview
Control Deck Audio, media, OBS, shortcuts, tasks, protocols, dependencies and platform limits
Discord widget Creating the Discord application, connecting it, controls and troubleshooting
Development Architecture, local demo, builds, tests, widget sources and isolated agent runs
Contributing Contribution scope, review expectations, privacy and required checks
Changelog Release history and unreleased changes
Release checklist Maintainer build, signing and publication workflow

The UMIDIGI BISON extras contain the reversible, no-root tune-up used on the original development phone.

Security & privacy

The desktop settings server listens on 127.0.0.1:8765; USB reaches it through adb reverse. Optional Wi-Fi uses HTTPS on port 8766 with a pinned certificate and a paired key. Settings and pairing endpoints stay local. The phone requests configured actions by ID; commands and integration credentials stay on the computer.

PhoneBox has no telemetry, analytics or accounts of its own. Optional widgets and integrations contact external services for weather, quotas, GitHub and other data, and the agent checks GitHub for updates. Supported public feeds can fall back through the agent over USB when the phone has no internet. The privacy policy lists outbound connections and how to disable them. Read the security details. To report a vulnerability, follow SECURITY.md.

Development

The agent uses .NET 10; the Android app uses Kotlin and a WebView with plain JavaScript widgets. For Android builds, install JDK 17 and Android SDK Platform 35 (the SDK the app is built with; the app itself runs on Android 7.0, API 24, and later). Preview the panel and editor from source with Python 3, using simulated data:

python tools/demo-server.py

Open http://127.0.0.1:8790/panel/ or http://127.0.0.1:8790/settings/. See development commands for running the agent, building the APK and testing changes. Contributions are welcome; start with CONTRIBUTING.md.

Code signing policy

Free code signing provided by SignPath.io, certificate by SignPath Foundation.

Thanks

People who tested PhoneBox on their own hardware:

Sponsor

Sponsored by WrongStack — open-source AI coding with durable memory and multi-agent workflows. Explore wrongstack.com.

Supported by WrongStack · An open-source AI coding agent that remembers your codebase.
Explore WrongStack → · View on GitHub & give it a star ★

Star History

Star history of ersinkoc/phonebox

License

MIT

phonebox (ersinkoc/phonebox)

正在搜索数据库…

这是什么?PhoneBox 可以把一部旧的安卓手机变成可自定义的桌面面板和触控操作台,用于 Windows、Linux 或 macOS 电脑。
它是怎么构成的?它由两部分组成:手机上的全屏安卓应用,以及电脑上的一个小型桌面代理程序。你可以在基于浏览器的可视化编辑器中设计面板,支持多页面,并带有实时预览。
我该怎么让它跑起来?在电脑上运行 README 中的安装脚本:Windows 10/11 x64 请把那行单行命令粘贴到 PowerShell 中;Linux 或 macOS 请以你自己的用户身份运行该脚本。安装过程会下载最新版本、校验其 SHA-256,并提示安装缺失的依赖项,还可以设置开机自启。然后通过 USB 或 Wi-Fi 连接手机。
我需要先准备什么?一部 Android 7 及以上版本的手机,以及一台受支持的电脑。USB 连接需要数据线并开启 USB 调试;Wi-Fi 配对则两者都不需要。发布版代理程序已内置 .NET,因此无需另外安装运行时。
Windows 安装程序现在就能直接用吗?不能无提示直接用。在 SignPath Foundation 的申请通过之前,发布版代理程序未经签名,SmartScreen 或杀毒软件可能会发出警告或拦截它们。Windows ARM 以及 Alpine 等 musl Linux 目前没有发布版本。
三个系统上的功能都完全一样吗?CPU、内存、磁盘、网络和进程信息在 Windows、Linux 和 macOS 上都可用。GPU 数据、媒体和音量控制则取决于操作系统和硬件,例如在 Windows 上,NVIDIA 的状态信息需要 nvidia-smi。
没有网络也能用吗?手机通过 USB 或 Wi-Fi 连接电脑,所以面板可以在本地运行。当手机本身无法上网时,获取公开数据的小组件可以通过 USB 经由桌面代理程序改走其他途径获取数据。
我的数据会离开本地网络吗?没有遥测、分析功能,也没有 PhoneBox 账户。可选的小组件会访问天气、AI 配额和 GitHub 等外部服务,代理程序也会检查 GitHub 上是否有更新。命令和集成凭据保留在电脑上。
许可条款是什么?采用 MIT 许可证,免费使用,无需账户,也不需要云服务。
面板上能放什么?系统状态、Claude Code 和 Codex 的 AI 编程配额与会话、应用和网址快捷方式、宏、媒体和音量控制、Home Assistant 控制、Webhook、时钟、天气和便签。README 中提到约 120 个小组件和 30 个模板。
我能在手机上回应 Claude Code 的权限请求吗?可以,但前提是你要主动开启。开启后,可以直接在手机上对 Claude Code 的权限请求选择允许或拒绝。
一部手机能同时连接多台电脑吗?可以。你可以连接多部手机,每部手机使用各自的布局;也可以让一部手机在已配对的电脑之间切换。
我能在家庭网络之外使用吗?Tailscale 是 Wi-Fi 连接的可选配置方案,README 中链接了一份单独的配置指南。
作者
ersinkoc
大小
28.2 MB
星标
2.6K
时长
11天
提交 · 90 天