Skip to content

Topology editor

The topology editor is where you create and change containerlab topologies. It shows the same topology two ways at once: as YAML and as a graph. A change in one is reflected in the other.

The topology editor: the topology explorer on the left, the YAML editor in the middle and the graph on the right
The editor in split view: explorer, YAML and graph.

Topologies are organised in collections. A collection usually belongs to a class, a course or a team, and it decides who can see and use its topologies (see permissions).

Administrators manage collections:

  • New collection: right-click an empty area of the explorer.
  • Edit / Delete: open the collection’s … menu or right-click it.

Each collection has two switches:

  • Anyone can deploy: everyone with access can start labs from this collection’s topologies.
  • Anyone can edit: everyone with access can add topologies here, and change and delete the ones they created.

Collection names must be unique, at most 64 characters long, start with a letter or digit and contain only letters, digits, spaces, ., _ and -.

As long as there is no topology yet, the editor guides you through creating a collection and a first topology.

The left panel shows collections, their topologies and each topology’s bind files as a tree. Type in Search topologies to filter it.

Item Buttons and menu
Collection + adds a topology. The menu has New topology, and for administrators Edit and Delete. Both are only shown if you may add topologies to the collection.
Topology ▶ opens the deploy dialog for it. The menu has Deploy, and for its creator and administrators New file, Upload files, Edit, Duplicate, Download YAML and Delete.
File or directory The menu has Edit and Delete.

Right-clicking an item opens the same menu.

Drag and drop a topology onto another collection to move it. Drag a bind file onto a topology or a directory to move it there.

Choose New topology on a collection. Give it a Name and optionally a Sync URL (see Git sync). The new topology starts empty:

name: my-topology
topology:
nodes: {}

You can edit a topology if you’re an administrator, or if you created it and its collection has Anyone can edit turned on. Other topologies open read-only.

The toolbar shows the topology’s collection and name. An asterisk marks unsaved changes.

Control What it does
Undo / Redo Step through your changes. Also Ctrl+Z, and Ctrl+Y or Ctrl+Shift+Z.
Code / Split / Graph Show the YAML, both, or only the graph. Your choice is remembered.
Sync options Set the URL to sync the topology from.
Save Save the topology. Also Ctrl+S. Disabled while the topology is invalid. A red dot means there are unsaved changes.
Download Download the open file: the YAML as <collection>_<topology>.yaml, or the annotations as <collection>_<topology>.annotations.json.
Deploy Open the deploy dialog for this topology. Only shown if you may deploy from its collection.

If you try to leave with unsaved changes, Antimony asks whether to Discard changes or Keep editing.

Tour (the question mark in the top bar) takes you through the editor. It starts by itself the first time you open a topology.

The YAML editor validates the topology against the containerlab JSON schema while you type, with completion and hover help for every field. The status bar at the bottom shows Valid, Pending or Error; hover over it to see the problem. It also shows the cursor position and the number of nodes and links.

Paths under binds: are links. Click one to open that bind file, or to create it if it doesn’t exist yet.

The graph shows nodes with their icons and the links between them, labelled with interface names. Drag nodes to arrange them; their positions are saved in the topology.

The toolbar on the left of the graph:

Button What it does
Select (V) Select, move and resize nodes, groups, shapes and text. Shift-click adds to the selection.
Hand (H) Pan the graph by dragging.
Add node Opens the node dialog to add a node.
Rectangle (R), Ellipse (O), Line (L), Text (T) Draw shapes, lines and text on the canvas. Text is written in Markdown and can contain links and images.
Group (G) Draw a named group box. Nodes and shapes whose center it covers are put in the group.
Group selection (Ctrl+G) Puts the selected elements in a new group.
Fit graph Zooms to show the whole topology.
Clear graph Removes all nodes. Can be undone.

Topologies you can’t edit only show Select, Hand and Fit graph. On macOS, use Cmd wherever these docs say Ctrl.

While you drag, elements snap to the grid and to the edges and centers of other elements. Hold Alt to turn snapping off. Dropping elements onto a group adds them to it, and the group grows to fit them. Hold Ctrl while dropping to keep them out of groups, or to move them out of their group.

Hovering over a group, shape or text shows arrows on its sides. Drag from an arrow to draw a line that is attached to it. The ends of attached lines follow the element when it moves or is resized.

Click an element to select it. The bar above the selection has its style options and Delete. Double-click a node’s icon to open the node dialog, or its name to rename it. Double-click a link to rename the interface at the nearer end, and a group’s name to rename the group. Right-click nodes, links, groups, shapes and the background for more options.

To connect two nodes, right-click the first one, choose Connect and click the second one. Clicking the first node again connects it to itself. Antimony uses the next free interface on both ends. Press Esc or click anywhere else to cancel.

Shortcut What it does
Ctrl+C, Ctrl+X, Ctrl+V Copy, cut and paste the selection
Ctrl+D Duplicate the selection
Ctrl+A Select everything
Delete or Backspace Delete the selection
Arrow keys Move the selection, by a grid step with Shift
Ctrl+Shift+G Ungroup
Ctrl+] / Ctrl+[ Bring forward / backward, to the front or back with Shift. Ctrl+↑ and Ctrl+↓ do the same.
F2 Rename the selected node or group
Enter Edit the selected text
Space (hold) Pan with the hand tool
Esc Clear the selection

The node dialog edits everything about a node:

  • the icon (click it to choose one), Name and Kind
  • Node properties: every containerlab node property, with search and validation from the schema
  • Connections: the node’s links and the interfaces they use
  • environment variables, certificates, health checks, DNS settings, labels and more

The topology file only describes the lab. Everything about how it looks in the graph lives in a separate annotations file next to it, <topology>.clab.yml.annotations.json. It uses containerlab’s annotations format, the same one the containerlab VS Code extension and TopoViewer read, so the layout carries over to those tools and the topology stays a plain containerlab file. The server validates the annotations against containerlab’s annotations schema when you save.

Use the Topology / Annotations file switch in the editor to view and edit the annotations as JSON. Antimony writes them whenever you change the layout, such as moving nodes, changing groups or drawing shapes and text.

Section Contents
nodeAnnotations One entry per node, matched by id (the node name): its position, icon and the groupId of the group it is in. Nodes placed on a map use geoCoordinates instead of position.
groupStyleAnnotations The group boxes: id, name, level, the position of the top left corner, width, height and optional styling such as colors and borders. A group with a parentId is drawn inside another group.
freeTextAnnotations, freeShapeAnnotations Text, rectangles, circles and lines drawn on the canvas.
edgeAnnotations, viewerSettings, … Other settings from the format. Antimony keeps them when it saves, even those it doesn’t use.
lab.clab.yml.annotations.json
{
"nodeAnnotations": [
{
"id": "leaf1",
"position": { "x": 320.5, "y": 180 },
"icon": "switch",
"groupId": "fabric"
}
],
"groupStyleAnnotations": [
{
"id": "fabric",
"name": "fabric",
"level": "1",
"position": { "x": 240, "y": 110 },
"width": 320,
"height": 160
}
]
}

Available icons: router, switch, spine, dcgw, server, client, controller, pon and rgw. pe is an alias for router and leaf for switch. Nodes without an icon, or with an unknown one, are shown as client.

Nodes without a position, e.g. in a topology that was pasted, synced or only edited as text, are placed automatically. If no node has a position, the whole graph is laid out by its links. Otherwise, the other nodes keep their positions and the new ones are placed next to the nodes they are linked to. The same topology is always placed the same way, and the positions are only saved once you change the layout.

Antimony used to store the layout in containerlab labels on each node: graph-posX, graph-posY, graph-icon, graph-group, graph-level, graph-geoCoordinateLat and graph-geoCoordinateLng. These labels are deprecated in all containerlab tools. Antimony still reads them for nodes without an annotation, so older topologies keep their layout, but never writes them. As soon as you change the layout, the labels are removed from the topology and converted into annotations, with a group box created around the nodes of each former group.

Bind files are files that containerlab mounts into nodes, such as startup configurations. They belong to a topology and appear under it in the explorer.

  • New file: create a file by its path, for example configs/r1.conf. Directories are created as needed.
  • Upload files: upload an archive (.zip, .tar, .tar.gz, .tgz, .7z, .rar, .bz2). Antimony unpacks it in your browser and lets you pick which files to add. Existing files with the same path are marked and overwritten. A top-level folder named like the topology is removed.
  • Click a file to edit it in the code editor, and use Download in the toolbar to download it.
  • Edit renames or moves a file or directory. Deleting a file asks you to type its path to confirm.

Reference bind files in the topology with paths relative to the topology:

topology:
nodes:
r1:
kind: linux
binds:
- configs/r1.conf:/etc/frr/frr.conf

Bind file paths must stay inside the topology. Absolute paths and .. are rejected. The topology policy also reports any file the topology refers to that isn’t one of its bind files.

Some names are reserved because Antimony, containerlab or netlab create files with them in the topology’s directory. A bind file can’t be created if the first part of its path matches one of them, ignoring case. Otherwise it could overwrite the topology or the lab’s certificate authority at deploy time.

Reserved names Used for
topology.clab.yaml, topology.yml and their .annotations.json files The topology and its graph layout
clab-* containerlab’s lab directory, with the lab’s state and certificate authority
clab_templates, topology.clab_vars.* containerlab templating
netlab.snapshot.pickle, netlab.snapshot.yml, netlab.lock, hosts.yml, ansible.cfg, group_vars, host_vars, node_files, clab_files, config Files netlab generates

A topology can be kept in sync with a file on the web, for example a raw file in a Git repository.

  1. Open Sync options in the toolbar, enter the Sync URL and click Save.
  2. Click Fetch to load the file into the editor.
  3. Review the changes and Save the topology.