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

# Running a workflow in simulation

> Set a workflow's execution target to Simulation to run it against a cloud physics simulation instead of real hardware

Every workflow has an execution target:

| Target             | Where twin commands go                         |
| ------------------ | ---------------------------------------------- |
| **Live** (default) | Real hardware, through your edge drivers.      |
| **Simulation**     | A cloud physics simulation of the environment. |

Set it from the workflow's runtime badge in the environment's workflow list.

## Simulation runs are provisioned for you

Triggering a Simulation workflow starts a simulation for its environment if one
is not already running, and waits for the physics to be ready before the first
twin command is sent. An already-running simulation is reused rather than
restarted, so you can watch the run live.

You need write access to the environment to trigger a Simulation workflow.

<Note>
  A Simulation run needs simulation capacity in your workspace. If none is
  available the run fails with the reason instead of hanging.
</Note>

## Edge workflows can run against the simulation

Perception nodes and pose models only run on an edge, so a workflow using them
needed a robot before it could run at all. It no longer does: a simulation can
host the workflow itself, reading the simulated cameras.

This needs **both** settings, and there is no default for the second:

1. Turn on **Run on edge** for the workflow.
2. Set its execution target to **Simulation**.

Then start the environment's simulation. The workflow runs against the
simulated camera and depth streams exactly as it would beside a real camera —
the same graph, unchanged, on either.

<Note>
  Activate the workflow **before** starting the simulation. A simulation that
  started with no Edge + Simulation workflow in its environment is not hosting a
  workflow, and activating one afterwards will not reach it — stop the simulation
  and start it again. Once a simulation is hosting one, activating a further
  workflow takes effect within about 15 seconds, and deactivating one within
  about half a minute.
</Note>

A workflow left on the **Live** target is untouched by this: it stays on your
real hardware and is never duplicated into the simulation.

## Robot arms follow waypoints through IK

A **Move Twin** node pointed at a fixed-base arm treats each waypoint as a
target for the arm's end effector, solving the joint angles that reach it. The
arm's catalog entry must declare an end-effector frame; arms without one, and
other jointed-but-anchored objects such as pan-tilt mounts, keep the base
navigation behaviour.

Waypoints may be placed in the environment or relative to the arm's own base
link — those are the two frames an arm accepts, on either target. Each
waypoint's authored duration becomes the time the arm takes to move to it.

<Note>
  This solving happens in the cloud, for the simulation only. On a **Live** target
  the same node sends the waypoints to the robot and its own driver plans the
  motion — so the arm moves in a straight line and refuses a path it cannot reach
  without a collision.

  A Live arm therefore needs a driver that supports waypoint missions (MoveIt on
  our ROS 2 drivers). If the arm's driver does not, the run fails immediately
  saying so rather than waiting on a robot that will never move — switch the
  target to **Simulation**, or bind a driver that does.

  Today, the Kinova Gen 3 is the only arm whose driver plans waypoint missions.
  Joint-streaming arms, including the SO-101 and UR7, support Move Twin on the
  **Simulation** target only. A catalog that explicitly contains the
  `navigate/command` topic remains valid even if it is maintained manually. Only
  a current catalog that omits the topic refuses Live; a missing or older catalog
  cannot answer the question, so the run proceeds and existing drivers keep
  working.
</Note>

### Take picture on arrival

Works for arms as well as mobile robots. The image is attached to the run and
exposed on the node's output as `attachment_uuid`, `file_url` and `captures`,
ready to wire into a Call Model or Annotate node. If no camera frame is
available the run continues and the node reports `capture_error`.

In a Simulation run **against a robot arm**, the picture is what the twin's
camera sees in the simulation, even when the same twin is also connected to a
real robot. If the simulation is not rendering that camera the node reports
`capture_error` rather than substituting the real camera's view.

<Warning>
  Mobile robots do not yet take an arrival picture in a Simulation run. The
  capture is performed by the robot's own driver, which a simulated run does not
  drive, so the node completes with no image and no `capture_error`. Use a Live
  run when you need the picture.
</Warning>