Happy is a tool for lightweight orchestration of simulated network topologies. Use it to test network protocols and other distributed execution programs on a single Linux development machine without using IoT device hardware.

What is it?

Happy simulates complex network topologies. On a single Linux machine, Happy can create multiple nodes with network stacks that are independent from each other. Some nodes may be connected to simulated Thread networks, others may connect to simulated Wi-Fi, WAN (Internet), or cellular networks.

Happy addresses the following use cases:

  • Testing network protocols and other distributed execution programs on a single Linux development machine without using hardware
  • Performing automated functional testing across a network
  • Running multiple concurrent, parallel networks on the same system to improve testing throughput

Happy solves these problems by creating network topology abstractions with minimal user overhead. Complex topologies may be created with a single shell command call. Happy supports both interactive use and automated scripting.

Use Happy shell commands to set up, test, and debug their code during development. The same networking configuration and test programs may then be scripted and used in automated testing.

Get started

The quickest and easiest way to get started with Happy is to go through the Codelab. It walks the user through all the Happy fundamentals, including:

  • Creating and deleting a topology
  • Networking nodes together
  • Saving and restoring topologies
  • Connecting a topology to the internet
  • Weave fundamentals

Try the Getting Started with Happy Codelab

See Setup and Usage for more information on setting up and using Happy.


Happy models the following:

  • Node — A Linux network namespace. Processes comprising the node run within a specified network namespace.
  • Link — A Linux network interface. Happy uses the veth network device to support L3 (IP) interfaces and the tap network device to support L2 interfaces out of the box.
  • Network — Linux network namespaces with an Ethernet bridge running within them.


Happy is a collection of Python modules. Core Happy modules provide abstractions for:

  • Managing node abstractions
    • Adding, modifying, and deleting nodes
    • Running a set of processes within the node
  • Managing links
    • Adding, modifying, and deleting links
    • Assigning links to a node and a network
    • Assigning and modifying address assignments
  • Managing networks
    • Creating, modifying, and destroying networks
    • Network connectivity
  • Managing the overall state of the framework in a cohesive fashion

Most of the abstractions implemented by Happy modules map into commands that invoke Linux network tools.

Happy also contains a set of plug-ins found in /plugins. Plug-ins wrap a set of functionality related to a particular technology. For example, /plugins/weave contain helpers that wrap various Weave applications for execution within Happy.


Users can build simulated topologies via two methods:

  • Shell commands — All commands are in /bin.
  • Python scripts — Import Happy modules to call Happy commands in your own Python scripts. Modules are in /happy.

For more information on using Happy modules in your own Python scripts, see Python scripting.