Your first experiment

Your first experiment#

This tutorial walks you from a fresh installation of Kiso to a working experiment result. You will run a simple shell experiment locally using Vagrant, then run the same config on FABRIC — demonstrating testbed portability in practice.

What you will build#

You will run a shell experiment that provisions a local Vagrant VM, installs Docker on it, runs a container that prints the VM hostname, and retrieves the output back to your machine. The experiment itself is intentionally trivial — the goal is to understand how Kiso’s config file, labels, and four-phase lifecycle fit together before working with real testbed infrastructure.

At the end of the tutorial you will make a single one-line change to the same config to run it on FABRIC, demonstrating testbed portability.

Prerequisites#

Step 1 — Install Kiso#

pip install kiso[vagrant]

To run on other testbeds later, install the matching extra: kiso[fabric] or kiso[chameleon].

Verify the installation:

kiso version

Step 2 — Write the config file#

Create a file called experiment.yml in a new directory:

name: hello-kiso

sites:
  - kind: vagrant
    backend: virtualbox
    box: bento/rockylinux-9
    resources:
      machines:
        - labels:
            - compute
          flavour: small
          number: 1
      networks:
        - labels:
            - r1
          cidr: 172.16.42.0/16

software:
  docker:
    labels:
      - compute

experiments:
  - kind: shell
    name: shell-experiment
    description: An experiment to print a message
    scripts:
      - labels:
          - compute
        script: |
          #!/bin/bash
          docker run --rm alpine echo "Hello, world!" | tee hello.txt
    outputs:
      - labels:
          - compute
        src: hello.txt
        dst: output

This config does three things:

  • Provisions one small Vagrant VM labelled compute

  • Installs Docker on that VM

  • Runs a single shell experiment that pulls and runs the Docker alpine image, prints Hello, world!, and downloads the output to output/ directory

The labels field is how Kiso connects resources to software and experiments — everything targeting compute runs on the same machine.

Step 3 — Run the experiment locally on Vagrant#

Validate the config: (optional but recommended):

kiso check experiment.yml

Provision the VM and install software:

kiso up experiment.yml

Kiso creates the Vagrant VM and installs Docker on it. This may take a few minutes the first time.

Run the experiment:

kiso run experiment.yml

You will see the hostname of the Vagrant VM printed by the alpine container.

Check the output:

ls -l output/hello.txt

Experiment output(s) are stored in the output/ directory (the default; change it with --output).

Tear down when done:

kiso down experiment.yml

Step 4 — Collect and view results#

After kiso run, results are written to the output directory:

output/
  hello.txt

View the output:

cat output/hello.txt

Step 5 — Run the same config on FABRIC#

This is the payoff. Change a few lines in experiment.yml and get it running on FABRIC:

sites:
  - kind: fabric
    rc_file: secrets/fabric_rc
    walltime: "02:00:00"
    resources:
      machines:
        - labels:
            - submit
          site: FIU
          flavour: small
          number: 1
      networks:
        - labels:
            - v4
          kind: FABNetv4
          site: FIU
          nic:
            kind: SharedNIC
            model: ConnectX-6

Everything else — the software block, the experiment block, the labels — stays identical.

Before running on FABRIC you need credentials. See Set up on FABRIC for how to configure them.

Once credentials are in place:

kiso up experiment.yml
kiso run experiment.yml
kiso down experiment.yml

The experiment runs on FABRIC infrastructure using the modified experiment file.

What you have accomplished#

🎉 Congratulations — you have run a complete Kiso experiment end to end. That is no small thing. Specifically, you have:

  • ✅ Written a config file that fully describes an experiment — resources, software, and what to run

  • ✅ Used kiso up to provision a VM and install Docker on it automatically, without touching a shell on the remote machine

  • ✅ Used kiso run to execute a script on that VM and retrieve the output to your local machine

  • ✅ Moved the same experiment from a local Vagrant VM to real FABRIC infrastructure

That last point is worth pausing on. Most researchers spend days porting an experiment from one environment to another. You just did it in few lines. 🚀 The config file you wrote is a fully reproducible experiment description — anyone with Kiso and the same config can reproduce exactly what you ran, on any supported testbed. That is the core idea behind everything else Kiso does, and you have already seen it work.

What’s next#