Simulate a machine

Run viam-server in a simulated environment in the cloud, so you can build and test your machine without its hardware. A simulated machine appears in the Viam app like any other machine: you configure it from the CONFIGURE tab, and you can control it, view its logs, and connect to it with an SDK.

Before you start

  • Simulation is billed by the minute. The machine’s organization is charged for as long as the simulation is running, whoever starts it, including through the AI assistant or MCP. The page where you start a simulation shows the current rate.
  • Idle simulations time out. If the simulated machine isn’t actuating, the simulation times out after at most 60 minutes.
  • You can stop or restart a simulation at any time.
  • Some modules need real hardware. Modules that are drivers for physical hardware, such as specific cameras, motors, or sensors, don’t work in a simulated environment.

Start a simulation

  1. Create a machine in the Viam app. If you haven’t made one before, follow Set up your first machine through step 1.
  2. In the setup wizard, choose to simulate your machine instead of installing Viam on a device.
  3. Read the notes about billing and limits, then click Start simulation.

The wizard shows the simulation’s progress as it starts, which can take several minutes. When it’s ready, the machine comes online and you can configure it like any other machine. See Configure hardware for how to add components. If a simulation fails to start, the wizard shows the error and lets you try again.

If a simulation is already running for the machine, the wizard offers View running simulation instead of starting a second one.

Check, stop, or restart a simulation

While a simulation is running, the machine’s page shows its status and a Stop sim control. After a simulation stops, the page offers Restart sim instead. Stop a simulation when you’re done with it to stop the per-minute charges.

Deleting a machine also ends its simulation.

Manage simulations from the AI assistant or MCP

A simulation runs in place of a machine part, which is normally a computer running viam-server. The Config AI assistant and the Viam MCP server can check on, start, and stop a machine’s simulation:

ToolWhat it does
read_simulationReports whether a simulation is running for a machine part.
start_simulationStarts a simulation. Does nothing if one is already running.
stop_simulationStops a simulation. Returns an error if none is running, or if one is still starting.

The start and stop tools take an optional part name and use the machine’s main part if you omit it. read_simulation reports on every part if you omit the part name. Starting a simulation this way is billed the same as starting one from the setup wizard. The Config AI assistant asks you to approve before it starts a simulation. The MCP server doesn’t ask.

What’s next