Antimony Desktop
Antimony Desktop runs Antimony on your own machine, for one person. It starts the Antimony server itself, in a Docker container next to your labs, and signs you in automatically. There is nothing to configure and no login.
To run Antimony for several people, or on a server, use the Docker deployment instead.
Requirements
Section titled “Requirements”- Linux on x86_64 or ARM64.
- Docker Engine, running, and your user allowed to use it, for example as a member of the
dockergroup. Labs need it anyway. - An internet connection on the first start, to download the Antimony server.
Install
Section titled “Install”The current release is Antimony 0.1.0. Every release contains Antimony Desktop as a package for Debian and Ubuntu, a package for Fedora, and an AppImage that runs on any distribution. Each comes for Intel and AMD processors and for ARM.
Download the package and install it:
curl -fLO https://github.com/antimony-team/antimony/releases/download/v0.1.0/antimony-desktop-0.1.0-amd64.debsudo apt install ./antimony-desktop-0.1.0-amd64.debOn ARM, replace amd64 with arm64 in both lines.
The package installs Docker Engine (docker.io) if neither it nor Docker’s own docker-ce is installed yet.
Download the package and install it:
curl -fLO https://github.com/antimony-team/antimony/releases/download/v0.1.0/antimony-desktop-0.1.0-x86_64.rpmsudo dnf install ./antimony-desktop-0.1.0-x86_64.rpmOn ARM, replace x86_64 with aarch64 in both lines.
The package needs Docker Engine, either Docker’s own docker-ce or Fedora’s moby-engine, and installs one of them if neither is installed yet.
Download the AppImage, make it executable and start it:
curl -fLO https://github.com/antimony-team/antimony/releases/download/v0.1.0/antimony-desktop-0.1.0-x86_64.AppImagechmod +x antimony-desktop-0.1.0-x86_64.AppImage./antimony-desktop-0.1.0-x86_64.AppImageOn ARM, replace x86_64 with arm64 in all three lines.
The AppImage needs no installation, but you install Docker Engine yourself.
Start the installed package from your applications menu, or with antimony-desktop in a terminal. On the first start, a small window shows the download of the Antimony server. After that, the app opens.
The packages don’t update themselves yet: to update, install the package of the new release the same way. To remove Antimony Desktop, use sudo apt remove antimony-desktop or sudo dnf remove antimony-desktop. Your labs and data in ~/.config/Antimony stay.
To check a download, compare it with the release’s checksums, or verify that it was built by the release workflow:
curl -fLO https://github.com/antimony-team/antimony/releases/download/v0.1.0/SHA256SUMSsha256sum -c SHA256SUMS --ignore-missinggh attestation verify antimony-desktop-0.1.0-amd64.deb --repo antimony-team/antimonySee verifying downloads.
Using the app
Section titled “Using the app”- Closing the window keeps Antimony running in the system tray, together with your labs. Open it again from the tray icon, or by starting the app again.
- Quit Antimony in the tray menu stops the server. Running labs keep running, and the server picks them up again at the next start.
- Only one instance runs at a time. Starting the app again opens the existing window.
Terminals, packet capture and everything else work as in the web version. Copy SSH command and Copy capture command use the server the app started, on 127.0.0.1. There is no Log out button, and the lab details have no Copy link, since a link to the app’s own server can’t be shared.
How it works
Section titled “How it works”At every start, the app:
- checks that Docker Engine is reachable, and that it isn’t Docker Desktop,
- downloads the server image if it isn’t there yet,
- picks two free ports on
127.0.0.1, one for the API and one for the SSH server, - writes the server’s
config.ymland starts the server container, - opens the window, which signs in with a token that is new on every start.
The server runs like the one of the Docker deployment: privileged, with access to Docker and the host’s network, so that it can run containerlab. It only listens on 127.0.0.1 and uses SQLite instead of PostgreSQL. When you quit the app, its container is removed.
The app uses the server of its own version, ghcr.io/antimony-team/antimony/server:<version>. Development builds use :dev and check for a newer one at every start.
Everything is kept in the app’s data folder, ~/.config/Antimony:
| File | Contents |
|---|---|
antimony.db |
The database: collections, topologies, labs |
storage/, run/ |
Topologies with their bind files, and deployed labs |
kinds.conf.yml |
Optional node kind settings, for example SSH logins for terminals. Create it to use it. |
config.yml |
The server’s configuration, written at every start. Changes are overwritten. |
server.log |
The server’s output, which also goes to the app’s own output |
ssh_host_key |
Host key of the SSH server |
The server runs as root in its container, so the files it creates belong to root. To remove the folder, use sudo rm -r ~/.config/Antimony.
Settings
Section titled “Settings”| Environment variable | Description |
|---|---|
SB_SERVER_IMAGE |
Server image to start instead of the app’s own version, for example SB_SERVER_IMAGE=ghcr.io/antimony-team/antimony/server:dev. |
The app always uses Docker Engine at /var/run/docker.sock. DOCKER_HOST doesn’t change it.
Troubleshooting
Section titled “Troubleshooting”| Problem | Solution |
|---|---|
| “Antimony needs Docker Engine, but only Docker Desktop was found.” | Install Docker Engine. Both can be installed side by side. |
| “You aren’t allowed to use Docker.” | Add your user to the docker group, then log out and in again. |
| “Docker Engine isn’t running.” | Start it, for example with sudo systemctl start docker. |
| “The Antimony server … couldn’t be downloaded: manifest unknown” | There is no server image for this version. Use a released version of Antimony Desktop, or start the app with SB_SERVER_IMAGE. |
| “The Antimony server stopped unexpectedly.” | See server.log in ~/.config/Antimony. |
Developing the app
Section titled “Developing the app”Antimony Desktop reuses the web interface. Everything specific to it is in the interface’s electron/ folder:
| File | Purpose |
|---|---|
main.ts |
The app: startup, window, tray, single instance, stopping the server when the app quits |
server.ts |
Picks the image and the ports, writes the server’s config and starts the server container |
docker.ts |
A small client for the Docker Engine API: the Docker Desktop check, image downloads with progress, containers and their output |
splash.ts |
The window that shows what the app is doing while it starts |
preload.ts |
Passes the server’s address and the login token to the interface |
config.yml |
Settings of the server on top of its defaults, such as auth.methods: [admin, desktop]. Ports and paths are set by the app. |
vite.config.ts, electron-builder.yml |
Build and packaging |
The interface signs in with the desktop login and sends the access token in a header, since the window is loaded from a file and can’t use cookies.
Building it
Section titled “Building it”You need Node.js 26, Yarn 1 (corepack enable), Task, and the tools that render the icons and assemble the packages. On Debian or Ubuntu:
sudo apt install librsvg2-bin libarchive-tools rpmgit clone https://github.com/antimony-team/antimonycd antimony/interfacetask package-electron-linuxThe AppImages, .deb and .rpm packages for x86_64 and ARM64 are in release/. Their version comes from package.json, which is 0.0.0-dev outside of releases, so it uses the :dev server image. To use your own server image, build it with task build-docker in server/ and start the app with SB_SERVER_IMAGE=antimony-server:dev.
Without packaging, task build-electron followed by yarn electron . starts the app from the repository. It then always uses the local image antimony-server:dev, and shows the server’s output in your terminal.
Releases
Section titled “Releases”CI builds all packages on every push to development and main and on pull requests that change the interface, and keeps them as the workflow artifact antimony-desktop, to catch build failures early. For a v* tag, the packages of that run are attached to the release, once the images of that version are published and the end-to-end tests have passed.