---
title: "pbl debugserver"
canonical_url: https://developer.repebble.com/pebbleos/docs/pbl/debugserver/
last_updated: 2026-10-29
sdk_version: 4.33.1
---
# pbl debugserver

Source: https://developer.repebble.com/pebbleos/docs/pbl/debugserver/

Start a GDB server for the firmware.

```
pbl debugserver
```

Runs the GDB server of the board’s [runner](https://developer.repebble.com/pebbleos/docs/pbl.md#pbl-runners) in the foreground, the one [pbl debug](https://developer.repebble.com/pebbleos/docs/pbl/debug.md) starts, until `Ctrl-C`. Anything that speaks the GDB remote protocol attaches to it: GDB, an [IDE](https://developer.repebble.com/pebbleos/docs/development/debugging/vscode.md), or `pbl debug` from another terminal, which then leaves the server running when GDB quits.

The server listens on the runner’s port, see [pbl debug](https://developer.repebble.com/pebbleos/docs/pbl/debug.md), or on `--gdb-port`:

```
pbl debugserver --tty /dev/cu.usbmodem5B7A1355001 --gdb-port 2331
```

The `native` runner has no GDB server: the simulator runs under the debugger itself.

## Options

```
pbl debugserver [-h] [-b DIR] [--dry-run] [--gdb-port PORT]
                [-r {native,nrfutil,openocd,phone,probe-rs,qemu,sftool,wasm}]
                [--tty TTY] [--probe VID:PID[:SERIAL]] [--keep-flash-image]
                [--decoration NAME] [--bt-hci CHARDEV] [--http-port HTTP_PORT]
                [--no-browser] [--address ADDRESS] [--adb-serial ADB_SERIAL]
```

`--gdb-port PORT`

Port of the gdb server (default: the runner’s)

`-r, --runner {native,nrfutil,openocd,phone,probe-rs,qemu,sftool,wasm}`

Override the board’s runner

`--tty TTY`

Serial port for the sftool and probe-rs runners

`--probe VID:PID[:SERIAL]`

Debug probe for the probe-rs runner

`--keep-flash-image`

Keep the emulator’s SPI flash image, and the apps and data in it, instead of rebuilding it

`--decoration NAME`

SDL decoration the emulator draws around the screen, or ‘none’ (default: the board’s first)

`--bt-hci CHARDEV`

H4 Bluetooth controller for builds with CONFIG\_BT\_HCI\_UART, e.g. the serial port /dev/cu.usbmodem1101

`--http-port HTTP_PORT`

Port the wasm runner serves the page on (default: 8000)

`--no-browser`

Do not open the page the wasm runner serves in a browser

`--address ADDRESS`

Phone address (Developer Connection) for the phone runner; without it, an Android phone is reached over adb

`--adb-serial ADB_SERIAL`

Serial of the Android phone for the phone runner, when adb sees several

Generated from PebbleOS [7e4f46eff](https://github.com/coredevices/pebbleos/commit/7e4f46effe247ce11eeee629a391e1d6a4988ef0). This page is maintained in the pebbleos repository: [docs/pbl/debugserver.md](https://github.com/coredevices/pebbleos/blob/7e4f46effe247ce11eeee629a391e1d6a4988ef0/docs/pbl/debugserver.md).