{"id":50509957,"url":"https://github.com/davdiv/compartinet","last_synced_at":"2026-06-02T19:03:59.576Z","repository":{"id":357462128,"uuid":"1237065809","full_name":"davdiv/CompartiNET","owner":"davdiv","description":"Experimental reactive network manager for Linux, written in TypeScript.","archived":false,"fork":false,"pushed_at":"2026-05-12T21:41:50.000Z","size":161,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-12T23:17:59.586Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/davdiv.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-12T20:59:12.000Z","updated_at":"2026-05-12T21:41:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/davdiv/CompartiNET","commit_stats":null,"previous_names":["davdiv/compartinet"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/davdiv/CompartiNET","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davdiv%2FCompartiNET","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davdiv%2FCompartiNET/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davdiv%2FCompartiNET/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davdiv%2FCompartiNET/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/davdiv","download_url":"https://codeload.github.com/davdiv/CompartiNET/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davdiv%2FCompartiNET/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33833280,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-02T19:03:58.479Z","updated_at":"2026-06-02T19:03:59.569Z","avatar_url":"https://github.com/davdiv.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CompartiNET\n\n[![codecov](https://codecov.io/gh/davdiv/compartinet/branch/main/graph/badge.svg)](https://codecov.io/gh/davdiv/compartinet)\n\nReactive 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.\n\n**This is very experimental, expect many bugs, it is clearly not yet ready for production use.**\n\n## Key Features\n\n- **Network namespaces** — create, delete, and move interfaces between namespaces\n- **Bridges** — with 802.1Q VLAN filtering, STP control, and per-port VLAN membership\n- **veth pairs** — virtual Ethernet links within or across namespaces\n- **WireGuard** — interface creation and full configuration (peers, keys, endpoints, keepalive)\n- **Hardware matching** — declare expected physical interfaces by PCI bus/device ID\n- **DHCP client** — automatic IPv4 lease acquisition with renewal and rebinding\n- **Wake-on-LAN** — send WoL magic packets via the `compartinet wol` command\n- **systemd integration** — `sd_notify` readiness, SIGHUP config reload, periodic state drift detection\n- **YAML/JSON configuration** — single file or a directory, validated against a JSON Schema\n\n## How It Works\n\nCompartiNET uses a **desired-state vs current-state reconciliation** pattern:\n\n1. **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.\n\n2. **Current state** is collected from the kernel by polling `iproute2` JSON output, `wg showconf`, `bridge vlan show`, `iw dev`...\n\n3. **Reconciliation** diffs the two models and produces a sequence of `ip`, `bridge` and `wg` commands to converge the current state toward the desired state.\n\n4. **Commands** are executed, and the cycle repeats every 30 seconds to catch drift.\n\n## Quick Start\n\n```bash\n# Install globally from npm\nnpm install -g compartinet\n\n# Check current state (network model)\ncompartinet state\n\n# Install the systemd service\nsudo compartinet install\n\n# Create a configuration based on the current state\ncompartinet state-config | sudo tee /etc/compartinet/config.d/network.yaml\n\n# Start the service\nsudo systemctl enable --now compartinet\n```\n\n## Configuration Example\n\n```yaml\n# /etc/compartinet/config.d/network.yaml :\n# yaml-language-server: $schema=./dist/config-schema.json\n- type: SetInterfaceUp\n  netns: \"\"\n  iface: lo\n  up: true\n\n- type: MatchHardware\n  netns: \"\"\n  iface: eth0\n  hardwareBus: pci\n  hardwareDevice: 0000:00:1f.6\n\n- type: SetInterfaceUp\n  netns: \"\"\n  iface: eth0\n  up: true\n\n- type: DhcpClient\n  netns: \"\"\n  iface: eth0\n  macAddress: 01:02:03:04:05:06\n```\n\nSee [sampleConfig.yaml](sampleConfig.yaml) for a complete annotated reference of all available features.\n\n## Installation\n\n### From npm (recommended)\n\n```bash\nnpm install -g compartinet\n```\n\nThe package bundles all dependencies. Requires Node.js.\n\n### From source\n\n```bash\ngit clone https://github.com/davdiv/compartinet.git\ncd compartinet\nnpm ci\nnpm run build:node\n# The built executables are in dist/\n```\n\n## Architecture\n\n```mermaid\nflowchart TD\n    config[\"Config (YAML/JSON)\"]\n    features[\"Feature handlers\"]\n    desired[\"Desired NetworkModel\"]\n    collect[\"collectState()\"]\n    current[\"Current NetworkModel\"]\n    reconciler[\"Reconciler\"]\n    actions[\"Actions\"]\n    commands[\"ip / bridge / wg commands\"]\n    kernel[\"Kernel state\"]\n\n    config --\u003e features --\u003e desired\n    desired --\u003e reconciler\n    collect --\u003e current --\u003e reconciler\n    reconciler --\u003e actions --\u003e commands --\u003e kernel\n```\n\n- **[src/common/](src/common/)** — platform-agnostic model, feature system, reconciler, DHCP protocol parsing\n- **[src/node/](src/node/)** — Linux state collection, command execution, CLI tools, systemd integration\n- **[tests/unit/](tests/unit/)** — pure-logic tests (reconciler, model generation, DHCP protocol)\n- **[tests/integration/](tests/integration/)** — end-to-end tests running real `ip`, `wg`, and `bridge` commands\n\n## Development\n\n**Prerequisites:** Node.js, Docker (for integration tests)\n\n```bash\nnpm ci\n\n# Full check (type-check, build, both unit and integration tests, lint and format check)\nnpm run ci\n\n# Individual commands:\nnpm run type-check       # TypeScript type checking\nnpm run build:node       # Build the dist/ output\nnpm run test:unit        # Run unit tests\nnpm run test:integration # Run integration tests (in Docker container)\nnpm run lint             # ESLint\nnpm run format:check     # Check formatting\nnpm run format:fix       # Fix formatting\n```\n\nIntegration 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:\n\n```bash\nnpm run sandbox\n```\n\n## License\n\n[MIT](LICENSE.md) — Copyright 2026 DivDE\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavdiv%2Fcompartinet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavdiv%2Fcompartinet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavdiv%2Fcompartinet/lists"}