> For the complete documentation index, see [llms.txt](https://docs.tryorchard.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryorchard.dev/guides/debugging.md).

# Debugging: lldb and the kernel

Beyond frida, the SDK exposes the on-device lldb debugger and a bridge to the guest-kernel gdb stub. Both need a rootable image. On Cuttlefish, launch the `cuttlefish-debug` image (a rooted userdebug build) for lldb and userland work; for the kernel gdb stub use `cuttlefish-debug-kernel`. The masked image refuses root.

For the full userland-to-kernel walkthrough (frida, lldb, syscalls, kernel gdb, and the TikTok anti-analysis notes) see [Debugging a device, userland to kernel](https://github.com/TheFlash2k/orchard/tree/main/docs/DEBUGGING.md).

## On-device lldb (`sandbox.debugger`)

`status`, `install` and `start` manage `lldb-server` on the device; `console` opens the interactive lldb stream.

{% tabs %}
{% tab title="Python" %}

```python
sb = orchard.sandbox("my-debug")
sb.debugger.install()                       # push lldb-server (needs root), start it
sb.debugger.start(process="com.example.app")

with sb.debugger.console(process="com.example.app") as c:
    c.send("bt")
    for line in c:
        print(line)
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
const sb = orchard.sandbox("my-debug");
await sb.debugger.install();
await sb.debugger.start("com.example.app");

const c = sb.debugger.console("com.example.app");
await c.send("bt");
for await (const line of c) console.log(line);
```

{% endtab %}
{% endtabs %}

## Guest-kernel gdb

A `cuttlefish-debug-kernel` sandbox launches crosvm with a kernel gdb stub (it halts the guest at boot until gdb attaches). Bridge it to a local TCP port, then attach gdb with the matching kernel `vmlinux`:

{% tabs %}
{% tab title="Python" %}

```python
bridge = orchard.sandbox("my-debug").gdb_bridge().start()
print(bridge.port)        # then: gdb vmlinux -ex "target remote 127.0.0.1:<port>"
# ... debug ...
bridge.close()
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
// The TS SDK exposes the raw channel; bridge it to a local port with the CLI
// (`orchard gdb`) or consume the bytes directly:
const ch = orchard.sandbox("my-debug").gdb();
```

{% endtab %}
{% endtabs %}

A kernel breakpoint freezes the whole VM, any frida session included. Kernel gdb is Cuttlefish-debug only; it needs the `kernel-debug` capability.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.tryorchard.dev/guides/debugging.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.