https://github.com/davdiv/compartinet
Experimental reactive network manager for Linux, written in TypeScript.
https://github.com/davdiv/compartinet
Last synced: 11 days ago
JSON representation
Experimental reactive network manager for Linux, written in TypeScript.
- Host: GitHub
- URL: https://github.com/davdiv/compartinet
- Owner: davdiv
- License: mit
- Created: 2026-05-12T20:59:12.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-05-12T21:41:50.000Z (about 1 month ago)
- Last Synced: 2026-05-12T23:17:59.586Z (about 1 month ago)
- Language: TypeScript
- Size: 157 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# CompartiNET
[](https://codecov.io/gh/davdiv/compartinet)
Reactive network manager for Linux, written in TypeScript. Manages network namespaces, bridges, veth pairs, WireGuard interfaces, routes, addresses, VLANs, and DHCP — all driven by a declarative YAML or JSON configuration.
**This is very experimental, expect many bugs, it is clearly not yet ready for production use.**
## Key Features
- **Network namespaces** — create, delete, and move interfaces between namespaces
- **Bridges** — with 802.1Q VLAN filtering, STP control, and per-port VLAN membership
- **veth pairs** — virtual Ethernet links within or across namespaces
- **WireGuard** — interface creation and full configuration (peers, keys, endpoints, keepalive)
- **Hardware matching** — declare expected physical interfaces by PCI bus/device ID
- **DHCP client** — automatic IPv4 lease acquisition with renewal and rebinding
- **Wake-on-LAN** — send WoL magic packets via the `compartinet wol` command
- **systemd integration** — `sd_notify` readiness, SIGHUP config reload, periodic state drift detection
- **YAML/JSON configuration** — single file or a directory, validated against a JSON Schema
## How It Works
CompartiNET uses a **desired-state vs current-state reconciliation** pattern:
1. **Desired state** is built from your declarative configuration (YAML/JSON). Feature handlers (netns, bridge, veth, WireGuard, DHCP, etc.) expand the config into a `NetworkModel` — a structured representation of namespaces, interfaces, addresses, and routes.
2. **Current state** is collected from the kernel by polling `iproute2` JSON output, `wg showconf`, `bridge vlan show`, `iw dev`...
3. **Reconciliation** diffs the two models and produces a sequence of `ip`, `bridge` and `wg` commands to converge the current state toward the desired state.
4. **Commands** are executed, and the cycle repeats every 30 seconds to catch drift.
## Quick Start
```bash
# Install globally from npm
npm install -g compartinet
# Check current state (network model)
compartinet state
# Install the systemd service
sudo compartinet install
# Create a configuration based on the current state
compartinet state-config | sudo tee /etc/compartinet/config.d/network.yaml
# Start the service
sudo systemctl enable --now compartinet
```
## Configuration Example
```yaml
# /etc/compartinet/config.d/network.yaml :
# yaml-language-server: $schema=./dist/config-schema.json
- type: SetInterfaceUp
netns: ""
iface: lo
up: true
- type: MatchHardware
netns: ""
iface: eth0
hardwareBus: pci
hardwareDevice: 0000:00:1f.6
- type: SetInterfaceUp
netns: ""
iface: eth0
up: true
- type: DhcpClient
netns: ""
iface: eth0
macAddress: 01:02:03:04:05:06
```
See [sampleConfig.yaml](sampleConfig.yaml) for a complete annotated reference of all available features.
## Installation
### From npm (recommended)
```bash
npm install -g compartinet
```
The package bundles all dependencies. Requires Node.js.
### From source
```bash
git clone https://github.com/davdiv/compartinet.git
cd compartinet
npm ci
npm run build:node
# The built executables are in dist/
```
## Architecture
```mermaid
flowchart TD
config["Config (YAML/JSON)"]
features["Feature handlers"]
desired["Desired NetworkModel"]
collect["collectState()"]
current["Current NetworkModel"]
reconciler["Reconciler"]
actions["Actions"]
commands["ip / bridge / wg commands"]
kernel["Kernel state"]
config --> features --> desired
desired --> reconciler
collect --> current --> reconciler
reconciler --> actions --> commands --> kernel
```
- **[src/common/](src/common/)** — platform-agnostic model, feature system, reconciler, DHCP protocol parsing
- **[src/node/](src/node/)** — Linux state collection, command execution, CLI tools, systemd integration
- **[tests/unit/](tests/unit/)** — pure-logic tests (reconciler, model generation, DHCP protocol)
- **[tests/integration/](tests/integration/)** — end-to-end tests running real `ip`, `wg`, and `bridge` commands
## Development
**Prerequisites:** Node.js, Docker (for integration tests)
```bash
npm ci
# Full check (type-check, build, both unit and integration tests, lint and format check)
npm run ci
# Individual commands:
npm run type-check # TypeScript type checking
npm run build:node # Build the dist/ output
npm run test:unit # Run unit tests
npm run test:integration # Run integration tests (in Docker container)
npm run lint # ESLint
npm run format:check # Check formatting
npm run format:fix # Fix formatting
```
Integration tests run inside a privileged Docker container (`--cap-add=NET_ADMIN --cap-add=SYS_ADMIN`) built from [tests/container/Dockerfile](tests/container/Dockerfile). You can also open an interactive shell in the test container:
```bash
npm run sandbox
```
## License
[MIT](LICENSE.md) — Copyright 2026 DivDE