Connect Device

This guide covers the complete device lifecycle in PhoneBase -- from creating a cloud phone to connecting, controlling, and managing multiple devices.

Device Lifecycle Overview

A PhoneBase cloud phone goes through the following stages:

Create → Start → Connect → Operate → Disconnect → Stop / Delete
         ↑                                ↓
         └────── Restart (reboot) ────────┘

Stage	Command	Description
Create	`pb devices create`	Allocate a new cloud phone
Start	`pb devices start`	Boot a stopped device
Connect	`pb connect <code>`	Connect for real-time control
Operate	`pb tap`, `pb text`, ...	Send commands to the device
Disconnect	`pb disconnect`	Disconnect from the device
Stop	`pb devices stop`	Shut down the device (preserves state)
Delete	`pb devices delete`	Permanently remove the device

TIP

You only pay for time the device is running (started). Stopped and disconnected devices do not incur charges, but be aware that a running device continues billing even when not connected.

Create a Device

Allocate a new Android cloud phone:

bash

pb devices create

Human-readable output:

✓ Device created
  device_code  IDY291LX6WW6RCW
  status       starting

JSON output (non-TTY / AI agent):

json

{
  "code": 0,
  "msg": "Device created",
  "data": {
    "device": {
      "id": "dev_01jk...",
      "device_code": "IDY291LX6WW6RCW",
      "status": "starting"
    }
  }
}

The device will be in starting status initially and transition to running within about 15 seconds.

List Devices

View all your devices:

bash

pb devices list

You can also use the shorthand:

bash

pb devices

Both produce the same output:

CODE               STATUS         ONLINE   CONNECTED  STARTED_AT
IDY291LX6WW6RCW   running        yes      yes        2026-04-09T10:30:00Z
K8X3M2P7QRST      stopped        no       -          -

Field Descriptions

Field	Description
`CODE`	The device code used to identify the device in commands
`STATUS`	Device status: `starting`, `running`, `stopped`, `deleting`
`ONLINE`	Whether the device agent is reachable
`CONNECTED`	Whether your CLI is currently connected to this device
`STARTED_AT`	Timestamp when the device was last started

Start / Stop a Device

Start

Boot a stopped device:

bash

pb devices start IDY291LX6WW6RCW

json

{
  "code": 0,
  "msg": "Device IDY291LX6WW6RCW: start",
  "data": { "task_id": "task_abc123" }
}

INFO

The start operation is asynchronous. The device transitions from stopped to starting to running. This typically takes about 15 seconds.

Stop

Shut down a running device:

bash

pb devices stop IDY291LX6WW6RCW

json

{
  "code": 0,
  "msg": "Device IDY291LX6WW6RCW: stop",
  "data": { "task_id": "task_def456" }
}

WARNING

Stopping a device will disconnect any active connections. Make sure to finish your operations before stopping.

If you omit the device ID, the command uses the currently connected device:

bash

pb devices stop

Connect to a Device

Connect to your cloud phone for real-time control:

bash

pb connect IDY291LX6WW6RCW

✓ Connected to device IDY291LX6WW6RCW

How Connection Works

The CLI automatically starts a background process (if not already running)
A persistent connection is established to the PhoneBase cloud
All subsequent pb commands are routed through this connection to the device
The connection persists in the background -- you can close the terminal and reconnect later
If the connection drops, it is automatically re-established

TIP

You do not need to keep the terminal open after connecting. The connection is maintained in the background. Any new pb command in any terminal session will use the existing connection.

Disconnect

Disconnect from the device:

bash

# Disconnect from a specific device
pb disconnect IDY291LX6WW6RCW

# Disconnect from all devices
pb disconnect

✓ Disconnected

INFO

Disconnecting does not stop the device. The device continues running (and billing continues). To stop billing, use pb devices stop.

Device Details

View detailed information about a specific device:

bash

pb devices info IDY291LX6WW6RCW

JSON output:

json

{
  "code": 0,
  "data": {
    "id": "dev_01jk...",
    "device_code": "IDY291LX6WW6RCW",
    "status": "running",
    "plex_status": "running",
    "is_online": true,
    "started_at": "2026-04-09T10:30:00Z",
    "created_at": "2026-04-09T10:29:45Z",
    "instance_id": "inst_xyz789"
  }
}

View Task History

Check the async task history for a device (start, stop, reboot, etc.):

bash

pb devices tasks IDY291LX6WW6RCW

Multi-Device Management

Targeting a Specific Device

When multiple devices are connected, use the -s global flag to specify which device a command targets:

bash

# Take a screenshot on a specific device
pb -s IDY291LX6WW6RCW screencap

# Tap on a specific device
pb -s K8X3M2P7QRST tap 540 960

Setting a Default Device

To avoid typing the device code every time:

bash

pb config set device_default IDY291LX6WW6RCW

Now commands without -s will target this device automatically.

Auto-Resolution

If you omit the device identifier:

The CLI first checks if -s was provided
Then it checks the device_default config setting
Then it uses the currently connected device (if exactly one is connected)
If none of the above resolves, the command exits with an error

Device Control Operations

Reboot

Reboot a running device (soft restart of the Android system):

bash

# Via the devices subcommand
pb devices reboot IDY291LX6WW6RCW

# Or use the shorthand (uses connected/default device)
pb reboot

json

{
  "code": 0,
  "msg": "Device IDY291LX6WW6RCW: reboot",
  "data": { "task_id": "task_ghi789" }
}

Factory Reset

Reset the device to its initial state:

bash

pb devices reset IDY291LX6WW6RCW

DANGER

Factory reset permanently erases all data on the device -- installed apps, app data, files, everything. This operation cannot be undone. Use snapshots to save your state before resetting.

Restore from Snapshot

Restore a device to a previously saved snapshot state:

bash

pb devices restore IDY291LX6WW6RCW --snapshot snap_abc123

json

{
  "code": 0,
  "msg": "Device IDY291LX6WW6RCW restored",
  "data": { "task_id": "task_jkl012" }
}

Managing Snapshots

You can create, list, and delete snapshots:

bash

# Save current device state as a snapshot
pb snapshots create IDY291LX6WW6RCW --name "after-setup"

# List all snapshots
pb snapshots list

# Delete a snapshot
pb snapshots delete snap_abc123

Delete a Device

Permanently remove a device:

bash

pb devices delete IDY291LX6WW6RCW

DANGER

This operation is irreversible. The device and all its data will be permanently deleted. Create a snapshot first if you need to preserve any state.

Device Modes

PhoneBase supports three device modes, each suited for different use cases:

Stateless

Each task starts on a fresh device. After execution completes, the device is destroyed. No state leaks between runs.

TASK → [ FRESH DEVICE ] → RESULT → DESTROY

Best for: One-off tasks, testing, CI/CD pipelines, tasks where you want guaranteed clean state.

Snapshot

Pre-configure a phone -- install apps, log in to accounts, set up preferences -- then take a snapshot. Each session clones from that baseline and is discarded after use.

SNAPSHOT ──→ CLONE → EXECUTE → DISCARD

Best for: Repeated tasks that require a specific setup (e.g., an app pre-installed and logged in), batch processing, parallel execution with identical starting states.

Persistent

A dedicated always-on device. State is fully preserved between sessions. Billed per hour while running.

DEVICE ──→ SESSION₁ → SESSION₂ → SESSION₃ ···

Best for: Long-running agents, tasks that require state accumulation over time, development and debugging.

Live View in Browser

Open the device's live screen stream in your default browser:

bash

pb view IDY291LX6WW6RCW

✓ View opened: IDY291LX6WW6RCW

This opens a browser tab showing the real-time video stream of the device screen. Useful for monitoring what the device is doing.

Troubleshooting

Device Shows "offline"

The device agent may not be reachable. Try:

Check the device status: pb devices info <code>
If the status is running but is_online is false, try rebooting: pb devices reboot <code>
If the device is stopped, start it: pb devices start <code>

Connection Timeout

If pb connect hangs or times out:

Verify the device is running and online: pb devices list
Check your network connection
If using a VPN or proxy, ensure the connection is not blocked
Try disconnecting and reconnecting:
bash
```
pb disconnect
pb connect <code>
```

Connection Lost

If you see "no active connection" errors:

The background process may have stopped. Reconnect:
bash
```
pb connect <code>
```
The background process automatically restarts when you run pb connect

Commands Return "no device specified"

This means the CLI can't determine which device to target:

Connect to a device: pb connect <code>
Or specify the device with -s: pb -s <code> <command>
Or set a default device: pb config set device_default <code>

Connect Device ​

Device Lifecycle Overview ​

Create a Device ​

List Devices ​

Field Descriptions ​

Start / Stop a Device ​

Start ​

Stop ​

Connect to a Device ​

How Connection Works ​

Disconnect ​

Device Details ​

View Task History ​

Multi-Device Management ​

Targeting a Specific Device ​

Setting a Default Device ​

Auto-Resolution ​

Device Control Operations ​

Reboot ​

Factory Reset ​

Restore from Snapshot ​

Delete a Device ​

Device Modes ​

Stateless ​

Snapshot ​

Persistent ​

Live View in Browser ​

Troubleshooting ​

Device Shows "offline" ​

Connection Timeout ​

Connection Lost ​

Commands Return "no device specified" ​

Connect Device

Device Lifecycle Overview

Create a Device

List Devices

Field Descriptions

Start / Stop a Device

Start

Stop

Connect to a Device

How Connection Works

Disconnect

Device Details

View Task History

Multi-Device Management

Targeting a Specific Device

Setting a Default Device

Auto-Resolution

Device Control Operations

Reboot

Factory Reset

Restore from Snapshot

Delete a Device

Device Modes

Stateless

Snapshot

Persistent

Live View in Browser

Troubleshooting

Device Shows "offline"

Connection Timeout

Connection Lost

Commands Return "no device specified"