Skip to content

Simplify the README #178

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ejj merged 2 commits into from
Aug 10, 2026
Merged

Simplify the README #178

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c0e790a
endor: satisfy clippy::manual_assert_eq under Rust 1.97
ejj Aug 10, 2026
33128ee
Simplify README.md
ejj Aug 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
213 changes: 20 additions & 193 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,204 +1,31 @@
# intermesh

Intermesh is a trust-based identity mesh written in Rust. Nodes exchange signed
control statements about names, addresses, and policy. Each node evaluates that
state locally to build its own view of the mesh. By bringing control to the
node, Intermesh distributes responsibility for trust across the network.
Intermesh is a research prototype from the
[NetSys Lab](https://netsys.cs.berkeley.edu/) at UC Berkeley exploring
disaggregated control in service meshes: what it takes for independently
operated meshes to interoperate across partial-trust boundaries without a
shared control plane.

Intermesh runs on Linux. Build and test on Linux to match production and CI.
Nodes exchange signed, time-bounded endorsements about names, addresses, and
policy. Each node runs a Datalog-style trust engine that derives its own local
view of the mesh from that authenticated control state, so admission,
disclosure, and peering are explicit policy rather than the implicit behavior
of a central controller.

## Getting Started
## Status

### Platform
Intermesh exists to explore a research idea, and it shows. It is not
production ready, not audited, and not meant to be deployed; interfaces,
policy semantics, and wire formats change without notice.

- Linux is required for Intermesh build and test workflows.
- Use a Linux host directly (bare metal, VM, or cloud instance), or use
Docker Desktop/Colima and run your workflow in a Linux container (mount the
repo and the Docker socket).
## Development

### Prompt-Driven Setup (especially useful on macOS/Windows)

If you are on macOS or Windows and want an assistant to drive setup, paste this
into Claude Code (or similar).

Budget 10-20 minutes (sometimes a touch longer) for a first run. Most of that
is unattended downloads and a cold Rust build. Several steps print nothing for
minutes at a time; that is normal, not a hang.

```text
I need a Linux-based Intermesh dev environment on this machine.
Create the smallest reliable setup and explain each step briefly.

Requirements:
- Intermesh tooling must run in Linux
- Docker daemon must be available
- Read this Intermesh README (where this prompt came from) first and treat it
as the source of truth
- Repo is already cloned at <PATH_TO_INTERMESH> (ask user if no path was provided)
- Prefer manual tool install in Linux (rustup + protoc + cmake + ruby +
pkg-config + musl-tools + git + build-essential)
- If using a container: mount the repo and the Docker socket, and set
DOCKER_BUILDKIT=1 (the e2e image build requires BuildKit)
- If using a container: ensure docker CLI, buildx, and docker compose are
installed in that container
- Set LANG=C.UTF-8 and LC_ALL=C.UTF-8 before running cargo local
- Nix is optional, not required

Please:
1) Detect host OS and choose a Linux execution path (native Linux, or Linux container/VM).
2) Give exact commands to set up dependencies.
3) Run verification commands and show pass/fail:
- docker info
- cargo --version
- cargo local
4) Warn me before any step that takes more than a few minutes, and say how
long it should take. The first cargo local runs 10-20 minutes and goes
silent for long stretches; do not report it as hung or kill it.
5) If a step fails, show likely cause and next command to run.
6) End with a short checklist of what is done vs what is still needed.
```

### Docker

Docker is required for e2e tests. Install it with your distro package manager
on Linux, then confirm:

```bash
docker info
```

## Setup

### Option 1: Manual Setup (recommended)

If you want a straightforward, roll-your-own setup, install:

- `rustup` (then run `rustup toolchain install` in this repo)
- `protoc`
- `cmake`
- `ruby`
- `pkg-config`
- `musl-tools`
- `git`
- a C toolchain (`build-essential` on Debian/Ubuntu)
- `flock` (usually provided by `util-linux`)

`rust-toolchain.toml` pins Rust, clippy, rustfmt, rust-analyzer, and targets.

### Option 2: Nix + direnv

Nix gives a reproducible dev shell with the exact toolchain and versions:

- Install [Nix](https://nixos.org/) (the
[Determinate installer](https://github.com/DeterminateSystems/nix-installer)
is the easiest path)
- Install [direnv](https://direnv.net/) and hook it into your shell
- From repo root: `direnv allow`

If you'd rather not manage tool versions yourself, use this.

## Verify Your Setup

Run the full local check:

```bash
cargo local
```

This runs formatting, lint, build, unit tests, and e2e tests.

Expect 10-20 minutes the first time. The cold Rust build and the e2e image
build take most of the time, and both go quiet for minutes at a time. Later
runs are much faster once the build cache and the e2e base image are warm.

## Core Commands

- `cargo build` - build the project
- `cargo test [filter]` - run unit tests; pass a filter to run just the tests
whose name matches it, e.g. `cargo test my_test_name`
- `cargo lint` - run format check, clippy, and custom lints
- `cargo local` - lint + build + unit tests + e2e tests
- `cargo all` - `local` plus perf tests and VM tests when Incus is available
- `cargo deps` - dependency freshness and vulnerability checks

## E2E Tests

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

E2E tests run Docker containers on a local bridge network with binaries built
from your working tree.

If you run inside a dev container, install `docker` CLI + buildx + compose in
that container so commands like `cargo test-e2e` and `docker compose` work.

## VM Tests

VM tests run intermesh across isolated local [Incus](https://linuxcontainers.org/incus/)
VMs. They run in CI, so most contributors never need a local Incus setup;
reach for them when you want guest-level network realism before pushing.

You only need this if you plan to run VM tests locally. The Nix shell includes
the `incus` CLI, but it does not install or configure the host Incus daemon.
Your host should be able to launch the Ubuntu 24.04 cloud VM image:

```bash
incus image info images:ubuntu/24.04/cloud --vm
incus launch images:ubuntu/24.04/cloud intermesh-incus-check --vm --ephemeral
incus delete --force intermesh-incus-check
```

Quick commands:
Intermesh is written in Rust and builds and tests on Linux.

```bash
cargo xtask vm-image # ensure the cached VM image exists, print its alias
cargo test-vm # run all VM tests; fails if Incus is unavailable
cargo test-vm test_name # run a specific test
cargo xtask clean-vm-images # drop cached local Intermesh VM images
cargo local # lint + build + unit tests + e2e tests
cargo all # local, plus perf and VM tests
```

`cargo all` attempts VM tests and skips them when Incus is unavailable.

## Local Mesh Demo

The repo ships a small local mesh demo in `sandbox/`:

```bash
# first run takes time
cd sandbox && docker compose up -d
```

See `sandbox/README.md` for what to try once it's up and running.

## Day-to-Day Workflow

A tight loop that works well:

1. `cargo test [filter]`
2. `cargo lint`
3. `cargo test-e2e [filter]`
4. `cargo local` before push

## Common Gotchas

- **Docker daemon not reachable:** start Docker and re-run `docker info`
- **Lint fails with `invalid byte sequence in US-ASCII`:** set
`LANG=C.UTF-8 LC_ALL=C.UTF-8`
- **First e2e run is slow:** expected; the e2e base image and build cache have
to warm up. Long silent stretches are normal, so let it finish
- **VM tests skipped:** expected without a local Incus setup
- **Using a Linux dev container on macOS/Windows:** set
`CARGO_TARGET_DIR` to a container-local path to avoid host/guest target dir
conflicts (for example `export CARGO_TARGET_DIR=/tmp/intermesh-target`)

Stuck on something platform-specific? File a GitHub issue:
<https://github.com/pcnofelt/intermesh/issues>

## Next Steps

1. Get `cargo local` passing
2. Run `cargo test-e2e` once to warm the environment
3. Bring up the `sandbox/` demo mesh
4. Pick a small issue and follow the day-to-day loop above
See [docs/development.md](docs/development.md) for environment setup, e2e and
VM test details, and the local mesh demo in `sandbox/`.
Loading
Loading