Getting started

vxedge is an all-software research platform for mapping 5G network slices onto zonal & central SDV (software-defined vehicle) E/E architectures: a virtual edge gateway (vxgateway), QEMU/KVM virtual ECUs, containerized AD compute, and a Rust control plane (vxedged) driven entirely by YAML manifests. Read ARCHITECTURE.md for the full picture; this page gets you from zero to a measured experiment; day-to-day usage lives in USER-GUIDE.md.

Pre-release (0.x). The manifest schema and vxAPI may change between minor versions (VERSIONING.md); published results are frozen and do not change.

1. Prerequisites

Verified versions as of 2026-07:

Later phases additionally need QEMU/KVM + libvirt, Open vSwitch, and an NVIDIA GPU (CARLA/Autoware/Alpamayo workloads) — none of that is required to build and run the control plane today.

2. Workspace layout

vxedge is a meta-workspace of independent git repos, cloned side by side (the parent folder is not a git repo):

mkdir vxedge && cd vxedge
for r in docs vxedge vxparts vxota vxagents vxtelemetry vxperiments vxmodels; do
  gh repo clone vxedge/$r
done

Every repo has an AGENTS.md (scope + rules) and TASKS.md (phased work items); docs/ROADMAP.md is the program-level board with the cross-repo critical path.

3. Build everything

for r in vxedge vxagents vxtelemetry; do (cd $r && cargo build --workspace); done

Quick unprivileged smoke (daemon + CLI over a Unix socket):

cd vxedge
./target/debug/vxedged --listen unix:///tmp/vxedge.sock --runtime-dir /tmp/vxrt &
./target/debug/vxedge --endpoint unix:///tmp/vxedge.sock status
# gateway vxgateway: state=1 detail=no gateway provisioned
./target/debug/vxedge --help          # full command tree

Real provisioning (up, zone up) needs CAP_NET_ADMIN — run vxedged under sudo, or sudo setcap cap_net_admin+ep target/debug/vxedged. Without it, up validates the manifest and then fails with an actionable message (by design).

4. Run your first experiment (exp-001)

The flagship walkthrough: a full slice-isolation measurement, one command per step.

cd vxperiments/experiments/exp-001-ws
sudo -E env "PATH=$PATH" ./scripts/run.sh --quick                              # ~1 min pipeline validation
python3 ../../notebooks/analyze_exp001.py ../../results/exp-001-quick          # table + H1 verdict

After pulling new commits, rebuild all three binaries before a run (cargo build --workspace in vxedge, vxagents and vxtelemetry, as your own user, not root). The runner refuses to measure with a binary older than its source and tells you the exact command, including a touch of the rebuilt binaries.

Zone images are pulled from ghcr.io/vxedge/parts/.... While those packages are private, run sudo env "PATH=$PATH" oras login ghcr.io once (the daemon runs as root); the exp-001 runner does not need it.

Results land in vxperiments/results/. Quick runs write to results/exp-001-quick/ (disposable); the frozen campaign owns results/exp-001/, and reruns use --repro (date-suffixed dir) — a dir holding a frozen campaign's archives is never overwritten in place.

The --quick numbers are pipeline validation only (marked NOT reportable). The full campaign is ./scripts/run.sh --repro (it never overwrites the frozen results/exp-001/): ~35 minutes, 5 repetitions x 5 load levels, 60k samples per point — keep the machine otherwise idle and prefer the performance CPU governor. Reference result and methodology: RESULTS.md and the experiment-methodology skill.

5. Zones and VM guest bundles

Container-backed zones work out of the box (vxedge zone up --vxid … after up). The VM backends (qemu-microvm, libvirt) boot a guest bundle built once per host:

sudo chmod 644 /boot/vmlinuz-$(uname -r)        # Ubuntu ships the kernel root-only
cd vxparts && ./parts/zone/linux/stack/probe-bundle/build.sh   # -> ./bundle + digests

See USER-GUIDE.md §3c for wiring a bundle into a manifest.

6. Poke the API directly

The contract lives in vxedge/proto/vxedge/v1/ (package vxedge.v1). Any gRPC tool works; with grpcurl, from the workspace root:

grpcurl -unix -plaintext -import-path vxedge/proto \
  -proto vxedge/v1/lifecycle.proto \
  /tmp/vxedge.sock vxedge.v1.GatewayService/Status

Proto hygiene: buf lint in the vxedge repo (CI enforces it).

7. Manifests — the only input

Everything the platform does is declared in YAML manifests (schema: ARCHITECTURE.md §6; worked example: §16). The parser is strict — unknown fields are errors — and semantic validation covers slice references, vxid uniqueness, and slice-mode consistency. Experiment manifests live in vxperiments/experiments/, vehicle manifests in vxperiments/vehicles/.

8. Troubleshooting

• protoc not found during cargo build — install protoc (table above); the proto codegen runs inside the build via crates/vxedge-api/build.rs.
• cannot reach vxedged at unix:///run/vxedge.sock — the default socket path needs root-writable /run; for development pass a user-writable path to both sides (--listen/--endpoint unix:///tmp/vxedge.sock) or set VXEDGE_ENDPOINT.
• A verb prints "not wired to the daemon yet (scaffold)" — truthfully unimplemented; USER-GUIDE.md §2 lists each verb's state. Check it before assuming a bug.
• An experiment runner refuses with "older than source file …" — the staleness gate: rebuild as your user (cargo build --workspace && touch <binary>; cargo doesn't relink unchanged binaries, so mtime alone can look stale).
• insufficient privileges … CAP_NET_ADMIN — run the daemon under sudo or setcap it (see §3); provisioning refuses to half-apply without privileges.
• Bundle build: "vmlinuz not readable" — Ubuntu ships kernels 0600; sudo chmod 644 /boot/vmlinuz-$(uname -r).

9. Where to contribute next

Check docs/ROADMAP.md (program board) and RESULTS.md (what's done vs open). The phase-1 gate has passed (2026-07-13): H1, H3, and H4 all hold with second-campaign reproducibility checks, and v0.1.0 is tagged across the delivering repos. Current open fronts, in order:

1. vxedge — Open5GS/UERANSIM driver (mode: s-nssai) + URSP-style slice_policy → the H2 numbers (phase-2 gate)
2. vxparts (parts/hpc/) — Autoware/ROS2 + CARLA + carla-ros-bridge, closed loop
3. vxparts (parts/zone/) — QNX SDP 8 / AAOS images + real-RTOS guest bundles (Zephyr/FreeRTOS) beyond the linux-probe bundle
4. Track M — M0/M1: vxmodels repo + the retroactive H1–H4 SysML v2 traceability model over the frozen archives (docs/ROADMAP.md track M; zero new experiments)
5. Release/artifact pipeline — GHCR images with digests, cargo-dist binaries

Conventions to know before your first PR: manifests are the sole source of truth; no orchestration logic in any frontend; every image is digest-tagged; commits without a Co-Authored-By trailer. Details per repo in its AGENTS.md.

@misc{djaafrivxedgegettingstarted2026,
  author = {Djaafri, Fouzi},
  title  = {vxedge: Getting started},
  year   = {2026},
  url    = {https://vxedge.dev/docs/GETTING-STARTED.html},
  note   = {Documentation, version 0.1.0, source commit dc27de9}
}