> ## Documentation Index
> Fetch the complete documentation index at: https://docs.contraforce.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gamebook Simulation: Run With No Side Effects

> Simulate Gamebooks end to end with no changes to your environment. Use Simulation mode for demos, trials, and training, and to test emails and webhooks.

Gamebook Simulation runs a Gamebook end to end, through planning, policies, approvals, and tracking, but every action only reports what it would have done. No device is isolated, no password is reset, and nothing changes in your environment.

Simulate a single Gamebook with one click from the **Run Gamebook** button, or turn on **Simulation mode** for a whole workspace so every Gamebook in it runs as a simulation. That makes Simulation the safest way to demo ContraForce, trial the platform, and train your team on real incidents.

> [!NOTE]
>
> **Who is this for?** Service providers running demos and trials, security teams onboarding and training analysts, and engineers who want to test their notification, ticketing, or SOAR integrations against Gamebook events without touching production entities.

***

## Why Use Gamebook Simulation?

A real Gamebook acts on real users and devices. That's exactly what you want during an incident, and exactly what you don't want during a demo, a trial, or a training session. Simulation gives you the full experience with zero side effects.

> [card] Safe demos, trials, and training
>
> Show the full response flow, including policies, approvals, and tracking, without isolating a single device or resetting a single password.

> [card] Test integrations end to end
>
> Simulated runs still send emails and webhooks, clearly marked as simulated, so you can validate your SOAR, ticketing, or notification setup safely.

> [card] Never confused with a real response
>
> Simulated runs are labeled **Simulated** everywhere they appear: in the Gamebook, the Gamebooks page, the audit log, emails, and webhooks.

> [card] Doesn't use up your action limits
>
> Simulated runs aren't counted toward your hourly action limits, so you can simulate as often as you need without blocking real responses.

### What Happens in a Simulated Run

| Step | Real run | Simulated run |
| - | - | - |
| Planning and targets | ✓ | ✓ |
| Workspace policies (allow, block, require approval) | ✓ | ✓ |
| Approvals | ✓ | ✓, with approval emails marked **\[Simulated]** |
| Tracking, status, and Gamebook history | ✓ | ✓, with a **Simulated** badge |
| Emails and webhooks | ✓ | ✓, marked as simulated |
| Hourly action limits | Checked and counted | Not checked, not counted |
| Action sent to Microsoft, CrowdStrike, SentinelOne, or other tools | ✓ | Never |
| Comment posted on the incident | ✓ | No |

***

## Simulate a Single Gamebook

You can run any Gamebook as a simulation, whatever the workspace setting. This is the quickest way to walk someone through a response on a real incident without acting on it.

**1. Build the Gamebook**

Open an incident and go to the **Response** panel → **Gamebook** tab. Add the actions you want, as you normally would.

**2. Open the Run menu**

Click the **arrow** next to the **Run Gamebook** button.

**3. Choose Simulate run**

Select **Simulate run**.

![Response panel Gamebook tab with three pending actions and the menu next to Run Gamebook open, showing the Simulate run option](https://mintcdn.com/contraforce/sBOENrkkTo-7fsNr/images/gamebook-simulation/per-gamebook-simulate-cta.png?fit=max\&auto=format\&n=sBOENrkkTo-7fsNr\&q=85\&s=d06739fbe5e376492e673a7e598155ab)

**4. Follow the simulated run**

The Gamebook goes through the same steps as a real run: policies, approvals, and tracking. You should see a blue **Simulated** badge next to the Gamebook's status, and each action reports "Simulated: would run (action) on (target). Nothing was changed."

![Finished Gamebook with three actions marked Finished and a blue Simulated badge next to the Finished status](https://mintcdn.com/contraforce/sBOENrkkTo-7fsNr/images/gamebook-simulation/simulation-output.png?fit=max\&auto=format\&n=sBOENrkkTo-7fsNr\&q=85\&s=26e73cc062916e3b6d10396b34294506)

> [!TIP]
>
> Want to know what a Gamebook would do without running it at all? Use [Gamebook Preview](https://docs.contraforce.com/guides/getting-started/gamebook-preview.md). It shows each action's target, policy verdict, and remaining hourly limit with one click.

***

## Simulation Mode for a Workspace

When **Simulation mode** is on, every new Gamebook in the workspace runs as a simulation: Gamebooks run by analysts, by AI agents, and through the API. Nobody has to remember to choose **Simulate run**.

This makes it ideal for:

* **Demos:** show prospects and customers the full ContraForce response flow, including AI agents building and running Gamebooks, on real incidents.
* **Trials:** let a new customer experience automated response in their own tenant without any action reaching their users or devices.
* **Training:** let new analysts practice building, running, and approving Gamebooks with no risk.

> [!WARNING]
>
> While Simulation mode is on, **Gamebooks don't contain real incidents**. Nothing is isolated, disabled, or blocked, even on a true positive. Use it for trial workspaces, demos, and training, never for a workspace you're actively protecting.

### Turn Simulation Mode On or Off

**Who can change it:** workspace Owners. Other roles can see the setting but can't change it.

**1. Open the workspace**

Go to **Workspaces** and open the workspace.

**2. Open the Gamebooks tab**

Select the **Gamebooks** tab.

**3. Find Simulation mode**

In **Gamebook configuration**, find **Simulation mode**, below **Action limits**.

![Simulation mode setting in Gamebook configuration with its description and a toggle set to Off](https://mintcdn.com/contraforce/sBOENrkkTo-7fsNr/images/gamebook-simulation/workspace-gamebook-simulation-setting.png?fit=max\&auto=format\&n=sBOENrkkTo-7fsNr\&q=85\&s=84290bf903698956dec1badc610dd58f)

**4. Switch it On or Off**

Switch the toggle **On** or **Off**. The change is saved immediately and recorded in the workspace's audit log.

**Default:** Simulation mode is off for every workspace.

### What the Setting Affects

* **New Gamebooks only.** It applies to Gamebooks created after you change it.
* **Queued Gamebooks keep their mode.** A Gamebook waiting for approval keeps the mode it was created with.
* **Retries stay simulated.** Retrying a simulated Gamebook runs another simulation.
* **Simulation always wins.** **Simulate run** can always simulate a single Gamebook, even when Simulation mode is off. Nothing can force a real run while Simulation mode is on.
* **AI agents and the API are included.** Gamebooks that Security Delivery Agents submit, and Gamebooks submitted through the API, also run as simulations. Simulation mode is managed in the portal only.

***

## How Simulated Runs Appear

| Where | What you see |
| - | - |
| Gamebook (incident **Response** panel) | A blue **Simulated** badge next to the status |
| **Gamebooks** page | A **Simulated** tag under the status of the run |
| Each action's result | "Simulated: would run (action) on (target). Nothing was changed." |
| Audit log | "Simulated Gamebook (ID). Nothing was changed." |
| Emails (Gamebook triggered, queued, approval requested) | The subject starts with **\[Simulated]**, and the title starts with "Simulated:" |
| Webhooks (`gamebook.run.v1`, `gamebook.completed.v1`) | `"isSimulation": true` in the payload, and the subject reads "Simulated gamebook: (title)" |
| Incident | No comment is posted on the incident for simulated actions |

***

## Simulation, Policies, and Action Limits

**Policies apply exactly as they do to real runs.** A policy that blocks an action blocks it in a simulation too, and a policy that requires approval sends the simulated Gamebook to your approvers. Approval emails are marked **\[Simulated]**, so approvers know that approving it changes nothing. That makes Simulation a good way to rehearse your approval process as well as your response.

**Action limits don't apply.** Simulated runs aren't checked against your workspace's hourly action limits and aren't counted toward them.

***

## For Integrations and Developers

### Webhook Payloads

Both Gamebook webhook events carry an `isSimulation` field:

```json theme={null}
{
  "type": "gamebook.run.v1",
  "data": {
    "gamebookId": "3c9d1b7e-2f44-4a86-8c11-9e0f7d5a2b31",
    "gamebookTitle": "Compromised account containment",
    "playbooks": ["Disable user", "Revoke sign-in sessions"],
    "isSimulation": true
  }
}
```

* `gamebook.run.v1`: `isSimulation` is `true` when the Gamebook runs as a simulation.
* `gamebook.completed.v1`: `isSimulation` is `true` when the Gamebook ran as a simulation, whatever its outcome says. A simulated Gamebook can report **Succeeded** even though nothing changed.

Real runs always send `"isSimulation": false`.

> [!WARNING]
>
> If your integration acts on Gamebook events, for example by closing a ticket when a Gamebook completes, skip events where `isSimulation` is `true`.

See [Configure Webhooks](https://docs.contraforce.com/guides/technical/configure-webhooks.md) to set up a webhook subscription.

***

## FAQ

> [accordion] Can a simulated Gamebook change anything in my environment?
>
> No. Simulated actions are never sent to the services that carry them out. Each action only reports what it would have done.

> [accordion] Will my team still get emails and webhooks for simulated runs?
>
> Yes, so you can test your notification and integration setup. Every simulated email and webhook is clearly marked as simulated.

> [accordion] Can AI agents run simulations?
>
> Yes. When Simulation mode is on, Gamebooks that AI agents submit also run as simulations.

> [accordion] Can I turn a simulated Gamebook into a real one?
>
> Not directly. Build the Gamebook again and click **Run Gamebook** with Simulation mode off, or run it from its [Preview](https://docs.contraforce.com/guides/getting-started/gamebook-preview.md).

> [accordion] Do simulated runs count toward my hourly action limits?
>
> No. Simulated runs aren't checked against the limits and aren't counted toward them, so they never block a real response.

> [accordion] Can I turn on Simulation mode through the API?
>
> No. Simulation mode is managed in the portal only. Gamebooks submitted through the API run as simulations whenever the workspace's Simulation mode is on.

***

## Related Guides

> [card] [Gamebook Preview](https://docs.contraforce.com/guides/getting-started/gamebook-preview.md)
>
> See what a Gamebook would do before you run it, with nothing run or stored

> [card] [What Are Gamebooks?](https://docs.contraforce.com/guides/getting-started/what-are-gamebooks.md)
>
> Build, run, and approve Gamebooks with the built-in response actions

> [card] [Workspace Policies](https://docs.contraforce.com/guides/getting-started/workspace-policies.md)
>
> Allow, block, or require approval for Gamebook actions, in real and simulated runs

> [card] [Configure Webhooks](https://docs.contraforce.com/guides/technical/configure-webhooks.md)
>
> Send Gamebook events to your SOAR, ticketing, or notification tools

***

> [!NOTE]
>
> Questions about Gamebook Simulation? Contact us at [support@contraforce.com](mailto:support@contraforce.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.