Skip to content

Antimony Desktop

Zoey leaning on a large Electron logo

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.

  • Linux on x86_64 or ARM64.
  • Docker Engine, running, and your user allowed to use it, for example as a member of the docker group. Labs need it anyway.
  • An internet connection on the first start, to download the Antimony server.

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:

Terminal window
curl -fLO https://github.com/antimony-team/antimony/releases/download/v0.1.0/antimony-desktop-0.1.0-amd64.deb
sudo apt install ./antimony-desktop-0.1.0-amd64.deb

On 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.

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:

Terminal window
curl -fLO https://github.com/antimony-team/antimony/releases/download/v0.1.0/SHA256SUMS
sha256sum -c SHA256SUMS --ignore-missing
gh attestation verify antimony-desktop-0.1.0-amd64.deb --repo antimony-team/antimony

See verifying downloads.

  • 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.

At every start, the app:

  1. checks that Docker Engine is reachable, and that it isn’t Docker Desktop,
  2. downloads the server image if it isn’t there yet,
  3. picks two free ports on 127.0.0.1, one for the API and one for the SSH server,
  4. writes the server’s config.yml and starts the server container,
  5. 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.

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.

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.

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.

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:

Terminal window
sudo apt install librsvg2-bin libarchive-tools rpm
Terminal window
git clone https://github.com/antimony-team/antimony
cd antimony/interface
task package-electron-linux

The 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.

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.