# Debug in your IDE

ct gdb-server serves a board over the GDB remote protocol, like a probe's GDB server. Your IDE loads, breaks, steps and reads memory as it would on hardware.

## Set up the IDE once

From your project directory, point ct at the ELF your build produces:

terminal

```
ct ide setup cubeide --elf Debug/app.elf --board nucleo-f767zi
ct ide setup vscode  --elf build/app.elf --board nucleo-f767zi
ct ide setup all     --elf build/app.elf          # both
```

| IDE                    | What ct ide setup writes                                                                                                                                                                     |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| STM32CubeIDE           | CircuitTwin <elf>.launch, a GDB hardware debugging configuration for localhost:3333 that loads, resets, halts and stops at main, plus an external tool configuration that starts the server. |
| VS Code (Cortex-Debug) | Launch and attach entries in .vscode/launch.json with the ELF and the device SVD, and a task in .vscode/tasks.json that starts the server. Existing configurations are kept.                 |

Options: `--port` (default `3333`), `--svd` (default: found in `CT_SVD_DIR` by part number), `--gdb` for VS Code (default: `CT_ARM_GDB`, else the STM32CubeIDE toolchain), and `--session` to debug a hosted session instead.

## Run the GDB server yourself

terminal

```
ct gdb-server --board nucleo-f767zi --elf build/app.elf --catch-faults
# listening on 127.0.0.1:3333; the board console streams to stdout
```

- `--elf`: program this image before the first debugger connects (otherwise use the debugger’s `load`).
- `--scenario`: drive the board’s sensors from a telemetry scenario while you debug.
- `--stop-on TEXT`: stop the firmware when a console line appears; `--catch-faults` stops on HardFault, MemManage, BusFault and UsageFault entry.
- `--once`: exit when the debugger disconnects. `--port 0` picks a free port.

> **Loopback only by default**
>
> The debug port gives full control of the simulated MCU, so the server accepts connections from this machine only. `--allow-remote` opens it to other hosts; use it only on a network you trust.

## Debug a session on the hosted service

A board running on the hosted service can be debugged from your local IDE. In the app, open a system from a project, choose **Debug** and then **Start a debug session** (or use `ct cloud session`). The Debug panel writes the STM32CubeIDE or VS Code files for you. Or bridge the session to a local port yourself:

terminal

```
ct gdb-bridge --session <SESSION_ID>
ct ide setup vscode --elf build/app.elf --session <SESSION_ID>
```

The bridge uses your `ct login` sign-in (or `CT_SERVER` and `CT_TOKEN`); the token needs the `gdb` scope. See [Access tokens](https://circuittwin.ai/docs/tokens).