> 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/ida-9.5/add-ons/malware/concepts/isolated-system-emulation.md).

# Isolated System Emulation

When you find a code sequence that you do not understand, you can step through it to learn what it does. But debugging malware is risky, and to do it safely you usually must leave your analysis to set up a VM or a remote debugger.

The isolated system emulator removes this risk. Start an interactive "debug" session with one click on the dedicated toolbar button (the "magic wand"). The code runs in an emulator, so the sample *cannot* escape or damage data, and you cannot run malicious code on your system by accident. The add-on sets up the configuration, dialogs, and auditing for you.

Step, set breakpoints, and stop or restart with IDA's debugger controls. A session is fast to start and restart, so you can run a sequence again until you understand it. When you rename an item during emulation, IDA keeps the new name in the disassembly and pseudocode views, and you can import the results of the emulation into the IDB.

## Backends

The add-on supports two emulator backends. Both run Windows PE files. For other file types, the toolbar button is not available.

### Sogen

[Sogen](/ida-9.5/add-ons/malware/concepts/sogen.md) runs the real Windows system DLLs on an emulated CPU, so the sample behaves as it does on a real system. Sogen runs 64-bit PE files, and 32-bit PE files through WOW64.

### Speakeasy

[Speakeasy](/ida-9.5/add-ons/malware/concepts/speakeasy.md) models the Windows API in Python. It is the default backend. When the sample calls an API that Speakeasy does not model, the call returns 1 and the session continues.

## Configuration

To change the settings, select **Malware Analysis > Isolated system emulator > Configure emulator...**, or use HCLI:

```bash
hcli extension config one-click-debugging set backend sogen
```

Restart IDA after you change a setting.

| Setting          | Default     | Description                                                                                                                                     |
| ---------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `backend`        | `speakeasy` | The emulator to use: `speakeasy` or `sogen`.                                                                                                    |
| `sogen_root`     | empty       | The Sogen emulation root. The directory must contain `filesys/c`. When empty, the add-on uses the root from the `ida-sogen-runtime` dependency. |
| `sogen_analyzer` | empty       | The path to the Sogen analyzer binary. When empty, the add-on uses the analyzer from the `ida-sogen-runtime` dependency.                        |

To start a session, select **Malware Analysis > Isolated system emulator > Start interactive emulation**, or click the toolbar button. To stop a session, select **Debugger > Terminate process**. If the database has no breakpoints, the add-on adds a breakpoint at the entry point.

During a session, the add-on selects IDA's remote GDB debugger on `127.0.0.1` and a random free port. When the session ends, the add-on restores your debugger settings. With Sogen, the add-on copies the sample into the emulation root as `C:\<file name>`. This copy replaces a file with the same name and stays there after the session.

The IDC function `start_emulator()` starts a session with the configured backend. `start_emulator_with_backend("sogen")` or `start_emulator_with_backend("speakeasy")` uses a different backend for one session.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.hex-rays.com/ida-9.5/add-ons/malware/concepts/isolated-system-emulation.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.