cml

CML

Build and operate CML labs through the CML MCP tools. The guidance below covers the conventions and pitfalls an agent will not infer correctly on its own. General networking knowledge (e.g., what OSPF is, how a switch works) is assumed and not repeated here.

IDs are opaque — copy them, never reconstruct them. When a tool returns an identifier (lab, node, interface, or link UUID), pass that exact value to later calls. Never retype an ID from memory or rebuild one from context; a single altered character makes the call fail, and the corrupted value can still look well-formed, so you cannot catch the error by inspecting it. If you are not certain you have the exact value, re-fetch it with the relevant listing tool (get_nodes_for_cml_lab, get_interfaces_for_node, get_all_links_for_lab) rather than guessing. One exception: send_cli_command/send_cli_config_command identify their node by label, not UUID — see Configuration.

Default approach: build incrementally, not in one shot

Build a lab by composing small, verifiable steps. Do not try to hand-assemble a complete topology object and import it in one call unless the user has explicitly provided a finished model.

Default sequence:

1. create_empty_lab (title, optional description/notes) → capture the returned lab_id. Lab notes are rendered as Markdown in the CML UI, so record the topology's purpose / high-level description there — it's what a human sees when they open the lab.
2. get_cml_node_definitions once, to learn valid node_definition values for this server. Do not guess names like csr1000v/iosv — servers differ in what's installed.
   1. Call the tool and check the result. If it returns an error or an empty list, stop immediately and tell the user: the server returned no node definitions and you cannot proceed without them. Do not guess any node_definition value.
   2. If the device type the user asked for isn't in the returned list, stop and tell them — name the closest available definitions and let them choose. Never silently substitute a different device type.
   3. If two or more definitions share the same vendor and device family as the requested device (matching the family name in the definition name or the description's product line — e.g. "a Cisco router" matching iol-xe, iosv, csr1000v, cat8000v), list each one by its exact name and ask the user to choose before proceeding. Do not silently choose the first match.
   4. Otherwise, use the single matching definition.
   5. For which definition to recommend as the default among installed options (e.g. iol-xe for routers, ioll2-xe for switches), see references/node_selection_guidance.md.
3. add_node_to_cml_lab per device. Set label, node_definition, and x/y (see Layout). Each add auto-creates that definition's default interfaces.
4. Connect nodes (see Connecting nodes — this is the step most often done wrong).
5. Apply configuration (see Configuration).
6. Start nodes when the user wants the lab running. Before starting a node, read its current state with get_nodes_for_cml_lab. If it is already BOOTED, skip the start call and report that. If the state cannot be read, report that and do not start it. To start an entire lab, use start_cml_lab(lab_id). To start nodes in a specific order (e.g., core infrastructure before edge devices), call start_cml_node(lab_id, node_id) sequentially, using wait_for_convergence=true on each node before starting the next when a later node depends on an earlier one being reachable. See references/operations.md for full lifecycle details.