diff --git a/netbox/README.md b/netbox/README.md
new file mode 100644
index 0000000..0df2d30
--- /dev/null
+++ b/netbox/README.md
@@ -0,0 +1,86 @@
+# NetBox Provisioning for EVPN-VXLAN Fabric
+
+This directory contains scripts to populate NetBox with the fabric topology defined in this repository.
+
+## Prerequisites
+
+- NetBox 4.4.x running and accessible
+- NetBox BGP Plugin v0.17.x installed (optional, for BGP sessions)
+- Python 3.9+
+- API token with write permissions
+
+## Installation
+
+```bash
+cd netbox
+pip install -r requirements.txt
+```
+
+## Usage
+
+```bash
+export NETBOX_URL="http://netbox.example.com"
+export NETBOX_TOKEN="your-api-token"
+python provision_fabric.py
+```
+
+## What Gets Created
+
+### Custom Fields
+
+| Object Type | Field | Description |
+|-------------|-------|-------------|
+| Device | `asn` | BGP ASN |
+| Device | `mlag_domain_id` | MLAG domain identifier |
+| Device | `mlag_peer_address` | MLAG peer IP |
+| Device | `mlag_local_address` | MLAG local IP |
+| Device | `mlag_virtual_mac` | Shared virtual MAC |
+| Interface | `mlag_peer_link` | Marks peer-link interfaces |
+| Interface | `mlag_id` | MLAG ID for host LAGs |
+| VRF | `l3vni` | L3 VNI for EVPN |
+| VRF | `vrf_vlan` | VLAN for L3 VNI SVI |
+| IP Address | `virtual_ip` | Anycast/virtual IP flag |
+
+### Organization
+
+- **Site**: evpn-lab
+- **Manufacturer**: Arista
+- **Device Types**: cEOS-lab, Linux Server
+- **Device Roles**: Spine, Leaf, Server
+
+### Devices
+
+| Device | Role | ASN | MLAG Domain |
+|--------|------|-----|-------------|
+| spine1, spine2 | Spine | 65000 | - |
+| leaf1, leaf2 | Leaf | 65001 | MLAG1 |
+| leaf3, leaf4 | Leaf | 65002 | MLAG2 |
+| leaf5, leaf6 | Leaf | 65003 | MLAG3 |
+| leaf7, leaf8 | Leaf | 65004 | MLAG4 |
+| host1-4 | Server | - | - |
+
+### Cabling
+
+- Spine1/2 Ethernet1-8 → Leaf1-8 Ethernet11/12
+- MLAG peer-links: Leaf pairs via Ethernet10
+- Host dual-homing: eth1/eth2 to MLAG pairs
+
+### IP Addressing
+
+| Purpose | Prefix |
+|---------|--------|
+| Spine1-Leaf P2P | 10.0.1.0/24 |
+| Spine2-Leaf P2P | 10.0.2.0/24 |
+| MLAG iBGP P2P | 10.0.3.0/24 |
+| MLAG Peer VLAN | 10.0.199.0/24 |
+| Loopback0 (Router-ID) | 10.0.250.0/24 |
+| Loopback1 (VTEP) | 10.0.255.0/24 |
+
+## Idempotency
+
+The script is idempotent - running it multiple times will not create duplicate objects. Existing objects are detected and skipped.
+
+## Reference
+
+- [NetBox Data Model Documentation](https://gitea.arnodo.fr/Damien/fabric-orchestrator/src/branch/main/docs/netbox-data-model.md)
+- [ContainerLab Topology](../evpn-lab.clab.yml)