intermesh

Contributing

Docker

You need Docker installed and running. On Linux, install it via your distribution's package manager. On macOS, you can use Docker Desktop or Colima. Development on macOS works but is not as heavily tested as Linux — if you hit mac-specific issues, ask in Slack.

Build Dependencies

Option 1: Nix + direnv (Recommended)

Nix is a package manager focused on reproducible builds that works on Linux and macOS. You don't need to understand it — it will just make sure you get all the right dependencies at the right versions, guaranteed to be compatible with each other. If you're curious, Zero to Nix is a good introduction.

• Install Nix — the Determinate Systems installer is the easiest option, though some prefer the official installer
• Install direnv and hook it into your shell (bonus points if you use nix profile install nixpkgs#direnv)

Once both are installed, cd into the repo and run direnv allow. From that point on, every time you enter the directory all build tools (Rust, protobuf, Ruby, cmake, etc.) are automatically available.

Option 2: Manual Installation

If you'd rather manage dependencies yourself, you'll need:

• Rust (rustc, cargo, clippy, rustfmt)
• protobuf compiler (protoc)
• cmake
• Ruby (for the custom linter)
• pkg-config

This is mostly standard Rust ecosystem tooling. You're on your own for version management, but it shouldn't be too hard.

Verify Your Setup

A good first goal is to get cargo local to pass:

cargo local

This runs formatting, linting, a full build, unit tests, and e2e tests. If it passes, you're mostly good to go.

Development Commands

• cargo build — Build the project
• cargo test [filter] — Run unit tests (use the filter to run a specific test while iterating, e.g. cargo test my_test_name)
• cargo lint — Run format check, clippy, and custom lints
• cargo local — Lint, build, unit tests, and e2e tests
• cargo all — Everything in local plus VM tests
• cargo deps — Check for outdated/unused/vulnerable dependencies

E2E Tests

cargo test-e2e            # run all e2e tests
cargo test-e2e test_name  # run a specific test

The e2e tests spin up Docker containers on a local bridge network. Each container runs the intermesh binary built from your working tree. The only requirement beyond the build dependencies is a running Docker daemon.

VM Tests

The VM tests exercise intermesh across separate machines using Docker contexts that point to remote VMs over SSH.

Setup

You need three VMs (vm1, vm2, vm3) with Docker installed and SSH access. Create a Docker context for each:

docker context create vm1 --docker "host=ssh://user@vm1-hostname"
docker context create vm2 --docker "host=ssh://user@vm2-hostname"
docker context create vm3 --docker "host=ssh://user@vm3-hostname"

Verify connectivity:

docker --context vm1 info
docker --context vm2 info
docker --context vm3 info

Running

cargo test-vm            # run all VM tests
cargo test-vm test_name  # run a specific test
cargo all                # run everything (local + VM tests)

Unlike e2e tests, the daemon containers run with network_mode: host so they operate on the VM's real network interfaces. VM tests use a global lock since all worktrees share the same VMs.