Kiso documentation

Kiso is a config-driven experiment management platform that helps researchers run reproducible experiments across academic testbeds (Vagrant, FABRIC, Chameleon). The same config file runs locally and on real testbeds with minimal changes.

Introduction

• Introduction
• Getting started

Tutorials

• Your first experiment
  • What you will build
  • Prerequisites
  • Step 1 — Install Kiso
  • Step 2 — Write the config file
  • Step 3 — Run the experiment locally on Vagrant
  • Step 4 — Collect and view results
  • Step 5 — Run the same config on FABRIC
  • What you have accomplished
  • What’s next
• Multi-testbed experiment
  • What you will build
  • Prerequisites
  • Step 1 — Configure the experiment for two testbeds
  • Step 2 — Write the Pegasus workflow script
  • Step 3 — Run the Pegasus workflow
  • Step 4 — Collect results and view them
  • What you have accomplished
  • What’s next

Concepts

• What is Kiso?
  • The problem Kiso solves
  • Core design philosophy
  • Design goals
  • Who Kiso is for
  • Component categories
  • See also
• The experiment model
  • The four phases
  • Monitoring and debugging
  • The config file as single source of truth
  • Testbed portability
  • See also
• Config file anatomy
  • Annotated example
  • The name field
  • The sites section
  • The software section
  • The deployment section
  • The experiments section
  • How the sections relate
  • See also
• Components
  • Testbeds
  • Software
  • Deployments
  • Experiment types
  • See also

How-to guides

• Set up on FABRIC
  • Prerequisites
  • FABRIC-specific config fields
  • FABRIC project permissions
  • Minimal working example
  • Example with public IP (for multi-testbed HTCondor)
  • Verifying the setup
  • Common failure modes
  • See also
• Set up on Vagrant
  • Prerequisites
  • Vagrant-specific config fields
  • Minimal working example
  • Verifying the setup
  • Common failure modes
  • See also
• Set up on Chameleon
  • Prerequisites
  • Chameleon bare metal (kind: chameleon)
  • Verifying the setup
  • Common failure modes
  • See also
• Set up on Chameleon Edge
  • Prerequisites
  • Config fields
  • Machine types
  • Container fields
  • Minimal working example
  • Verifying the setup
  • Common failure modes
  • See also
• Use Docker
  • Prerequisites
  • Config fields
  • Minimal working example
  • Using Docker in experiment scripts
  • See also
• Use Apptainer
  • When to prefer Apptainer over Docker
  • Prerequisites
  • Config fields
  • Minimal working example
  • Using Apptainer in experiment scripts
  • See also
• Use Ollama
  • What kinds of experiments Ollama enables
  • Prerequisites
  • Config fields
  • How to specify which model to use
  • Minimal working example
  • Calling Ollama from experiment scripts
  • See also
• Run custom setup scripts
  • Prerequisites
  • Config fields
  • Minimal working example
  • Running different scripts on different node groups
  • See also
• Deploy with HTCondor
  • Prerequisites
  • Config fields
  • Single-node setup (personal)
  • Distributed setup (single testbed)
  • Minimal working example (personal + Pegasus)
  • Verifying the HTCondor pool is healthy
  • Multi-testbed deployments
  • Why public IPs are required
  • Common failure modes
  • See also
• Run a Shell experiment
  • When Shell is the right choice
  • Config fields
  • Minimal working example
  • Setup then run
  • Running scripts on multiple node groups
  • See also
• Run a Pegasus workflow
  • Execution flow
  • When Pegasus is the right choice
  • Prerequisites
  • Config fields
  • Writing the workflow script (main)
  • Using setup, post_scripts, and outputs together
  • Minimal working example
  • See also
• Collect and export results
  • Where results are stored
  • Supported output formats
  • Changing the output directory
  • Re-running experiments
  • See also

Extending Kiso

• How Kiso extensions work
  • How the plugin system works
  • The extension model
  • What each extension type must implement
  • Contracts by extension type
  • Config key naming conventions
  • Error handling and logging
  • See also
• Add a software runtime
  • Prerequisites
  • Step 1 — Create the plugin subpackage
  • Step 2 — Define the configuration dataclass
  • Step 3 — Define the JSON schema
  • Step 4 — Write the Ansible playbook
  • Step 5 — Implement the installer class
  • Step 6 — Register the entry point
  • Step 7 — Verify the plugin loads
  • Step 8 — Write tests
  • See also
• Add a deployment
  • Prerequisites
  • Step 1 — Create the plugin subpackage
  • Step 2 — Define the configuration dataclass
  • Step 3 — Define the JSON schema
  • Step 4 — Write the Ansible playbook
  • Step 5 — Implement the installer class
  • Step 6 — Register the entry point
  • Step 7 — Verify the plugin loads
  • Step 8 — Write tests
  • See also
• Add an experiment type
  • Prerequisites
  • Step 1 — Create the plugin subpackage
  • Step 2 — Define the configuration dataclass
  • Step 3 — Define the JSON schema
  • Step 4 — Implement the runner class
  • Step 5 — Register the entry point
  • Step 7 — Verify the plugin loads
  • Step 8 — Write tests
  • See also
• Software interface reference
  • Class attributes
  • Methods
  • Configuration dataclass conventions
  • JSON schema conventions
  • Example: minimal software plugin
  • See also
• Deployment interface reference
  • Class attributes
  • Methods
  • Configuration dataclass conventions
  • JSON schema conventions
  • Error conditions
  • See also
• Experiment type interface reference
  • Class attributes
  • Methods
  • Configuration dataclass conventions
  • JSON schema conventions
  • Output directory conventions
  • Error conditions
  • See also

Experiment gallery

• Experiment gallery
• Pydantic agent
• Multiple Pydantic agents
• Plankifier
• Orcasound
• COLMENA
• Network Measurement Experiment

Reference

• Config file reference
  • Complete annotated example
  • Top-level keys
  • sites[] — Vagrant
  • sites[] — FABRIC
  • sites[] — Chameleon bare metal
  • sites[] — Chameleon Edge
  • software.docker
  • software.apptainer
  • software.ollama[]
  • software.shell[]
  • deployment.htcondor[]
  • experiments[] — Shell
  • experiments[] — Pegasus
  • variables
  • See also
• CLI reference
  • Global options
  • kiso check
  • kiso up
  • kiso run
  • kiso down
  • kiso ssh
  • kiso version
  • Typical workflow
  • See also
• Testbed parameters
  • Vagrant (kind: vagrant)
  • FABRIC (kind: fabric)
  • Chameleon
  • Label naming rules
  • See also
• Output formats
  • Output directory structure
  • Pegasus workflow output
  • File transfer outputs
  • Environment state file (env)
  • See also
• API reference
  • kiso.utils
  • kiso.schema
  • kiso.objects
  • kiso.edge
  • kiso.ip
  • kiso.errors
  • See also
• Glossary
  • Kiso terms
  • Testbed terms
  • HTCondor terms
  • Workflow and experiment terms
  • See also
• Changelog
  • v0.1.0a10 (2026-03-15)
  • v0.1.0a9 (2026-01-28)
  • v0.1.0a8 (2026-01-07)
  • v0.1.0a7 (2025-12-08)
  • v0.1.0a6 (2025-11-13)
  • v0.1.0a5 (2025-11-05)
  • v0.1.0a4 (2025-11-05)
  • v0.1.0a3 (2025-11-03)
  • v0.1.0a2 (2025-11-03)
  • v0.1.0a1 (2025-09-12)
  • v0.1.0a0 (2025-09-10)

About

• Contributing
• Contact
• Funding
• License
• Citing Kiso
• External links