Skip to content

How it works

Labs always run on Linux, next to Docker. The apps differ only in how they get there.

# Diagram only: how the apps reach a lab host. Not a deployable lab.
name: architecture
 
topology:
  nodes:
    vs-code: {kind: linux}
    desktop-app: {kind: linux}
    browser: {kind: linux}
    web-app: {kind: linux}
    containerlab: {kind: linux}
    clab-api-server: {kind: linux}
    spine: {kind: linux}
    leaf1: {kind: linux}
    leaf2: {kind: linux}
 
  links:
    - endpoints: [spine:e1-1, leaf1:e1-49]
    - endpoints: [spine:e1-2, leaf2:e1-49]
VS Code and the desktop app run containerlab on the machine they run on. Every app can also sign in to clab-api-server on a lab host.

Every app reaches labs in one of two ways, and shows the labs of both side by side:

  • containerlab on the machine the app runs on. No server and no sign-in: the app runs containerlab as you. VS Code calls it Local, the desktop app This computer.
  • clab-api-server on a lab host. You sign in with a Linux account on the lab host, and the API server deploys labs, opens terminals, and captures packets there. One app can sign in to several lab hosts at once.

VS Code runs containerlab on whatever machine the extension runs on. With Remote SSH, that is the remote server, and your laptop only shows the window. Lab hosts show up next to Local.

The desktop app on Linux opens on the labs of this computer, like VS Code. On macOS and Windows, and for labs elsewhere, it signs in to lab hosts.

The web app signs in to lab hosts. On a host you trust, it can also run labs on its own host.

The browser sandbox has no lab host. It is the same editor, saving to your browser.

What works where

containerlab on this machine clab-api-server on a lab host
VS Code Local: Linux, WSL, Remote SSH Lab hosts, from any OS
Desktop app This computer: Linux Lab hosts, from any OS
Web app Its own host, when turned on Lab hosts

Both ways run the same lab actions. A few depend on the API server:

Feature containerlab on this machine clab-api-server
Deploy, destroy, redeploy, apply, start, stop, save
Edit topologies and annotations
Node shell, SSH, telnet, logs
Packet capture, Wireshark in a tab or Edgeshark
Link impairments
Install Edgeshark, manage container images
Draw.io diagrams
Import or deploy a lab from GitHub or GitLab
Host CPU, memory, and disk
Several users on one lab host, each with their own labs
Shared labs in @shared
SSH to a node through a port the lab host forwards
Interactive Draw.io editing (VS Code)
Sign-in none, runs as you Linux account in clab_api or clab_admins

Two files per lab

A lab is a containerlab topology file. The editor adds a second file next to it for everything visual.

lab.clab.yml

Nodes, kinds, images, links, configuration. This is what containerlab deploys. Edit it on the canvas or as text; both stay in sync.

lab.clab.yml.annotations.json

Positions, icons, colors, groups, text, and display settings. Containerlab ignores it.

Your own config files

Startup configs and binds referenced from the YAML. The editor leaves them alone.

Moving a node changes only the annotations. Connecting two interfaces changes the YAML. Both files are plain text, so they work in Git and with the containerlab CLI.

The same topology, without and with its annotations file:

YAML only

name: fabric
 
topology:
  defaults:
    kind: nokia_srlinux
    image: ghcr.io/nokia/srlinux:latest
 
  nodes:
    spine1:
      type: ixrd3
    spine2:
      type: ixrd3
    leaf1:
      type: ixrd2
    leaf2:
      type: ixrd2
    leaf3:
      type: ixrd2
    client1:
      kind: linux
      image: ghcr.io/srl-labs/network-multitool:latest
    client2:
      kind: linux
      image: ghcr.io/srl-labs/network-multitool:latest
    client3:
      kind: linux
      image: ghcr.io/srl-labs/network-multitool:latest
 
  links:
    - endpoints: [spine1:e1-1, leaf1:e1-49]
    - endpoints: [spine1:e1-2, leaf2:e1-49]
    - endpoints: [spine1:e1-3, leaf3:e1-49]
    - endpoints: [spine2:e1-1, leaf1:e1-50]
    - endpoints: [spine2:e1-2, leaf2:e1-50]
    - endpoints: [spine2:e1-3, leaf3:e1-50]
    - endpoints: [leaf1:e1-1, client1:eth1]
    - endpoints: [leaf2:e1-1, client2:eth1]
    - endpoints: [leaf3:e1-1, client3:eth1]

The editor picks a layout.

YAML + annotations

name: fabric
 
topology:
  defaults:
    kind: nokia_srlinux
    image: ghcr.io/nokia/srlinux:latest
 
  nodes:
    spine1:
      type: ixrd3
    spine2:
      type: ixrd3
    leaf1:
      type: ixrd2
    leaf2:
      type: ixrd2
    leaf3:
      type: ixrd2
    client1:
      kind: linux
      image: ghcr.io/srl-labs/network-multitool:latest
    client2:
      kind: linux
      image: ghcr.io/srl-labs/network-multitool:latest
    client3:
      kind: linux
      image: ghcr.io/srl-labs/network-multitool:latest
 
  links:
    - endpoints: [spine1:e1-1, leaf1:e1-49]
    - endpoints: [spine1:e1-2, leaf2:e1-49]
    - endpoints: [spine1:e1-3, leaf3:e1-49]
    - endpoints: [spine2:e1-1, leaf1:e1-50]
    - endpoints: [spine2:e1-2, leaf2:e1-50]
    - endpoints: [spine2:e1-3, leaf3:e1-50]
    - endpoints: [leaf1:e1-1, client1:eth1]
    - endpoints: [leaf2:e1-1, client2:eth1]
    - endpoints: [leaf3:e1-1, client3:eth1]

Your positions and icons.

Editing a running lab

You can keep editing while a lab runs. The play button then shows that the file differs from what is deployed. Apply lists what containerlab would change, and applies it when you confirm. See Run a lab.

Labs open locked by default, so a stray drag changes nothing. Select the lock in the toolbar to start editing. An empty lab opens unlocked.