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

# run

> Run compiled firmware on a chip-accurate virtual board with Chiplab. Get console output and pass/fail status without physical hardware.

<Info>
  This page describes what your AI agent can do with Chiplab. You don't need to call anything yourself, just ask your agent to run or test your firmware and it takes care of the rest. This is a reference for the curious, not a set of instructions for you to follow.
</Info>

Chiplab can execute your firmware on a chip-accurate virtual board and return the console output, no physical hardware required. Every supported board runs the same binary, the same peripherals, and the same interrupt timing as its physical counterpart, so what you see in Chiplab reflects what you'd see on real hardware.

## Parameters

<ParamField body="artifact_id" type="string" required>
  The identifier of the firmware binary to simulate. Your agent obtains this automatically before running.
</ParamField>

<ParamField body="board_id" type="string" required>
  The slug identifying the virtual board to emulate. See [Supported Hardware](/hardware/boards) for the full list. Example values include `stm32f4_discovery` and `nrf52840_dk`.
</ParamField>

## Response

<ResponseField name="run_id" type="string">
  A unique identifier for this simulation run.
</ResponseField>

<ResponseField name="stdout" type="string">
  All data written to standard output during the firmware simulation.
</ResponseField>

<ResponseField name="stderr" type="string">
  All data written to standard error during the firmware simulation.
</ResponseField>

## Example calls

Run a firmware binary on a target board:

```json theme={null}
{
  "artifact_id": "a1b2c3d4-...",
  "board_id": "stm32f4_discovery"
}
```

A successful response looks like this:

```json theme={null}
{
  "run_id": "run-xyz",
  "stdout": "Hello from STM32F4!\n",
  "stderr": ""
}
```

## Chip accuracy

Chiplab's virtual boards are not generic CPU emulations. Each board runs your exact firmware binary against a faithful model of the target chip's peripherals, memory map, and interrupt controller, so results are directly comparable to real hardware outcomes.

## Knowledge corpus

Every run deposits observed behavior into Chiplab's knowledge corpus, indexed by chip family, failure pattern, and board configuration. Chiplab never collects your firmware code or binaries as part of this, only the chip-level behavior observed during the run. The corpus is shared, so future calls to ask can draw on patterns observed across the platform, making each simulation more useful over time.