Skip to content

Architecture overview

Zoey in a hard hat holding a blueprint

Antimony is made of two applications:

  • The interface (interface/): a React single-page app. It runs in the browser, or packaged with Electron as Antimony Desktop. It has no state of its own; everything comes from the server.
  • The server (server/): a Go application that stores topologies and labs, schedules and deploys labs, streams logs and statistics, and controls who can do what.

The server doesn’t run network nodes itself. It hands every deployment to a deployment provider: containerlab on the local Docker host, or clabernetes on a Kubernetes cluster.

Antimony architectureThe web interface and Antimony Desktop talk to the server's REST API and Socket.IO, SSH clients and Wireshark to its SSH server. The transport layer calls the domain services and the runtime; the runtime also uses the domain services. Below them, the infrastructure layer holds the database repositories, auth, file storage and the deployment provider (containerlab, clabernetes or dummy). These talk to PostgreSQL or SQLite, an OpenID provider, the disk, and containerlab on Docker or clabernetes on Kubernetes.InterfaceWeb interfacebrowserAntimony DesktopElectronSSH client · Wiresharkshells and packet captureAntimony serverserver/TransportREST APItransport/http · ginSocket.IOsocket · live events, terminalsSSH serversshserver · :6969ServicesDomain servicesdomain/*collectionstopologieslabsusersdevicesschemaserver configstatus messagesRuntimeruntime/*schedulerinstancesshellscommandsInfrastructureDatabaseGORM repositoriesAuthlogins, tokens, OIDCStoragetopology and run filesDeployment providercontainerlab, clabernetesor dummyExternalPostgreSQL / SQLitelabs, topologies, usersOpenID providerKeycloak, Entra ID, …Diskstorage/ · run/ containerlabon Dockerclaberneteson Kubernetes
Antimony's layers. The transport layer hands requests to the domain services and the runtime, which use the infrastructure layer below them. Exactly one deployment provider is active, set in the configuration. The dashed lines are optional: SSH access and OpenID Connect.
Channel Used for
REST (/api/...) Reading and changing data: collections, topologies, bind files, labs, devices and the containerlab schema. See the REST API.
Socket.IO (/socket.io) Everything live: lab state changes, deployment and node logs, CPU and memory statistics, terminal input and output, and commands such as deploy or restart node. See Socket.IO API.
SSH (port 6969) Not used by the interface itself. People connect with their own SSH client or Wireshark for shells and packet capture.

In a deployment, a reverse proxy puts the interface and the server on the same origin: / goes to the interface, /api and /socket.io go to the server.

The topology editor draws its graph in four stacked layers that share one pan and zoom. Cytoscape draws the nodes and links on a canvas. Groups, shapes and lines are HTML and SVG elements below that canvas; texts and everything that belongs to the selection, such as outlines, guides and handles, are above it. The editor keeps track of the selection itself, Cytoscape doesn’t select anything.

Layers of the topology editorFour stacked layers share one pan and zoom. From the bottom: the graph container with the dot grid, the underlay with groups, shapes and lines, the Cytoscape canvas with nodes and links, and the overlay with texts, the selection and its handles.Graph containerdot grid in the backgroundTopologyGraphUnderlaygroups, shapes and linesAnnotationLayer, EdgeHaloCytoscape canvasnodes and linksCytoscapeOverlaytexts, selection and handlesTextLayer, SelectionLayer, LineHandles, MoveableHandles
Hover the diagram to hold the layers apart, and a layer to see which components draw it.

The server is organised by domain. Each domain object has its own package with an entity, a repository for the database and a service with the business logic. The packages under src/ are:

Package Responsibility
transport/http REST handlers (gin), request validation, the authentication middleware.
socket Socket.IO namespaces with authentication and backlogs, so late subscribers still see recent output.
sshserver The SSH server for node shells and packet capture.
domain/* Collections, topologies, labs, users, devices, the containerlab schema, server config and status messages.
runtime/scheduler Deploys labs at their start time and destroys them at their end time.
runtime/instance Running labs: deployment, node state, readiness checks, logs and statistics.
runtime/shell Browser terminals, including per-user limits and idle timeouts.
runtime/commands Handles commands from the interface, such as deploy lab or restart node.
deployment The providers: containerlab, clabernetes and dummy.
storage Topology files and bind files on disk, and the run directories of labs.
auth Login tokens, the admin login, OpenID Connect and Antimony Desktop’s login.
policy The topology policy, which finds unsafe features in topologies.
config Loading the configuration.

Services publish lab events (lab.created, lab.moved, lab.deleted, lab.manually-deployed, lab.restored) on an internal event bus. The scheduler listens to them to keep its queues up to date.

Domain modelA collection contains topologies. A topology has bind files and is deployed as labs. A lab has at most one instance while it is deployed, and an instance has nodes. Users create collections, topologies and labs. Instances and nodes are kept in memory only.CollectionnamepublicDeploypublicWriteTopologytopology.clab.yamlsyncUrllastDeployFailedLabnamestartTime, endTimeinstanceNameBind filerelative path, contentInstancestatedeployed, recoveredin memoryNodestate, IPscontainerIdin memoryUsersub, namegroupsfrom logincontainsdeployshas0 or 1while deployed1..ngroup names = collection names
Antimony's domain. Collections, topologies, bind files, labs and users are stored; instances and nodes (dashed) only exist while the server runs and are rebuilt when it starts.
  • A collection groups topologies. Access to a collection comes from the user’s OpenID groups. See permissions.
  • A topology is a containerlab topology definition plus its bind files, such as startup configurations.
  • A lab is a deployment of a topology with a start and end time. Several labs can be created from the same topology. A lab belongs to the collection its topology was in when the lab was created.
  • While a lab is deployed, it has an instance with a state and a list of nodes. Instances aren’t stored in the database. When the server starts, it asks the provider which labs are still running and rebuilds their instances (see lab lifecycle).
storage/
<topology id>/
topology.clab.yaml the topology definition
topology.clab.yaml.annotations.json
the graph layout
configs/r1.conf bind files, by relative path
run/
<lab id>/
topology.clab.yaml copy, renamed to the instance name
configs/r1.conf copies of the bind files
clab-<instance name>/ created by containerlab

When you create a lab, Antimony copies the topology’s directory into a new run directory and sets the topology name to the lab’s instance name. containerlab requires unique lab names, so every lab gets one of its own: the topology name in lowercase, with every character other than letters, digits and - replaced by - and cut to 46 characters, followed by - and 12 random hex characters, for example ospf-multiarea-3f9c2a1b7d4e. That keeps the name valid for containerlab and, as c9s-<instance name>, as a Kubernetes namespace.

Because each lab has its own copy, editing a topology never changes labs that already exist.

Bind file paths must be relative and stay inside the topology directory. Absolute paths and .. are rejected, and so are reserved names that Antimony, containerlab or netlab use in the directory, such as clab-*.

The server stores its data in PostgreSQL, or in a SQLite file when started with -sqlite, through the GORM library. Topology definitions and bind files are stored as files in the storage directory, not in the database.