Skip to content

Containerlab API Server#

The clab-api-server exposes Containerlab operations over an HTTP API. It is meant for cases where the lab host needs to be controlled by another program, a browser UI, or a remote user session instead of by someone typing containerlab commands directly on the host.

Typical uses are:

  • running the Containerlab Desktop GUI or Containerlab Web GUI
  • integrating Containerlab with automation systems
  • giving a UI or service account a controlled way to deploy, inspect, destroy, and operate labs
  • managing lab files on a shared lab server

The API server runs on the Linux system that owns the container runtime and the lab files. Clients connect to that API endpoint from the same machine, a browser, a desktop app, or another workstation.

Note

The API server embeds Containerlab as a Go library. When you install and run clab-api-server directly, you do not need to install a separate containerlab binary for the API server itself.

Installation#

There are several ways to run the API server. For a persistent lab host, the systemd installation is the recommended path.

Systemd service#

Install the latest release:

curl -fsSL https://raw.githubusercontent.com/srl-labs/clab-api-server/main/install.sh | sudo bash -s -- install

The installer:

  • downloads the API server binary to /usr/local/bin/clab-api-server
  • creates /etc/clab-api-server/clab-api-server.env
  • creates the clab-api-server.service systemd unit
  • creates the default clab_api and clab_admins groups if they do not exist
  • generates a random JWT_SECRET for new installations

Edit the environment file before starting the service:

sudoedit /etc/clab-api-server/clab-api-server.env

At minimum, set:

  • API_SERVER_HOST to the hostname or IP address clients should use
  • CORS_ALLOWED_ORIGINS if a browser client contacts the API server directly

Add users to the API group, then start the service:

sudo usermod -aG clab_api <username>
sudo systemctl enable --now clab-api-server
sudo systemctl status clab-api-server

For an immediate start with the generated defaults, use install --start.

The systemd service runs as root because it controls host container runtime resources, network namespaces, Linux users, and lab files.

Upgrade to the latest release:

sudo clab-api-server version upgrade

Install a specific release, including an older release for downgrade:

curl -fsSL https://raw.githubusercontent.com/srl-labs/clab-api-server/main/install.sh | sudo bash -s -- upgrade --version clab-0.73.0-api-0.2.1

Uninstall removes the service and binary while keeping configuration:

curl -fsSL https://raw.githubusercontent.com/srl-labs/clab-api-server/main/install.sh | sudo bash -s -- uninstall

Use uninstall --purge only when you also want to remove /etc/clab-api-server/clab-api-server.env.

Containerlab tools command#

For quick trials, demos, or temporary API access, Containerlab can start the API server as a container:

sudo containerlab tools api-server start \
  --labs-dir /opt/containerlab/labs

Use the matching commands to inspect or remove the API server container:

sudo containerlab tools api-server status
sudo containerlab tools api-server stop

See the command reference for the complete flag list:

Warning

The standalone API server and the containerlab tools api-server start helper both default to port 8090 and HTTPS.

Direct binary#

Download and run a release binary directly when you want to test without installing the service:

curl -fsSL https://raw.githubusercontent.com/srl-labs/clab-api-server/main/install.sh | sudo bash -s -- pull-only
sudo clab-api-server -env-file /path/to/clab-api-server.env

Configuration is read from environment variables or a .env file in the current directory.

Container image#

The API server can also run as a container. This is useful when you want to manage it with your own container tooling:

docker run -d \
  --name clab-api-server \
  --privileged \
  --network host \
  --pid host \
  -e LOG_LEVEL=debug \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /var/run/netns:/var/run/netns \
  -v /var/lib/docker/containers:/var/lib/docker/containers \
  -v /etc/passwd:/etc/passwd:ro \
  -v /etc/shadow:/etc/shadow:ro \
  -v /etc/group:/etc/group:ro \
  -v /etc/gshadow:/etc/gshadow:ro \
  -v /home:/home \
  ghcr.io/srl-labs/clab-api-server/clab-api-server:latest

The bind mounts give the API server access to the host container runtime, network namespaces, Linux user database, and user lab files.

Users and access#

The API server authenticates Linux users from the host it runs on. A user must:

  • exist on the API server host
  • belong to API_USER_GROUP, clab_api by default, or SUPERUSER_GROUP, clab_admins by default
  • log in with the Linux username and password

Create the default groups and add users if they do not exist yet:

sudo groupadd -f clab_api
sudo groupadd -f clab_admins
sudo usermod -aG clab_api <username>

Successful login returns a JWT token that clients use for API requests.

Superusers can see and operate all labs. Regular API users operate within their user context and lab ownership.

Configuration#

These settings are the ones most users need to look at first:

Variable Default Purpose
API_PORT 8090 API server listen port
API_SERVER_HOST localhost Hostname or IP address shown to clients for API and SSH access
JWT_SECRET generated by installer Secret used to sign login tokens
JWT_EXPIRATION 24h Token lifetime, for example 24h or 7d
API_USER_GROUP clab_api Linux group allowed to use the API
SUPERUSER_GROUP clab_admins Linux group with elevated API access
CLAB_RUNTIME docker Container runtime used for labs
CORS_ALLOWED_ORIGINS unset Browser origins allowed to call the API directly
TLS_ENABLE true Serve the API over HTTPS
TLS_AUTO_CERT true Generate a local self-signed certificate if cert files are unset

The full configuration reference is maintained in the clab-api-server repository.

API docs#

When the server is running, the interactive API documentation is available from the API server itself:

https://<server>:<port>/swagger/index.html
https://<server>:<port>/redoc

The published API reference is available at:

https://srl-labs.github.io/clab-api-server/

API example#

Log in with a Linux user accepted by the API server:

TOKEN=$(curl -sk -X POST https://localhost:8090/login \
  -H "Content-Type: application/json" \
  -d '{"username":"your_linux_username","password":"your_linux_password"}' \
  | jq -r '.token')

List labs:

curl -k -H "Authorization: Bearer $TOKEN" https://localhost:8090/api/v1/labs

Using it with Containerlab GUI#

The Containerlab Desktop GUI and Containerlab Web GUI connect to a reachable API server URL and log in with a Linux user accepted by the API server. For regular use, run clab-api-server as a service on the lab host, then point the GUI at that URL.

On macOS and Windows, the API server still needs to run in the Linux environment that owns Docker and the lab files, such as a remote lab host, a Linux VM, a devcontainer, Docker Desktop VM, or OrbStack VM. The GUI can run on the workstation and connect to that API endpoint.