---
title: "Install RemotiveTopology"
description: "Install RemotiveTopology with Docker, Python 3.10+, RemotiveCLI and a subscription or free 30-day trial, and set up WSL2, RemotiveBus, Podman and VS Code."
source: https://developer.remotivelabs.com/docs/get-started/install
last_updated: 2026-11-20
---

# Install RemotiveTopology

## Prerequisites

RemotiveTopology runs the topology with the help of docker containers that interact with each other. Thus, you need [Docker engine](http://www.docker.com). Make sure to follow the [post install steps](https://docs.docker.com/engine/install/linux-postinstall/) to be able to run docker without `sudo`. Notice that **Docker Engine** is free and open source, only **Docker _Desktop_** requires license and this isn't needed for RemotiveTopology. However, RemotiveTopology also supports [Podman](https://podman.io/) as an alternative, simply replace `docker` with `podman` in all instructions.

To develop behavioral models for RemotiveTopology, you need **Python 3.10** or later.

On Windows you need to use WSL2, follow the instructions [below](#wsl2-in-windows) to get started.

## RemotiveTopology setup

To use RemotiveTopology, your organization must have an active subscription. If your organization is already a customer of RemotiveLabs, a subscription is likely already in place. Access to the service requires logging in with your organizational credentials to verify the subscription.

**Free 30 day trial:** For new users who wish to evaluate RemotiveTopology, it’s possible to create a trial subscription. This trial provides temporary access to explore the features and capabilities of the service. Once the trial period expires, you need to contact RemotiveLabs to purchase a full subscription and continue using RemotiveTopology. Read more about [RemotiveTopology free trial](https://www.remotivelabs.com/blog/democratizing-automotive-software).

First install [RemotiveCLI](https://developer.remotivelabs.com/docs/remotive-cli/installation.md). Then:

Run `remotive setup`. It signs you in to RemotiveCloud, chooses a default
organization and gets RemotiveTopology ready to use, for example by starting a
trial if your organization has no subscription and downloading
RemotiveTopology. It checks what's already in place and asks before it changes
anything, so it's safe to run again.

Signing in uses a web browser. If there's no browser on the machine, such as a
virtual machine or a docker container, use `--no-browser`. You still need a
browser, just not on that machine.

**Desktop (normal):**

Signing in opens a web browser on this machine.

```bash
remotive setup
```

Follow the sign-in in the browser until it says that you have signed in. Setup
then continues in the terminal.

**Headless (virtual machine, etc):**

With **--no-browser** you get a link to the sign-in page to open in a browser on
another machine.

```bash
remotive setup --no-browser
```

Follow the sign-in until the browser shows a verification code, then paste it
into the terminal.

To keep your current account, default organization and container engine without
being asked about them, run `remotive setup --only-missing`.

If your subscription has expired, or for pricing information and to discuss your specific requirements, reach out to [RemotiveLabs sales](https://remotivelabs.com/contact/).

## Verify installation

To verify that RemotiveTopology is correctly installed:

```sh
remotive topology version
```

This displays the current version of RemotiveTopology and the default versions that are used in runtime environments.

If `remotive setup` hasn't downloaded RemotiveTopology already, the first run downloads it, which takes a while. Later runs are much faster.

### WSL2 in Windows

At the moment prebuilt kernels for WSL doesn't include support for VCAN/VXCAN and SocketCAN drivers. Before following the Linux instructions you need to do some WSL2 specific setup, pick one of the 3 options.
1. Use RemotiveLabs public prebuilt kernel located [here](https://releases.remotivelabs.com/#wsl2-kernels/). This kernel also contains all kernel drivers available upstream located in the sub menu. All modules are statically linked. To use the prebuilt kernel do
```
wsl --shutdown
edit C:\Users\YOURWINDOWSLOGINNAME\.wslconfig
```
Modify the path to the location of your kernel
```
[wsl2]
kernel=C:\\Users\\<yourwindowsloginname>\\vmlinux_static_usb_drivers
```
2. In recent [kernels](https://github.com/microsoft/WSL2-Linux-Kernel/releases) `linux-msft-wsl-6.18.20.1` or newer, only VXCAN is missing, this can be added by running `build-vxcan-module.sh` which can be found [here](https://releases.remotivelabs.com/#wsl2-kernels/).

3. You can rebuild the kernel as shown [here](https://gist.github.com/manavortex/cdaf9540784808e5848cbec744d49a19), make sure to also include `vxcan` and if you intend to attach hardware you need to select the proper driver in `CAN USB interfaces --->`. You are encouraged to select `*` over `M` to create a kernel where the modules are statically linked.

By experience you are advised to uninstall `docker for desktop` and instead use vanilla Ubuntu docker engine install instructions as shown [here](https://docs.docker.com/engine/install/ubuntu/). Make sure to follow the [post install steps](https://docs.docker.com/engine/install/linux-postinstall/) to be able to run docker without `sudo`.

Once you get the kernel running follow all instructions for Linux.

If you need to attach real USB SocketCAN adapter to connect to a real CAN/LIN bus go [here](https://learn.microsoft.com/en-us/windows/wsl/connect-usb), Windows allows WSL2 to get passthrough access to the connected USB device.

### RemotiveBus

Installation instructions and more information can be found in the [RemotiveBus documentation](https://developer.remotivelabs.com/docs/remotive-bus.md).

### Podman

`remotive setup` saves the container engine it sets up as the default for all `remotive topology` commands. To set up Podman, run:

```sh
remotive setup --container-engine podman
```

You can also set the environment variable `REMOTIVE_CONTAINER_ENGINE` to `podman`, which takes precedence over the saved choice:

```sh
export REMOTIVE_CONTAINER_ENGINE=podman
```

To verify that it works simply run:

```sh
remotive topology version
```

## Editor setup

RemotiveTopology uses YAML files to describe instances and platforms. It's strongly recommended that you configure [RemotiveTopology json schema](https://developer.remotivelabs.com/apis/json/topology) in your editor to make it easier to edit these files. There is also a separate [recording json schema](https://files.remotivelabs.com/remotive_topology/recording-0.2.schema.json) which is used when working with [recordings](https://developer.remotivelabs.com/docs/remotive-topology/usage/recordings.md).

### Visual Studio Code

Install [Red Hat YAML plugin](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml)

Add the following to your `settings.json`:

```json
"yaml.schemas": {
    "https://files.remotivelabs.com/remotive_topology/topology-0.18.schema.json":
    ["*.instance.yaml", "*.platform.yaml"],
    "https://files.remotivelabs.com/remotive_topology/recording-0.2.schema.json":
    ["*.recordingsession.yaml", "*.mapping.yaml"]
},
```

## Usage

Run the following to get further instructions:

```
remotive topology --help
```

See [Your first topology](https://developer.remotivelabs.com/docs/get-started/first-topology.md) for next steps.

### Important

It's important that you run all `remotive topology` commands at the root of your project folder. Read more about the RemotiveTopology [workspace](https://developer.remotivelabs.com/docs/remotive-topology/concepts/workspace.md).

## Troubleshooting

If something doesn't work, run:

```bash
remotive doctor
```

It checks your installation, sign-in, container engine and, on Linux, RemotiveBus without changing anything, and says how to fix any problem it finds.

<details>
<summary>Example output on Linux</summary>

```
┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Component        ┃ Check                ┃ Status                   ┃ Version ┃ Details                            ┃
┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ RemotiveBus      │ installation         │ ✓ ok                     │ 0.11.3  │ provides docker/podman CAN, VCAN   │
│                  │                      │                          │         │ and VLAN networks (used by         │
│                  │                      │                          │         │ RemotiveTopology)                  │
│                  │ service              │ ✓ ok                     │ -       │ daemon that creates the container  │
│                  │                      │                          │         │ CAN/VCAN/VLAN networks             │
│                  │ kernel module vcan   │ ✓ ok                     │ -       │ loaded - enables virtual CAN buses │
│                  │ kernel module vxcan  │ ✓ ok                     │ -       │ loaded - enables tunneling CAN     │
│                  │                      │                          │         │ interfaces into containers         │
│                  │ kernel module can_gw │ ✓ ok                     │ -       │ loaded - enables routing CAN       │
│                  │                      │                          │         │ frames between interfaces          │
│                  │ docker plugin socket │ - unknown (not required) │ -       │ no permission to check             │
│                  │                      │                          │         │ /run/docker/plugins/remotivebus.s… │
│                  │                      │                          │         │ (run doctor with sudo to verify)   │
│                  │ remotivebus group    │ ✓ ok                     │ -       │ lets rootless podman reach the     │
│                  │                      │                          │         │ RemotiveBus socket                 │
├──────────────────┼──────────────────────┼──────────────────────────┼─────────┼────────────────────────────────────┤
│ Container engine │ docker engine        │ - missing (not required) │ -       │ 'docker' is not in PATH            │
│                  │ podman engine        │ ✓ ok                     │ 5.4.2   │ runs the RemotiveTopology          │
│                  │                      │                          │         │ containers                         │
│                  │ podman compose       │ ✓ ok                     │ 5.4.2   │ runs multi-container topologies    │
├──────────────────┼──────────────────────┼──────────────────────────┼─────────┼────────────────────────────────────┤
│ Authentication   │ credentials          │ ✓ ok                     │ -       │ credentials found for              │
│                  │                      │                          │         │ me@mycompany.com                   │
│                  │ login                │ ✓ ok                     │ -       │ authenticated with the access      │
│                  │                      │                          │         │ token for                          │
│                  │                      │                          │         │ me@mycompany.com                   │
│                  │ organization         │ ✓ ok                     │ -       │ (my-company) My Company            │
├──────────────────┼──────────────────────┼──────────────────────────┼─────────┼────────────────────────────────────┤
│ Wireshark        │ wireshark            │ ✓ ok                     │ -       │ opens and views packet captures on │
│                  │                      │                          │         │ this host                          │
│                  │ dumpcap              │ ✓ ok                     │ -       │ streams remote captures to a       │
│                  │                      │                          │         │ desktop Wireshark                  │
│                  │ wireshark group      │ ✓ ok                     │ -       │ lets your user capture packets     │
│                  │                      │                          │         │ without sudo                       │
└──────────────────┴──────────────────────┴──────────────────────────┴─────────┴────────────────────────────────────┘
```

</details>

If that doesn't solve the problem, contact RemotiveLabs support at [support@remotivelabs.com](mailto:support@remotivelabs.com). Include the output of `remotive doctor`.
