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

# Core concepts

> How Chiplab fits together: you compile the firmware, your agent runs it on a virtual board, and you read what the chip did.

You compile the firmware. Chiplab runs that ELF on a virtual board and reports what the chip did. You do not drive the simulator. Your coding agent does.

The board is not a generic CPU. It runs your exact binary against a model of the target's peripherals, memory map, and interrupt controller, so the firmware behaves the way it would on the real chip. There is no hardware on the desk. The simulator today is [Renode](https://renode.io). [QEMU](https://www.qemu.org) is planned.

A session is a few objects the agent passes along. A project holds the work. An artifact is the ELF in that project. A run executes one artifact on a board. A test checks that same firmware and returns a pass or fail.

## The board

A board is a board model plus the UARTs to capture. Only the UARTs you name are written into the output. Name the UART the firmware writes, or the capture comes back empty.

Models and UART names are on [Boards](/hardware/boards). Framework coverage is on [Frameworks](/hardware/frameworks).

> [!NOTE]
>
> Peripheral coverage keeps growing. If your firmware depends on a peripheral or timing behavior Chiplab doesn't model yet, ask Chiplab for the current coverage of your board.

## The pieces

A project is where uploads and runs live. The next session can pick up the same work, and everyone with access to the project can see it. The calls that create, rename, and delete a project are on [run](/tools/run).

An artifact is the compiled ELF your agent uploads into that project. Cross-compilation happens on your side. Chiplab runs the ELF as-is.

A run is one execution of one artifact on one board. The captured output is `uart`. The full call is on [run](/tools/run).

A test is a TypeScript suite that drives the same firmware on a virtual board. You get a pass or fail for each test. The full call is on [test](/tools/test).

## What comes back

A run lasts up to 5 seconds of virtual time.

`succeeded` means Chiplab completed the run. It does not mean your firmware behaved: a firmware that panics or faults still returns `succeeded`. Check the `uart` output for what you expect.

Use a run when you want the printed output. Use a test when you need a pass or fail. For a test, `succeeded` means the suite ran, not that every test passed. Check `result.summary`.

## What Chiplab keeps

Every run deposits observed behavior into the [knowledge corpus](/introduction#knowledge-corpus), indexed by chip family, failure pattern, and board configuration. Your firmware code and binaries are not part of it.

[ask](/tools/ask) reads that corpus. Your agent uses it for board facts, gotchas, and how Chiplab itself works.

## How a session moves

You describe the work in plain language. The agent picks the tool, waits, and reports what the virtual chip did.

1. [ask](/tools/ask), at the start of a session and whenever something is board-specific. For example, "Which UART does stm32f4\_discovery write to?" or "Why is my captured output empty?"
2. [run](/tools/run) uploads the ELF, executes it, and returns the UART you asked to capture.
3. [test](/tools/test), when you need a pass or fail for each test.
4. A pipeline repeats that loop. It authenticates with a [personal access token](/platform/api-keys), then asks, produces an ELF, uploads and runs it, and fails unless the captured UART matches what you expect. Setup is on [Test in CI](/use-cases/ci-on-every-pr).

> **[Quickstart](/quickstart)**
>
> Run your first simulation in under five minutes.

> **[ask](/tools/ask)**
>
> Look up boards, tools, and firmware patterns.

> **[run](/tools/run)**
>
> Execute an ELF on a virtual board and read the UART.

> **[test](/tools/test)**
>
> Get a pass or fail for each test.

> **[Test in CI](/use-cases/ci-on-every-pr)**
>
> Repeat the loop from a pipeline with a token.

> **[Boards](/hardware/boards)**
>
> STM32 and Nordic boards, and the UART each model can capture.


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