Network manager

.air.toml

@@ -5,7 +5,7 @@ tmp_dir = "tmp"
 [build]
   args_bin = []
   bin = "./tmp/main"
-  cmd = "go build -tags containers_image_openpgp -o ./tmp/main ./cmd/api"
+  cmd = "go build -tags containers_image_openpgp -o ./tmp/main ./cmd/api && sudo setcap cap_net_admin,cap_net_bind_service=+eip ./tmp/main"
   delay = 1000
   exclude_dir = ["assets", "tmp", "vendor", "testdata", "bin", "scripts", "data", "kernel"]
   exclude_file = []
@@ -20,6 +20,7 @@ tmp_dir = "tmp"
   log = "build-errors.log"
   poll = false
   poll_interval = 0
+  post_cmd = []
   rerun = false
   rerun_delay = 500
   send_interrupt = false

.github/workflows/stainless-sdks.yml

@@ -0,0 +1,65 @@
+name: Stainless SDK preview on PRs
+
+on:
+  pull_request:
+    types:
+      - opened
+      - synchronize
+      - reopened
+      - closed
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+env:
+  STAINLESS_ORG: ${{ vars.STAINLESS_ORG }}
+  STAINLESS_PROJECT: ${{ vars.STAINLESS_PROJECT }}
+  OAS_PATH: openapi.yaml
+  CONFIG_PATH: stainless.yaml
+
+jobs:
+  preview:
+    if: github.event.action != 'closed'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - name: Run preview builds
+        uses: stainless-api/upload-openapi-spec-action/preview@v1
+        with:
+          stainless_api_key: ${{ secrets.STAINLESS_API_KEY }}
+          org: ${{ env.STAINLESS_ORG }}
+          project: ${{ env.STAINLESS_PROJECT }}
+          oas_path: ${{ env.OAS_PATH }}
+          config_path: ${{ env.CONFIG_PATH }}
+          make_comment: true
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+  merge:
+    if: github.event.action == 'closed' && github.event.pull_request.merged == true
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - name: Run merge build
+        uses: stainless-api/upload-openapi-spec-action/merge@v1
+        with:
+          stainless_api_key: ${{ secrets.STAINLESS_API_KEY }}
+          org: ${{ env.STAINLESS_ORG }}
+          project: ${{ env.STAINLESS_PROJECT }}
+          oas_path: ${{ env.OAS_PATH }}
+          make_comment: true
+          github_token: ${{ secrets.GITHUB_TOKEN }}

Makefile

@@ -115,8 +115,42 @@ dev: $(AIR)
 	$(AIR) -c .air.toml
 
 # Run tests
+# Compile test binaries and grant network capabilities (runs as user, not root)
+# Usage: make test                              - runs all tests
+#        make test TEST=TestCreateInstanceWithNetwork  - runs specific test
 test: ensure-ch-binaries lib/system/exec_agent/exec-agent
-	go test -tags containers_image_openpgp -v -timeout 30s ./...
+	@echo "Building test binaries..."
+	@mkdir -p $(BIN_DIR)/tests
+	@for pkg in $$(go list -tags containers_image_openpgp ./...); do \
+		pkg_name=$$(basename $$pkg); \
+		go test -c -tags containers_image_openpgp -o $(BIN_DIR)/tests/$$pkg_name.test $$pkg 2>/dev/null || true; \
+	done
+	@echo "Granting capabilities to test binaries..."
+	@for test in $(BIN_DIR)/tests/*.test; do \
+		if [ -f "$$test" ]; then \
+			sudo setcap 'cap_net_admin,cap_net_bind_service=+eip' $$test 2>/dev/null || true; \
+		fi; \
+	done
+	@echo "Running tests as current user with capabilities..."
+	@if [ -n "$(TEST)" ]; then \
+		echo "Running specific test: $(TEST)"; \
+		for test in $(BIN_DIR)/tests/*.test; do \
+			if [ -f "$$test" ]; then \
+				echo ""; \
+				echo "Checking $$(basename $$test) for $(TEST)..."; \
+				$$test -test.run=$(TEST) -test.v -test.timeout=60s 2>&1 | grep -q "PASS\|FAIL" && \
+				$$test -test.run=$(TEST) -test.v -test.timeout=60s || true; \
+			fi; \
+		done; \
+	else \
+		for test in $(BIN_DIR)/tests/*.test; do \
+			if [ -f "$$test" ]; then \
+				echo ""; \
+				echo "Running $$(basename $$test)..."; \
+				$$test -test.v -test.parallel=10 -test.timeout=60s || exit 1; \
+			fi; \
+		done; \
+	fi
 
 # Generate JWT token for testing
 # Usage: make gen-jwt [USER_ID=test-user]
@@ -131,4 +165,3 @@ clean:
 	rm -f lib/exec/exec.pb.go
 	rm -f lib/exec/exec_grpc.pb.go
 	rm -f lib/system/exec_agent/exec-agent
-

README.md

@@ -8,10 +8,17 @@ Run containerized workloads in VMs, powered by [Cloud Hypervisor](https://github
 
 ### Prerequisites
 
-**Go 1.25.4+**, **KVM**, **erofs-utils**
+**Go 1.25.4+**, **KVM**, **erofs-utils**, **dnsmasq**
 
 ```bash
+# Verify prerequisites
 mkfs.erofs --version
+dnsmasq --version
+```
+
+**Install on Debian/Ubuntu:**
+```bash
+sudo apt-get install erofs-utils dnsmasq
 ```
 
 **KVM Access:** User must be in `kvm` group for VM access:
@@ -20,13 +27,100 @@ sudo usermod -aG kvm $USER
 # Log out and back in, or use: newgrp kvm
 ```
 
+**Network Capabilities:** 
+
+Before running or testing Hypeman, ensure IPv4 forwarding is enabled:
+
+```bash
+# Enable IPv4 forwarding (temporary - until reboot)
+sudo sysctl -w net.ipv4.ip_forward=1
+
+# Enable IPv4 forwarding (persistent across reboots)
+echo 'net.ipv4.ip_forward=1' | sudo tee -a /etc/sysctl.conf
+sudo sysctl -p
+```
+
+**Why:** Required for routing traffic between VM network and external network.
+
+The hypeman binary needs network administration capabilities to create bridges and TAP devices:
+```bash
+# After building, grant network capabilities
+sudo setcap 'cap_net_admin,cap_net_bind_service=+eip' /path/to/hypeman
+
+# For development builds
+sudo setcap 'cap_net_admin,cap_net_bind_service=+eip' ./bin/hypeman
+
+# Verify capabilities
+getcap ./bin/hypeman
+```
+
+**Note:** The `i` (inheritable) flag allows child processes spawned by hypeman (like `ip` and `iptables` commands) to inherit capabilities via the ambient capability set.
+
+**Note:** These capabilities must be reapplied after each rebuild. For production deployments, set capabilities on the installed binary. For local testing, this is handled automatically in `make test`.
+
 ### Configuration
 
 #### Environment variables
 
+Hypeman can be configured using the following environment variables:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PORT` | HTTP server port | `8080` |
+| `DATA_DIR` | Directory for storing VM images, volumes, and other data | `/var/lib/hypeman` |
+| `BRIDGE_NAME` | Name of the network bridge for VM networking | `vmbr0` |
+| `SUBNET_CIDR` | CIDR notation for the VM network subnet (gateway derived automatically) | `10.100.0.0/16` |
+| `UPLINK_INTERFACE` | Host network interface to use for VM internet access | _(auto-detect)_ |
+| `JWT_SECRET` | Secret key for JWT authentication (required for production) | _(empty)_ |
+| `DNS_SERVER` | DNS server IP address for VMs | `1.1.1.1` |
+| `MAX_CONCURRENT_BUILDS` | Maximum number of concurrent image builds | `1` |
+| `MAX_OVERLAY_SIZE` | Maximum size for overlay filesystem | `100GB` |
+
+**Important: Subnet Configuration**
+
+The default subnet `10.100.0.0/16` is chosen to avoid common conflicts. Hypeman will detect conflicts with existing routes on startup and fail with guidance.
+
+If you need a different subnet, set `SUBNET_CIDR` in your environment. The gateway is automatically derived as the first IP in the subnet (e.g., `10.100.0.0/16` → `10.100.0.1`).
+
+**Alternative subnets if needed:**
+- `172.30.0.0/16` - Private range between common Docker (172.17.x.x) and AWS (172.31.x.x) ranges
+- `10.200.0.0/16` - Another private range option
+
+**Example:**
+```bash
+# In your .env file
+SUBNET_CIDR=172.30.0.0/16
+```
+
+**Finding the uplink interface (`UPLINK_INTERFACE`)**
+
+`UPLINK_INTERFACE` tells Hypeman which host interface to use for routing VM traffic to the outside world (for iptables MASQUERADE rules). On many hosts this is `eth0`, but laptops and more complex setups often use Wi‑Fi or other names.
+
+**Quick way to discover it:**
+```bash
+# Ask the kernel which interface is used to reach the internet
+ip route get 1.1.1.1
+```
+Look for the `dev` field in the output, for example:
+```text
+1.1.1.1 via 192.168.12.1 dev wlp2s0 src 192.168.12.98
+```
+In this case, `wlp2s0` is the uplink interface, so you would set:
+```bash
+UPLINK_INTERFACE=wlp2s0
+```
+
+You can also inspect all routes:
+```bash
+ip route show
+```
+Pick the interface used by the default route (usually the line starting with `default`). Avoid using local bridges like `docker0`, `br-...`, `virbr0`, or `vmbr0` as the uplink; those are typically internal virtual networks, not your actual internet-facing interface.
+
+**Setup:**
+
 ```bash
 cp .env.example .env
-# Edit .env and set JWT_SECRET
+# Edit .env and set JWT_SECRET and other configuration values
 ```
 
 #### Data directory
@@ -54,29 +148,27 @@ make build
 ```
 ### Running the Server
 
-1. Copy the example environment file and modify the values:
-```bash
-cp .env.example .env
-# Edit .env and set JWT_SECRET and other configuration values
-```
-
-2. Generate a JWT token for testing (optional):
+1. Generate a JWT token for testing (optional):
 ```bash
 make gen-jwt
 ```
 
-3. Start the server with hot-reload for development:
+2. Start the server with hot-reload for development:
 ```bash
 make dev
 ```
 The server will start on port 8080 (configurable via `PORT` environment variable).
 
 ### Testing
 
+Network tests require elevated permissions to create bridges and TAP devices.
+
 ```bash
 make test
 ```
 
+The test command compiles test binaries, grants capabilities via `sudo setcap`, then runs tests as the current user (not root). You may be prompted for your sudo password during the capability grant step.
+
 ### Code Generation
 
 After modifying `openapi.yaml`, regenerate the Go code:

cmd/api/api/api.go

@@ -4,6 +4,7 @@ import (
 	"github.com/onkernel/hypeman/cmd/api/config"
 	"github.com/onkernel/hypeman/lib/images"
 	"github.com/onkernel/hypeman/lib/instances"
+	"github.com/onkernel/hypeman/lib/network"
 	"github.com/onkernel/hypeman/lib/oapi"
 	"github.com/onkernel/hypeman/lib/volumes"
 )
@@ -14,6 +15,7 @@ type ApiService struct {
 	ImageManager    images.Manager
 	InstanceManager instances.Manager
 	VolumeManager   volumes.Manager
+	NetworkManager  network.Manager
 }
 
 var _ oapi.StrictServerInterface = (*ApiService)(nil)
@@ -24,12 +26,14 @@ func New(
 	imageManager images.Manager,
 	instanceManager instances.Manager,
 	volumeManager volumes.Manager,
+	networkManager network.Manager,
 ) *ApiService {
 	return &ApiService{
 		Config:          config,
 		ImageManager:    imageManager,
 		InstanceManager: instanceManager,
 		VolumeManager:   volumeManager,
+		NetworkManager:  networkManager,
 	}
 }
 

cmd/api/api/api_test.go

@@ -10,6 +10,7 @@ import (
 	"github.com/onkernel/hypeman/cmd/api/config"
 	"github.com/onkernel/hypeman/lib/images"
 	"github.com/onkernel/hypeman/lib/instances"
+	"github.com/onkernel/hypeman/lib/network"
 	"github.com/onkernel/hypeman/lib/paths"
 	"github.com/onkernel/hypeman/lib/system"
 	"github.com/onkernel/hypeman/lib/volumes"
@@ -28,8 +29,9 @@ func newTestService(t *testing.T) *ApiService {
 	}
 
 	systemMgr := system.NewManager(p)
+	networkMgr := network.NewManager(p, cfg)
 	maxOverlaySize := int64(100 * 1024 * 1024 * 1024) // 100GB for tests
-	instanceMgr := instances.NewManager(p, imageMgr, systemMgr, maxOverlaySize)
+	instanceMgr := instances.NewManager(p, imageMgr, systemMgr, networkMgr, maxOverlaySize)
 	volumeMgr := volumes.NewManager(p)
 
 	// Register cleanup for orphaned Cloud Hypervisor processes

cmd/api/api/exec_test.go

@@ -76,10 +76,17 @@ func TestExecInstanceNonTTY(t *testing.T) {
 
 	// Create instance
 	t.Log("Creating instance...")
+	networkDisabled := false
 	instResp, err := svc.CreateInstance(ctx(), oapi.CreateInstanceRequestObject{
 		Body: &oapi.CreateInstanceRequest{
 			Name:  "exec-test",
 			Image: "docker.io/library/nginx:alpine",
+			Network: &struct {
+				Enabled *bool   `json:"enabled,omitempty"`
+				Name    *string `json:"name,omitempty"`
+			}{
+				Enabled: &networkDisabled,
+			},
 		},
 	})
 	require.NoError(t, err)