> For the complete documentation index, see [llms.txt](https://docs.hex-rays.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hex-rays.com/add-ons/assist/concepts/emulation.md).

# Emulation

Assist includes an embedded concrete and symbolic emulation engine ([RAX](/add-ons/assist/reference/glossary.md#rax)) that the agent can drive to answer questions static analysis cannot — what a decoder produces, which strings a routine builds on the stack, where a computed jump goes, or how tainted input flows through a function.

## Automatic per-function analysis

Whenever you send a message with the cursor inside a function — or when the agent inspects a function — Assist automatically runs a bounded background analysis pass combining Hex-Rays [microcode](/add-ons/assist/reference/glossary.md#microcode) inspection with concrete micro-emulation across a handful of plausible argument values and call-site inputs.

* **Best-effort budget and isolated guest state.** The pass runs under a shared \~500 ms cooperative budget. Guest execution operates on isolated emulator state and never executes native code on your host CPU or applies its writes to the [IDB](/add-ons/assist/reference/glossary.md#idb) (though IDA/decompiler inspection may update host metadata).
* **Cached per database revision.** Results are cached per function while the database revision remains valid, avoiding repeated work on subsequent turns.
* **Disabling the emulator.** To disable the embedded emulator via `ASSIST_RAX_DISABLE=1`, see [Diagnostics & Data Storage → Environment variables](/add-ons/assist/reference/diagnostics.md#environment-variables).

## Two emulation surfaces: CPU sessions and whole-process sessions

Assist exposes two distinct emulation surfaces (see [Requirements & Support → Emulation support](/add-ons/assist/reference/requirements.md#emulation-support) for the canonical tool list and parameters):

1. **CPU & function micro-emulation** — maps segments from the open IDA database into an isolated address space for **x86-32**, **x86-64**, **ARM64 (AArch64)**, and **ARM32 (AArch32)**. You select the execution mode (`"system"` by default, or `"user"`) when starting a stateless run or creating a session; subsequent session operations (stepping, running until an address, watching memory, saving/restoring/forking/diffing state, and exploring branches) inherit the session's mode.
2. **Whole-process emulation (`emulate_process`)** — loads an executable image and optional dependency libraries into a [user-mode OS personality](/add-ons/assist/reference/glossary.md#user-mode-os-personality) (modelling a bounded subset of OS and runtime services) with stdin/stdout/stderr capture and thread/module inspection:

| Guest format                            | Supported architectures                                             | Notes                                                                       |
| --------------------------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| **Windows PE**                          | `x86`, `x64`, `ARM64`                                               | Windows personality is the default                                          |
| **Linux ELF**                           | `x86-64`, `i386`, `AArch64`, `AArch32 EABI`, `RV64` (RISC-V 64-bit) | Select the Linux personality                                                |
| **Darwin Mach-O**                       | `x86-64`, `AArch64`                                                 | Select the Darwin personality                                               |
| **Host runtime libraries** *(optional)* | Matching host architecture/OS                                       | Optional host runtime loading (requires **Read files outside the project**) |

{% hint style="warning" %}
Assist **refuses** to emulate an unsupported architecture by name rather than guessing. A wrong-ISA run would not fail loudly — it would return registers and memory that look plausible.
{% endhint %}

For the per-architecture capability matrix, see [Requirements & Support → CPU emulation capability matrix](/add-ons/assist/reference/requirements.md#cpu-emulation-capability-matrix).

{% hint style="info" %}
**Using `execution_mode: "user"` on ARM.** CPU emulation defaults to `execution_mode: "system"`, where memory-write recording is enabled only on x86-32 and x86-64. On **AArch64** and **AArch32**, pass `execution_mode: "user"` when starting `extract_strings`, `emulate`, or `emulate_start` to enable memory read/write recording, watchpoints, stack-string extraction, and (on AArch32) single-stepping and instruction budgets.
{% endhint %}

## What emulation can do

On a supported target, the agent can:

* **Run and single-step** a function, basic-block slice, or process image from a chosen entry point.
* **Record memory writes** to reconstruct stack strings and runtime-decoded buffers (`extract_strings` observes only the executed path and inputs; a zero-string result can mean the chosen path or inputs never constructed the string or the run stopped early, not that no stack strings exist).
* **Track** [**taint**](/add-ons/assist/reference/glossary.md#taint-tracking) **and** [**symbolic expressions**](/add-ons/assist/reference/glossary.md#symbolic-execution) to follow how specific inputs propagate through registers and memory.
* **Set watch ranges** to break on or log reads and writes to a memory region.
* **Explore branches** (on x86-64 and AArch64) to discover reachable paths and resolve computed control flow.
* **Save, restore, fork, and diff session state** — capture a checkpoint or snapshot at a decision point, rewind the session to an earlier saved state, fork a sibling session to test a second input, or diff register and memory changes between two saved states.
* **Seed state** — map or write memory, set registers, and (in `system` mode) inject interrupts before or during a run.

## Modelled imports and call stubs

By default on x86-32, x86-64, and AArch64, the CPU emulator intercepts and models common C and runtime library functions — heap allocation, string/memory operations, conversions, formatted output, environment queries, deterministic seeded `rand`, and exit/assertion handlers — directly against a synthetic guest heap constrained by the run's mapped-memory budget.

Any other imported call rolls back the call transaction and halts the run with `unmodeled import: <symbol>` unless you provide a custom **call stub** describing its return value and side effects. User-supplied call stubs always take precedence over built-in models.

See [Requirements & Support → Modelled C and runtime functions](/add-ons/assist/reference/requirements.md#modelled-c-and-runtime-functions) for the complete list of modelled imports.

## Limitations and resource bounds

* **Defensive resource limits.** Concurrent sessions, checkpoints, mapped guest memory, trace records, instruction/turn budgets, and wall-clock timeouts are bounded to keep IDA responsive. Reproducibility depends on identical guest inputs, modelled environment, runtime dependencies, and stopping conditions. See [Requirements & Support → Emulation resource limits](/add-ons/assist/reference/requirements.md#emulation-resource-limits) for current defaults.
* **Taint, symbolic execution, and runtime-call interception.** Intercepting modelled or stubbed runtime calls marks taint results approximate (including on x86), and [symbolic execution](/add-ons/assist/reference/glossary.md#symbolic-execution) cannot currently be combined with modelled or stubbed runtime-call interception.
* **AArch32 system mode.** On **AArch32** in the default `execution_mode: "system"`, execution is timeout-bounded run-to-exit only; use `execution_mode: "user"` on AArch32 for single-stepping and instruction budgets.


---

# 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.hex-rays.com/add-ons/assist/concepts/emulation.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.