An Intelligent Phone That Never Sleeps.
OpenPocket runs an always-on agent phone locally, with privacy first.
Status snapshot (February 2026):
adb) driven by CLI + Telegram gateway + dashboard.emulator and physical-phone ready today (android-tv and cloud are in progress).openpocket onboard) for consent, model/API key, Telegram, target selection, and human-auth mode.full|minimal|none) and workspace context budgets.BOOTSTRAP.md, PROFILE_ONBOARDING.json) with persisted workspace onboarding state.TASK_PROGRESS_REPORTER.md, TASK_OUTCOME_REPORTER.md) with anti-noise suppression.read, write, edit, apply_patch, exec, process) with workspace/safety constraints.memory_search, memory_get) for recall-oriented interactions./context [list|detail|json]./auth, one-time web link, optional ngrok) with dynamic template pages and agentic delegation artifacts.skills/auto, scripts/auto) with behavior fingerprint dedupe and semantic ui_target traces.Merged PR: #77
Highlights:
emulator, physical-phone, android-tv, cloud)openpocket target pair for Wireless Debugging pairingphone-use-util) for camera/microphone/location/photos/payment signalsuiTemplate / templatePath)Key commits:
032fa03 feat(skills): experience engine (active skill injection, UI semantic traces, replay relevance)c02a870 fix: harden auto-skill prompt and ui_target escapingHighlights:
ui_target) and reusable behavior fingerprintsadb) for all target typesNOTE: If gpt-5.3-codex is unavailable in your account/provider route, use gpt-5.2-codex.
npm install -g openpocket
openpocket onboard
openpocket gateway start
git clone git@github.com:SergioChan/openpocket.git
cd openpocket
npm install
npm run build
./openpocket onboard
./openpocket gateway start
onboard configuresThe onboarding wizard is interactive and persists progress to:
~/.openpocket/state/onboarding.jsonIt walks through:
emulator, physical-phone, android-tv, cloud).openpocket agent --model gpt-5.2-codex "Open Chrome and search weather"
Or send plain text directly to your configured messaging channel (Telegram, Discord, or WhatsApp) after gateway start.
Settings -> About phone -> Build numberBuild number 7 timesSettings -> System -> Developer optionsUSB debuggingAllow USB debugging prompt.adb devices -l
openpocket target set --type physical-phone
openpocket target show
When multiple devices are online, target set shows an arrow-key selector with explicit transport labels (USB ADB / WiFi ADB) so you can choose the exact device.
You can also use aliases: openpocket target set-target ... or openpocket target config ....
openpocket gateway start
Optional Wi-Fi ADB:
adb tcpip 5555
adb connect <phone-ip>:5555
openpocket target set --type physical-phone --adb-endpoint <phone-ip>:5555
Or use the built-in pairing wrapper (no manual adb commands):
openpocket target pair --host <device-ip> --pair-port <pair-port> --code <pairing-code> --type physical-phone
Notes:
android-tv and cloud targets already exist in config/CLI, and full deployment guides are still in progress.For a full persistence map (OpenPocket runtime files + Android AVD/image storage and deletion/reset flow), see:
This section focuses on production-style runtime deployment for:
gateway start| Environment | Recommended | Notes |
|---|---|---|
| macOS (Apple Silicon / Intel) | Yes | Best local developer experience. |
| Windows (native host) | Yes | Use Android Emulator on Windows host (Hyper-V/WHPX). |
Linux Server (x86_64 + KVM) | Yes | Recommended for headless server runtime. |
Docker on ARM host running linux/amd64 emulator | Not recommended | Works unpredictably due nested software emulation. |
Run onboarding once:
openpocket onboard
Or configure manually in ~/.openpocket/config.json:
{
"target": {
"type": "emulator",
"adbEndpoint": "",
"cloudProvider": ""
},
"emulator": {
"avdName": "OpenPocket_AVD",
"androidSdkRoot": "",
"headless": true,
"bootTimeoutSec": 180
},
"telegram": {
"botTokenEnv": "TELEGRAM_BOT_TOKEN",
"allowedChatIds": []
},
"humanAuth": {
"enabled": true,
"useLocalRelay": true,
"localRelayHost": "127.0.0.1",
"localRelayPort": 8787,
"apiKeyEnv": "OPENPOCKET_HUMAN_AUTH_KEY",
"tunnel": {
"provider": "ngrok",
"ngrok": {
"enabled": true,
"authtokenEnv": "NGROK_AUTHTOKEN"
}
}
}
}
Required env vars for gateway + remote approval:
export TELEGRAM_BOT_TOKEN="<your_telegram_bot_token>"
export OPENPOCKET_HUMAN_AUTH_KEY="<your_human_auth_key>"
export NGROK_AUTHTOKEN="<your_ngrok_token>"
adb version
~/Library/Android/sdk/emulator/emulator -list-avds
openpocket emulator start
openpocket emulator status
openpocket gateway start
Windows does not require WSL for OpenPocket runtime. Recommended setup is: Android Emulator + adb on Windows host, OpenPocket CLI also on Windows host.
$env:ANDROID_SDK_ROOT="$env:LOCALAPPDATA\\Android\\Sdk"
adb version
& "$env:ANDROID_SDK_ROOT\\emulator\\emulator.exe" -list-avds
openpocket emulator start
openpocket gateway start
setx TELEGRAM_BOT_TOKEN "<token>"
setx OPENPOCKET_HUMAN_AUTH_KEY "<key>"
setx NGROK_AUTHTOKEN "<ngrok_token>"
WSL can still be used for development tooling, but running Android Emulator inside WSL/Linux guest is not the preferred path.
x86_64 Headless)This is the recommended server deployment target.
uname -m # expect x86_64
ls -l /dev/kvm # must exist
"emulator": {
"headless": true,
"extraArgs": ["-no-window", "-no-audio", "-no-boot-anim", "-no-snapshot"]
}
openpocket emulator start
openpocket gateway start
systemd or tmux, and keep ngrok token configured for remote human-auth links.OpenPocket currently has two E2E paths:
test/integration/docker-agent-e2e.mjs
npm run test:e2e:docker).openpocket test permission-app run --case <scenario> --chat <chat_id>
camera, microphone, location, contacts, sms, calendar, photos, notification, 2fa.scripts/smoke/dual-side-smoke.sh
Run it locally:
bash scripts/smoke/dual-side-smoke.sh
full|minimal|none)request_human_auth only for real-device/sensitive checkpointsread, write, edit, apply_patch, exec, processmemory_search, memory_get/context command reports actual injected prompt context and budgets.Build a robust memory layer for long-horizon tasks:
Establish a production prompt stack tailored to mobile workflows:
Expand from macOS-first to full platform support:
Strengthen system-level authorization architecture:
Evolve from static skills to dynamic capability generation:
Go beyond Telegram and support more communication entry points:
Improve real-world login workflows after app installation:
Additional engineering tracks needed for production readiness:
The project is actively seeking contributors. If you want to help, pick one task area below and open a PR with the task ID in the title (for example: R2-T3).
R1-T1: design memory schema v2 (episodic + semantic + working memory)R1-T2: implement memory retrieval ranking and relevance filtersR1-T3: implement memory compaction/summarization jobsR1-T4: add memory quality tests for multi-step phone tasksR2-T1: draft phone-use prompt templates per task category (shopping/social/entertainment)R2-T2: add prompt fallback strategies for app-state ambiguityR2-T3: build prompt regression suite with golden trajectoriesR2-T4: add failure taxonomy and prompt tuning playbookR3-T1: Linux runtime parity audit (CLI/emulator/gateway)R3-T2: Windows runtime bring-up and compatibility fixesR3-T3: define and implement Web UI dashboard MVPR3-T4: headless server operator workflow (no GUI) documentation + scriptsR4-T1: iOS real-device auth bridge prototypeR4-T2: Android real-device auth bridge hardeningR4-T3: permission isolation policy and enforcement checksR4-T4: secure tunnel and one-time token lifecycle reviewR5-T1: agent-authored skill generation interfaceR5-T2: skill static checks + runtime policy gateR5-T3: skill test harness and reproducibility toolsR5-T4: skill marketplace-style metadata/index formatR6-T1: channel abstraction layer for inbound/outbound controlR6-T2: Discord connectorR6-T3: WhatsApp connectorR6-T4: WeChat/QQ connector research and adapter designR7-T1: one-time account authorization session protocolR7-T2: 2FA/SMS remote approval UX flow and timeout handlingR7-T3: user-facing auth status model and recovery pathsR7-T4: mobile-first approval page UX improvementsR8-T1: integration test matrix for onboarding + gateway + auth relayR8-T2: security review for relay APIs and artifact storageR8-T3: observability dashboard/log schema improvementsR8-T4: release pipeline hardening and rollback-safe packagingOpenPocket is built for both developers and everyday users.
Typical scenarios include:
Telegram / CLI -> Gateway -> Agent Runtime -> Model Client -> adb -> Agent Phone Target
flowchart LR
U["Local User / Telegram"] --> G["OpenPocket Gateway"]
G --> A["Agent Runtime"]
A --> M["Model Client"]
A --> D["ADB Runtime"]
A --> S["Script Executor"]
A --> C["Coding Executor"]
A --> R["Memory Executor"]
D --> E["Agent Phone Target (Local)"]
A --> W["Workspace Store"]
W --> SS["sessions/*.md"]
W --> MM["memory/YYYY-MM-DD.md"]
W --> RR["scripts/runs/*"]
W --> AS["skills/auto/* + scripts/auto/*"]
RP["User Phone (Human Auth Link)"] -.-> G
Primary config file:
~/.openpocket/config.json (or OPENPOCKET_HOME/config.json)Example config template:
Skill compatibility mode:
agent.skillsSpecMode = "legacy" | "mixed" | "strict"mixed (legacy + strict-compatible loading)strict to enforce directory-based SKILL.md validationSkill validation command:
openpocket skills validate --strict
Skill workspace commands:
openpocket skills list # show loaded workspace skills only
openpocket skills load # interactive select bundled skills to copy into workspace
openpocket skills load --all # copy all bundled skills missing from workspace
Coding runtime migration note:
agent.legacyCodingExecutor is now off by default.agent.legacyCodingExecutor=true remains available as a temporary compatibility toggle, but it is deprecated and will be removed.OpenPocket supports multiple AI model providers through OpenAI-compatible APIs:
OpenAI - Direct access to GPT models (gpt-5.2-codex, gpt-5.3-codex)
OpenRouter - Multi-provider routing for Claude models (claude-sonnet-4.6, claude-opus-4.6)
BlockRun - Pay-per-request micropayments with no subscriptions
blockrun/gpt-4o, blockrun/claude-sonnet-4, blockrun/gemini-2.0-flash, blockrun/deepseek-chatAutoGLM - Phone-optimized multilingual model (autoglm-phone)
Common environment variables:
export OPENAI_API_KEY="<your_openai_key>"
export OPENROUTER_API_KEY="<your_openrouter_key>"
export BLOCKRUN_API_KEY="<your_blockrun_key>"
export AUTOGLM_API_KEY="<your_autoglm_key>"
export TELEGRAM_BOT_TOKEN="<your_telegram_bot_token>"
export OPENPOCKET_HUMAN_AUTH_KEY="<your_human_auth_relay_key>"
export NGROK_AUTHTOKEN="<your_ngrok_token>"
export ANDROID_SDK_ROOT="$HOME/Library/Android/sdk"
export OPENPOCKET_HOME="$HOME/.openpocket"
For Codex subscription auth (no OPENAI_API_KEY), OpenPocket can reuse Codex CLI credentials for codex models:
codex CLI$CODEX_HOME/auth.json (or ~/.codex/auth.json)Codex Auth keychain entry firstCommand prefix by install mode:
openpocket ..../openpocket ... (or openpocket ... after install-cli)./openpocket --help
./openpocket install-cli
./openpocket onboard
./openpocket target show
./openpocket target set --type physical-phone
./openpocket target set --type physical-phone --adb-endpoint 192.168.1.25:5555
./openpocket config-show
./openpocket emulator start
./openpocket emulator status
./openpocket agent --model gpt-5.2-codex "Open Chrome and search weather"
./openpocket script run --text "echo hello"
./openpocket telegram setup
./openpocket telegram whoami
./openpocket skills list
./openpocket skills load
./openpocket skills load --all
./openpocket skills validate --strict
./openpocket gateway start
./openpocket dashboard start
./openpocket test permission-app deploy
./openpocket test permission-app task
./openpocket human-auth-relay start
human-auth-relay start is mainly a standalone debug mode. In normal gateway usage, local relay/tunnel startup is handled automatically from config.
gateway start now auto-starts the local Web dashboard (default http://127.0.0.1:51888, configurable in config.dashboard).
Use dashboard start when you want to run only the dashboard process.
Legacy aliases still work (deprecated): openpocket init, openpocket setup.
The legacy native macOS panel has been removed from the repository.
Use openpocket dashboard start (or openpocket gateway start, which auto-starts dashboard).
The local Web dashboard is now the primary control surface.
openpocket gateway start auto-starts dashboard and prints dashboard URL.openpocket dashboard start starts dashboard only (no Telegram gateway).Default dashboard config:
"dashboard": {
"enabled": true,
"host": "127.0.0.1",
"port": 51888,
"autoOpenBrowser": false
}
OpenPocket supports three human-auth configurations:
When the agent emits request_human_auth, Telegram users can:
/auth approve <request-id> [note]/auth reject <request-id> [note]uiTemplate
(optional live remote takeover is still available), then approve/rejectrequest_human_auth now supports an optional uiTemplate payload so each authorization page can be customized per request instead of using one fixed form.
Supported template controls include:
brandColor, backgroundCss, fontFamily)text, textarea, email, password, otp, card-number, expiry, cvc, select, ...)middleHtml, middleCss, middleScript)approveScript)templatePath, JSON in workspace)artifactKind, requireArtifactOnApprove)Portal shell invariants (always present, not generated by template):
Show Full Context)uiTemplate)This enables capability-specific flows such as:
credentials)payment_card)High-level runtime behavior:
request_human_auth with capability and optional uiTemplate
(or templatePath generated via coding tools in the same Agent Loop)uiTemplateImportant: current implementation is delegation-based (explicit artifact handoff after approve), not direct remote hardware passthrough from human phone sensors into Agent Phone OS APIs.
Credential security notes:
state/human-auth-artifacts/)humanAuth.tunnel.provider=none) for zero third-party network hopTo inspect current chat allow policy and discover recent chat IDs for your bot:
openpocket telegram whoami
When a running task enters Android system permission UI
(permissioncontroller / packageinstaller), OpenPocket handles it locally in
the emulator (auto-approve policy) instead of escalating to remote human-auth.
Use the built-in Android test app to verify remote authorization flow end-to-end.
openpocket gateway start
openpocket test permission-app deploy
Optional commands:
openpocket test permission-app launch
openpocket test permission-app reset
openpocket test permission-app uninstall
openpocket test permission-app cases
openpocket test permission-app task
openpocket test permission-app run --case camera --chat <your_chat_id>
openpocket test permission-app task --case camera --send --chat <your_chat_id>
Recommended command:
openpocket test permission-app run --case camera --chat <your_chat_id>
Or use task --send (same execution path, keeps backward compatibility):
openpocket test permission-app task --case camera --send --chat <your_chat_id>
Available scenario IDs: camera, microphone, location, contacts, sms,
calendar, photos, notification, 2fa.
In this mode, OpenPocket will:
When Telegram receives the human-auth message:
OpenPocket can run on Linux/headless servers when Android SDK + emulator dependencies are present. The current auto-installer is macOS-only, but runtime execution is cross-platform.
For repeatable integration tests, use the Docker E2E harness:
npm run test:e2e:docker
What this flow does:
Important notes:
/dev/kvm, emulator boot is much faster.OPENPOCKET_E2E_TASK=\"Open Android Settings and then go home\" npm run test:e2e:docker
The documentation frontend is implemented in this repository:
/frontend/frontend/.vitepress/config.mjs/frontend/index.md/frontend/.vitepress/theme/custom.cssnpm run docs:dev
npm run docs:build
npm run docs:build:vercel
npm run docs:preview
vercel.json/frontend/get-started/deploy-docs.md/src: runtime source code (agent, gateway, device, tools, onboarding, dashboard)/frontend: standalone frontend site (homepage + docs)/test: runtime contract and integration tests/dist: build outputRun checks:
npm run check
npm test
/frontend in the relevant hub.run_script execution is guarded by an allowlist and deny patterns.exec/process coding tools are guarded by allowlist, deny patterns, workspace boundaries, timeout, and output caps.MEMORY.md and memory/*.md.FAQs
OpenPocket Node.js TypeScript runtime
The npm package openpocket receives a total of 8 weekly downloads. As such, openpocket popularity was classified as not popular.
We found that openpocket demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
GitHub Actions checkout now blocks risky pull_request_target checkouts by default to help prevent pwn request supply chain attacks.
Product
Socket now supports Custom Roles and Repository Access Permissions so organizations can control who can access specific repositories and actions.
Product
Socket MCP now lets AI assistants review org alerts, investigate threats using the Socket threat feed, and inspect package files in addition to dependency scoring.