Main Navigation Setup Docs

Appearance

Sidebar Navigation

Overview

Home

Documentation Hubs

Direction

Doc Hubs

Popular Specs

Scope Policy

Get Started

Index

Quickstart

Prerequisites

npm Install

Source Install

First Onboard Output

Env Vars

Command Check

Switch Target (Optional)

Run a Task (CLI)

Run via Gateway

Add More Agents (Optional)

Human-in-the-Loop

Device Targets

Target Types and Status

Select or Switch Target

When to Create Another Agent Instead of Switching

Physical Phone Setup (USB)

1) Enable Developer Options on your Android phone

2) Connect phone to your computer and trust the host

3) Verify adb and set target

4) Start gateway

Physical Phone Setup (Wi-Fi ADB)

Physical Phone Setup (Wi-Fi Pairing via target pair)

1) On phone, open Wireless debugging pairing details

2) Run OpenPocket pairing command

3) Verify and continue

Emulator Path in Multi-Agent Installs

Android TV and Cloud Paths

Multi-Agent Setup

Why Multi-Agent Exists

Usage Boundary

Practical Use Cases

1) Home lab: many Android phones on one computer

2) Run several independent agents at the same time

3) Real-world operations

Why This Matters as Open Source

What Isolation Means

Default Agent vs Managed Agents

Create an Agent

Agent Management Commands

Use --agent on Existing CLI Commands

One Target Per Agent

Model Configuration Behavior

Dashboard Model

Per-agent dashboard

Manager dashboard

Shared Human-Auth Relay Hub

Recommended Operational Pattern

Related Pages

Configuration

File Resolution

Config Scope Levels

Default agent

Managed agents

Manager metadata

Load Order

Create-Agent Cloning Rules

API Keys

Aliyun UI Agent mobile backend

Backward Compatibility Keys

Validation and Clamps

Related Runtime Constraints

Defaults

Deploy Documentation Site

Steps

Preview

Concepts

Index

Project Blueprint

Product Vision

Core Principles

Local Agent Phone Runtime

Human Phone vs Agent Phone

Local Data + Auditability

Dual Control

Human-in-the-Loop

Experience Layers

User Scenarios

Shopping

Entertainment

Social

Non-Goals

Summary

Architecture

End-to-End Topology

Runtime Planes

Multi-Agent Runtime Model

Deployment Targets

Primary Task Loop

Manager Services

Manager dashboard

Shared relay hub

Permission and Human Auth Boundary

Auto Skill Experience Engine

Model Endpoint Compatibility

Why This Shape

Remote Human Authorization

Boundary Policy

Handled locally on Agent Phone (no human auth)

Escalated to human auth

Template-Driven Human Auth Portal

Why This Exists

Architecture

End-to-End Sequence (Managed Agent + Shared Hub)

Request and Token Model

Decision Notification

Agentic Delegation Model

Available Skills

Delegation Artifact Types

Scenario-by-Scenario Behavior

1) User account login (oauth)

2) Permission authorization

3) SMS verification code (sms)

4) Camera photo (camera)

Relay Modes

1) Standalone local relay

2) Standalone local relay + ngrok

3) Managed agent + shared relay hub

Persistence

Prompting and Decision Model

Task Prompt Stack

System prompt

User prompt (per step)

Workspace Context Injection

Prompt Observability

Onboarding Prompting

Progress and Outcome Prompting

Progress narrator

Outcome narrator

Output Contract and Safety

Chat Routing

Sessions and Memory

Workspace Bootstrap

Onboarding Lifecycle Persistence

Session Lifecycle

Daily Memory

Memory Recall Tools

Screenshots

Auto Task Sedimentation

Tools

Index

Skills

Source Order

Discovery

Metadata Parsing

Prompt Injection Model

Auto-Skill Experience Engine

Authoring Template

Scripts

Entry Points

Validation

Deny Patterns

Allowlist Check

Execution Model

Result

Generated Scripts

Reference

Index

Config Defaults

Default Config JSON

Aliyun UI Agent mobile note

Managed Agent Overrides

Normalization

Paths

API Keys

Backward Compatibility Keys

Prompt Templates

Task System Prompt (buildSystemPrompt)

full (default)

minimal

none

Task User Prompt (buildUserPrompt)

Workspace Context Injection

Prompt Observability

Onboarding Prompt Templates (Chat Assistant)

Bootstrap onboarding conductor

Locale onboarding template

Session Reset Prompt Template

Task Narration Prompt Templates

Progress narrator

Outcome narrator

Action and Output Schema

Model Step Output

AgentAction Types

Tool Name Mapping

Normalization Defaults

Execution Semantics

ADB-backed actions

Script executor action

Coding executor actions

Memory executor actions

Human authorization action

Terminal action

Current Screen Snapshot Schema

Session and Memory Formats

Workspace Onboarding State

Session

Daily Memory

Root Memory and Search Scope

Screenshot Format

Script Run Artifact

Auto Artifact Outputs

Human Auth Artifact

CLI and Gateway

CLI Commands

Global Selection Rules

onboard

create agent

agents list|show|delete

target set

target pair

install-cli

dashboard start

dashboard manager

gateway start

human-auth-relay start

Model Profile Management

Channel Commands

Telegram Commands

Chat and Task Routing

Bootstrap and Session Reset Behavior

Prompt Context Diagnostics (/context)

Progress and Outcome Messaging

Human Auth in Gateway

Filesystem Layout

Runtime Tree

Agent Storage Model

Default agent

Managed agents

Manager Persistence Map

manager/registry.json

manager/model-template.json

manager/ports.json

manager/locks/targets/.json

Agent Persistence Map

config.json

state/

workspace/

Default Workspace Bootstrap Tree

Human Auth Storage in Multi-Agent Mode

Android Emulator Persistence (AVD)

Where emulator data is stored

Persistence mechanism

Delete or reset the virtual phone

Repo Layout

Skill Sources

Ops

Index

Runbook

Daily Start

Multi-Agent Operational Pattern

Runtime Prompt Context Check

Remote Auth Validation (PermissionLab)

Monitoring

Safe Stop

Debug Evidence Collection

Data Retention

Model Switch

Script and Coding Safety

Troubleshooting

Unknown agent:

Target '' is already bound to agent ''

Target '' is already in use by agent '' (pid ...)

Gateway is running for agent '' ... Stop it before switching deployment target

adb not found

Android emulator binary not found

No AVD found

Missing API key for model

Task keeps failing with invalid model output

Aliyun UI Agent cannot fetch screenshot URL

Aliyun UI Agent keeps returning wait or unsupported operations

Channel bot does not respond

Manager dashboard does not show an agent

Human-auth link is missing in channel reply

Shared relay hub / ngrok URL does not come up

Managed agent falls back to direct local relay unexpectedly

Human-auth request always times out

Web page camera says permission denied after Allow

Delegated artifact was approved but flow did not resume correctly

Invalid manager registry JSON ... / Invalid manager ports JSON ...

Scripts blocked unexpectedly

Gateway logs are too noisy (or too quiet)

Recommended Multi-Agent Deployment Patterns

First Principle

Pattern 1: Solo Home Lab Starter Setup

Pattern 2: Sandbox + Production Ring

Pattern 3: Role-Based Agents

Pattern 4: Region or Account Isolation

Pattern 5: Mixed Target Ladder

Pattern 6: Shared Human-Auth Control Plane

Pattern 7: Business and Operations Stack

Channel Topology Recommendations

Best: one primary channel per agent

Acceptable: many agents in one group

Model Allocation Recommendations

Hardware and Network Guidance

Real phones

Emulators

Network

Naming Conventions That Scale

Anti-Patterns

1) One agent for many phones

2) One shared group chat with loose access rules

3) Production-only deployment with no sandbox agent

4) Reusing the same target for multiple agents

5) Copying workspaces around casually

What a Good Home Deployment Looks Like

Related Pages

Screen Awake Heartbeat

Why It Exists

Architecture

Interval and Configuration

Timing Characteristics

On this page

Ops Index

Runbook
Troubleshooting
Recommended Multi-Agent Deployment Patterns
Screen Awake Heartbeat

Last updated:

Pager

Previous pageFilesystem Layout

Next pageRunbook

GitHub Repository

MIT License · OpenPocket Contributors

Physical Phone Setup (USB)

Physical Phone Setup (Wi-Fi Pairing via target pair)

Practical Use Cases

Dashboard Model

Config Scope Levels

API Keys

Core Principles

User Scenarios

Manager Services

Boundary Policy

Agentic Delegation Model

Scenario-by-Scenario Behavior

Relay Modes

Task Prompt Stack

Progress and Outcome Prompting

Default Config JSON

Task System Prompt (buildSystemPrompt)

Onboarding Prompt Templates (Chat Assistant)

Task Narration Prompt Templates

Execution Semantics

Agent Storage Model

Manager Persistence Map

Agent Persistence Map

Android Emulator Persistence (AVD)

Channel Topology Recommendations

Hardware and Network Guidance

Anti-Patterns

Ops Index ​

Ops Index