Skip to content

Running a lab

The packaged image starts with /boxen/boxen run. Containerlab supplies the node's hostname, credentials, networking, and optional startup configuration; the profile turns those inputs into commands for the guest OS.

Start with the platform's Containerlab kind

Choose the kind for your guest and set image to the name produced by boxen build. For example:

name: router-lab
topology:
  nodes:
    r1:
      kind: juniper_vjunosrouter
      image: boxen-juniper_vjunos-router:25.2R1.9
      healthcheck:
        start-period: 1200
    r2:
      kind: juniper_vjunosrouter
      image: boxen-juniper_vjunos-router:25.2R1.9
      healthcheck:
        start-period: 1200
  links:
    - endpoints: ["r1:ge-0/0/0", "r2:ge-0/0/0"]

The Boxen profile juniper_vjunos-router contains a hyphen, while the Containerlab kind juniper_vjunosrouter does not. Use the platform list and the relevant Containerlab kind documentation for interface aliases and runtime defaults.

sudo containerlab deploy --topo router-lab.clab.yml
sudo containerlab inspect --topo router-lab.clab.yml
docker logs -f clab-router-lab-r1

Runtime order

  1. Read /boxen/profile.yaml and construct the template values from the runtime flags.
  2. Write 1 booting to /health.
  3. Wait for interfaces when CLAB_INTFS specifies a count, then honor BOOT_DELAY in seconds.
  4. Execute preRunCommands in the container shell.
  5. Launch QEMU with the packaged disk and runtime hardware settings.
  6. Start the TC service that joins container interfaces to guest TAPs.
  7. Open the serial console and execute run.process.
  8. If /config/startup-config.cfg exists, execute run.configProcess.
  9. Close the automation console and write 0 running to /health.
  10. Keep the container running until its context is cancelled.

Provisioning errors stop the run process before it can mark the node healthy. Boxen does not rerun packaging during this phase.

Startup configuration

Declare a startup file on the Containerlab node:

startup-config: ./configs/r1.cfg

Containerlab's VM integration places the file at /config/startup-config.cfg. The profile's configProcess must enter the appropriate NOS configuration mode, send or load the file, and save or commit it. The presence of a file only triggers that process; it is not an automatic configuration loader by itself.

For CLI-oriented platforms, a typical step is:

run:
  configProcess:
    - type: write
      write:
        contentFromStartupConfig: true

Add the platform's mode changes and completion checks around this step. The vJunos-router profile instead loads hierarchical configuration using load merge terminal. Avoid startup commands that break management connectivity or change the console credentials expected during the next boot.

Hardware and boot overrides

Set environment variables in the node's container:

env:
  QEMU_MEMORY: "8192"
  QEMU_CPU: host
  QEMU_SMP: "4"
  BOOT_DELAY: "10"
  CLAB_MGMT_PASSTHROUGH: "true"

These override generated QEMU fields where supported. QEMU_SMP is considered when the profile has a nonzero cpuCores. A profile's complete section override bypasses that section's normal generator. See QEMU configuration and the environment reference.

Interface wiring

By default, eth0 is management and eth1 through ethN are data ports. Boxen creates corresponding tap0 for transparent management and tap1 through tapN for data traffic. A background TC service redirects frames in both directions, notices interfaces that appear after startup, and reattaches recreated interfaces.

Containerlab kind aliases map the first NOS data port to eth1; the NOS's port numbering can start at zero. CLAB_INTF_PREFIX and CLAB_MGMT_INTF let an integration supply different container interface names.

Readiness and console access

docker exec clab-router-lab-r1 /boxen/boxen health
docker exec clab-router-lab-r1 cat /health
docker inspect --format '{{.State.Health.Status}}' clab-router-lab-r1

The base image checks readiness every five seconds and allows a five-minute startup period. Slow nested guests can need a longer node-specific healthcheck.start-period. The readiness file records successful provisioning, including startup configuration; it does not continuously probe guest services.

After provisioning closes the automation console, connect manually:

docker exec -it clab-router-lab-r1 telnet localhost 5001

Exit telnet with Ctrl+], then q. Avoid taking over the console while profile automation is running.

Stop and recreate

sudo containerlab destroy --topo router-lab.clab.yml

Removing a node removes its writable disk changes unless you arranged separate persistence. A newly created node uses the packaged image baseline plus its runtime and startup configuration.