Architecture overview
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.
How the interface talks to the server
Section titled “How the interface talks to the server”| 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.
Inside the interface
Section titled “Inside the interface”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.
Inside the server
Section titled “Inside the server”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.
The domain
Section titled “The domain”- 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).
Files on disk
Section titled “Files on disk”storage/ <topology id>/ topology.clab.yaml the topology definition topology.clab.yaml.annotations.json the graph layout configs/r1.conf bind files, by relative pathrun/ <lab id>/ topology.clab.yaml copy, renamed to the instance name configs/r1.conf copies of the bind files clab-<instance name>/ created by containerlabWhen 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-*.
Data storage
Section titled “Data storage”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.