---
title: "Instantiating topology"
description: "Write an instance file to choose which parts of the platform RemotiveTopology runs, and see how an instance resolves with remotive topology show."
source: https://developer.remotivelabs.com/docs/remotive-topology/concepts/instance
last_updated: 2026-11-20
---

# Instantiating topology

To run a topology you need to create an instance file (`.instance.yaml`) that describes what parts of the [platform](https://developer.remotivelabs.com/docs/remotive-topology/concepts/platform.md) you want to run in your virtual environment. The instance also specifies how each ECU is implemented, how channels connect to hardware, what tests to run, and so on.

Relative paths in instance and platform files are always relative to the file that contains the path, not to the directory where you run commands.

> **Tip**
>
> To understand how a topology is instantiated you can use
>
> ```sh
> remotive topology show instance <filename>
> ```
>
> This shows only the parts of the platform that are instantiated and any defaults that have been applied.

See full [topology schema](https://developer.remotivelabs.com/apis/json/topology) for details. Also make sure to setup your editor to use schema validation, see [installation instructions](https://developer.remotivelabs.com/docs/get-started/install.md).

## Choosing what to run

Given a platform, `mytopology.platform.yaml`:

```yaml
schema: remotive-topology-platform:0.18
channels:
  DriverCan:
    type: can
    database: ../databases/driver_can.dbc

  BodyCan:
    type: can
    database: ../databases/body_can.dbc
```

The channels are defined in the platform file, while the ECUs and how they're connected come from the DBC files, see [Using DBC](https://developer.remotivelabs.com/docs/remotive-topology/concepts/platform.md#using-dbc). This gives the following platform:

```mermaid
---
config:
  class:
    hideEmptyMembersBox: true
---
    classDiagram

    class SCCM {
    }

    class BCM {
    }

    class DriverCan {
        <<CAN bus>>
    }

    class DIM {
    }
    class FLCM {
    }
    class RLCM {
    }
    class GWM {
    }

    class BodyCan {
        <<CAN bus>>
    }

    SCCM -- DriverCan
    BCM -- DriverCan
    BCM -- BodyCan
    DIM -- BodyCan
    FLCM -- BodyCan
    RLCM -- BodyCan
    GWM -- BodyCan
```

In `mytopology.instance.yaml` you specify both what platform to use and which ECUs to instantiate:

```yaml
schema: remotive-topology-instance:0.18

platform:
  includes:
    - ./mytopology.platform.yaml

ecus:
  BCM:
```

By default all channels that are connected to the instantiated ECUs are instantiated. This means the resulting topology is:

```mermaid
---
config:
  class:
    hideEmptyMembersBox: true
---
    classDiagram

    class BCM {
    }

    class DriverCan {
        <<CAN bus>>
    }

    class BodyCan {
        <<CAN bus>>
    }

    BCM -- DriverCan
    BCM -- BodyCan
```

Only the ECUs listed in the instance are instantiated. All the other ECUs in the platform are left out.

### Choosing channels

You can optionally specify a subset of channels for an ECU. For example, this only includes a single channel:

```yaml
schema: remotive-topology-instance:0.18

platform:
  includes:
    - ./mytopology.platform.yaml

ecus:
  BCM:
    channels:
      DriverCan:
```

This results in the following topology:

```mermaid
---
config:
  class:
    hideEmptyMembersBox: true
---
    classDiagram

    class BCM {
    }

    class DriverCan0 {
        <<CAN bus>>
    }

    BCM -- DriverCan
```

This is rarely needed, but can be useful when testing an exceptional scenario, for example how BCM behaves when one of its buses isn't available.

## Next steps

| Goal                                                                              | Read                                             |
| --------------------------------------------------------------------------------- | ------------------------------------------------ |
| Give an ECU behavior, mock it, run a custom container, or mark it as hardware      | [Implementing ECUs](https://developer.remotivelabs.com/docs/remotive-topology/usage/ecus.md)                   |
| Use SocketCAN, connect to CAN hardware, or run CAN on macOS                        | [CAN channels](https://developer.remotivelabs.com/docs/remotive-topology/usage/channels/can.md)                |
| Set a LIN schedule table or connect to LIN hardware                               | [LIN channels](https://developer.remotivelabs.com/docs/remotive-topology/usage/channels/lin.md)                |
| Use VLANs, bridge to a physical network interface, or set IP addresses on Ethernet | [Ethernet channels](https://developer.remotivelabs.com/docs/remotive-topology/usage/channels/ethernet.md)      |
| Passively observe Ethernet traffic in tests                                       | [Test access points (TAP)](https://developer.remotivelabs.com/docs/remotive-topology/usage/test/tap.md)    |
| Run tests or other tools inside the topology                                      | [Test and tool containers](https://developer.remotivelabs.com/docs/remotive-topology/usage/test/test-containers.md)      |
| Set RemotiveBroker version, license, Docker images, or registry                    | [Instance settings](https://developer.remotivelabs.com/docs/remotive-topology/reference/settings.md)               |
| Build and run the topology                                                        | [Running a topology](https://developer.remotivelabs.com/docs/remotive-topology/usage/run.md)              |
| Inspect the topology visually                                                     | [RemotiveStudio](https://developer.remotivelabs.com/docs/remotive-studio/topology.md) |
