diff --git a/docs/proxmox-setup.md b/docs/proxmox-setup.md
new file mode 100644
index 0000000..974df78
--- /dev/null
+++ b/docs/proxmox-setup.md
@@ -0,0 +1,153 @@
+# Proxmox Setup for Terraform
+
+Configuration guide for the `bpg/proxmox` Terraform provider on Proxmox VE 9.1.
+
+> Related issue: [#1 - Proxmox 9.1 upgrade: Terraform API user disabled](https://gitea.arnodo.fr/Damien/iac-homelab/issues/1)
+
+## Overview
+
+Instead of using the `Administrator` role, we create a dedicated `TerraformRole` with minimal required privileges.
+
+## Required Privileges (Proxmox 9.1)
+
+| Category  | Privileges |
+|-----------|------------|
+| Datastore | `Allocate`, `AllocateSpace`, `AllocateTemplate`, `Audit` |
+| System    | `Audit`, `Console`, `Modify` |
+| VM        | `Allocate`, `Audit`, `Clone`, `Config.*`, `Console`, `Migrate`, `PowerMgmt`, `Snapshot`, `Snapshot.Rollback` |
+| Pool      | `Allocate`, `Audit` |
+| SDN       | `Use` |
+
+> ⚠️ `VM.Monitor` was deprecated in Proxmox 9 — do not include it.
+
+---
+
+## Option A: Web Interface
+
+### 1. Create Role
+
+**Datacenter → Permissions → Roles → Create**
+
+- **Name**: `TerraformRole`
+- **Privileges**: Select all from the table above
+
+### 2. Create User
+
+**Datacenter → Permissions → Users → Add**
+
+| Field | Value |
+|-------|-------|
+| User name | `terraform` |
+| Realm | `Proxmox VE authentication server` |
+| Password | *(set a strong password)* |
+| Enabled | ☑️ |
+| Expire | `never` |
+
+### 3. Create API Token
+
+**Datacenter → Permissions → API Tokens → Add**
+
+| Field | Value |
+|-------|-------|
+| User | `terraform@pve` |
+| Token ID | `terraform_token` |
+| Privilege Separation | ☐ *(unchecked)* |
+| Expire | `never` |
+
+> 📋 **Save the token secret** — it won't be shown again!
+
+### 4. Assign Permissions
+
+**Datacenter → Permissions → Add → User Permission**
+
+| Field | Value |
+|-------|-------|
+| Path | `/` |
+| User | `terraform@pve` |
+| Role | `TerraformRole` |
+| Propagate | ☑️ |
+
+---
+
+## Option B: CLI
+
+```bash
+# 1. Create role
+pveum role add TerraformRole -privs "Datastore.Allocate,Datastore.AllocateSpace,Datastore.AllocateTemplate,Datastore.Audit,Pool.Allocate,Pool.Audit,SDN.Use,Sys.Audit,Sys.Console,Sys.Modify,VM.Allocate,VM.Audit,VM.Clone,VM.Config.CDROM,VM.Config.Cloudinit,VM.Config.CPU,VM.Config.Disk,VM.Config.HWType,VM.Config.Memory,VM.Config.Network,VM.Config.Options,VM.Console,VM.Migrate,VM.PowerMgmt,VM.Snapshot,VM.Snapshot.Rollback"
+
+# 2. Create user
+pveum user add terraform@pve --comment "Terraform automation"
+
+# 3. Create API token (save the output!)
+pveum user token add terraform@pve terraform_token --privsep 0
+
+# 4. Assign permissions
+pveum acl modify / --user terraform@pve --role TerraformRole
+```
+
+---
+
+## SSH Access (Required)
+
+The `bpg/proxmox` provider uses SSH to upload cloud-init files.
+
+```bash
+# Create system user
+useradd -m -s /bin/bash terraform
+
+# Configure passwordless sudo
+echo 'terraform ALL=(ALL) NOPASSWD: ALL' > /etc/sudoers.d/terraform
+chmod 440 /etc/sudoers.d/terraform
+
+# Setup SSH key
+mkdir -p /home/terraform/.ssh
+echo "YOUR_PUBLIC_KEY" > /home/terraform/.ssh/authorized_keys
+chmod 700 /home/terraform/.ssh
+chmod 600 /home/terraform/.ssh/authorized_keys
+chown -R terraform:terraform /home/terraform/.ssh
+```
+
+---
+
+## Terraform Configuration
+
+```hcl
+provider "proxmox" {
+  endpoint  = "https://pve01.example.com:8006"
+  api_token = "terraform@pve!terraform_token=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+  insecure  = true
+  
+  ssh {
+    agent    = true
+    username = "terraform"
+  }
+}
+```
+
+Or use environment variables:
+
+```bash
+export PROXMOX_VE_ENDPOINT="https://pve01.example.com:8006"
+export PROXMOX_VE_API_TOKEN="terraform@pve!terraform_token=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+```
+
+---
+
+## Verification
+
+```bash
+# Test API token
+curl -k -H "Authorization: PVEAPIToken=terraform@pve!terraform_token=YOUR_SECRET" \
+  https://pve01.example.com:8006/api2/json/version
+
+# Test Terraform
+terraform init && terraform plan
+```
+
+---
+
+## References
+
+- [bpg/proxmox provider](https://github.com/bpg/terraform-provider-proxmox)
+- [Proxmox User Management](https://pve.proxmox.com/wiki/User_Management)
+- [Proxmox API](https://pve.proxmox.com/wiki/Proxmox_VE_API)