Skip to content

Quick start

Install the server on a Linux host with Docker, let one user in, and run a two-node lab with nothing but curl.

This is the lab you will run: two Linux containers, wired together on eth1.

name: hello
 
topology:
  defaults:
    kind: linux
    image: alpine:3.23
  nodes:
    client: {}
    server: {}
  links:
    - endpoints: [client:eth1, server:eth1]

  1. Install and start the server.

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

    The server now listens on https://<host>:8090 with a self-signed certificate.

  2. Let a user in. Any Linux account in the clab_api group can sign in with its password.

    sudo usermod -aG clab_api alice

  3. Sign in. The response holds a JWT for every further call.

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

  4. Save the topology. Write the lab above to hello.clab.yml, or download it from the diagram:

    cat > hello.clab.yml <<'EOF'
name: hello

topology:
  defaults:
    kind: linux
    image: alpine:3.23
  nodes:
    client: {}
    server: {}
  links:
    - endpoints: [client:eth1, server:eth1]
EOF

  5. Upload and deploy it. The file goes into your workspace, then the server deploys it from there:

    curl -sk -X PUT "$API/api/v1/labs/workspace/file?path=hello.clab.yml" \
  -H "Authorization: Bearer $TOKEN" --data-binary @hello.clab.yml

curl -sk -X POST "$API/api/v1/labs/hello/deploy?path=hello.clab.yml" \
  -H "Authorization: Bearer $TOKEN"

  6. Look inside. Inspect the lab, then ping across the link from client:

    curl -sk -H "Authorization: Bearer $TOKEN" $API/api/v1/labs/hello

curl -sk -X POST "$API/api/v1/labs/hello/exec?nodes=client" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"command": "ip addr add 10.0.0.1/24 dev eth1"}'
curl -sk -X POST "$API/api/v1/labs/hello/exec?nodes=server" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"command": "ip addr add 10.0.0.2/24 dev eth1"}'
curl -sk -X POST "$API/api/v1/labs/hello/exec?nodes=client" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"command": "ping -c 3 10.0.0.2"}'

    Each answer holds the command's stdout, stderr, and exit code per node.

  7. Destroy it.

    curl -sk -X DELETE "$API/api/v1/labs/hello" -H "Authorization: Bearer $TOKEN"

hello.clab.yml stays in Alice's workspace (~/.clab/ by default), ready to deploy again. The Containerlab Apps show the same lab, and can draw, deploy, and open terminals on it.