diff --git a/README.md b/README.md
index 54f22be..6c5e855 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,31 @@
-# awx
\ No newline at end of file
+# awx
+
+AWX Local Setup for Minikube
+
+This folder provides an automated script and instructions to deploy the awx-operator and a single-node AWX instance locally using Minikube + kubectl.
+
+Files
+- `setup_awx_local.sh` — idempotent installer script. Run from inside the `awx-operator` repo (it expects the repo files like `config/` and `awx.yml` to be present in the parent folder).
+- `cleanup.sh` — stops port-forward and optionally deletes the `awx` namespace and CRs.
+- `README_GIT_PUSH.md` — instructions to create a new remote repo and push this directory to your git host.
+
+Quickstart
+1. From the `awx-operator` repo root, copy or open this folder:
+
+```bash
+cd /home/alex/awx-operator
+ls -la awx-local-setup
+```
+
+2. Make scripts executable and run the installer:
+
+```bash
+chmod +x awx-local-setup/setup_awx_local.sh awx-local-setup/cleanup.sh
+./awx-local-setup/setup_awx_local.sh --port 8082
+```
+
+3. Open AWX in your browser at the host IP and port printed by the script, or use the NodePort on the Minikube VM.
+
+Notes
+- The script is intended for local development/testing only. For production, use official operator docs.
+- The script tries to be idempotent and safe. It does not delete CRDs or secrets automatically.
diff --git a/README_GIT_PUSH.md b/README_GIT_PUSH.md
new file mode 100644
index 0000000..98a39f3
--- /dev/null
+++ b/README_GIT_PUSH.md
@@ -0,0 +1,21 @@
+Pushing this directory to your git host
+
+To create a new remote repo and push this local setup, run these commands from the host that owns `/home/alex/awx-operator/awx-local-setup`:
+
+```bash
+cd /home/alex/awx-operator/awx-local-setup
+# initialize a local repo
+git init
+git add .
+git commit -m "Add AWX local setup scripts and README"
+
+# create a remote repository on your git host (GitHub/GitLab). Example with GitHub CLI:
+# gh repo create my-org/awx-local-setup --private --source=. --remote=origin
+
+# or add a remote manually and push
+git remote add origin git@github.com:YOURUSER/awx-local-setup.git
+git branch -M main
+git push -u origin main
+```
+
+If you'd like I can initialize the local git repo and commit here; pushing requires remote credentials or a remote URL.
diff --git a/cleanup.sh b/cleanup.sh
new file mode 100755
index 0000000..18494fe
--- /dev/null
+++ b/cleanup.sh
@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# cleanup.sh
+# Stops port-forward and optionally deletes the awx namespace and CRs.
+
+PORTF_PID_FILE=/tmp/awx-pf.pid
+NAMESPACE=awx
+
+if [ -f "$PORTF_PID_FILE" ]; then
+  PID=$(cat $PORTF_PID_FILE)
+  echo "Killing port-forward PID $PID"
+  kill $PID 2>/dev/null || true
+  rm -f $PORTF_PID_FILE
+  rm -f /tmp/awx-port-forward.log || true
+else
+  echo "No port-forward PID file present"
+fi
+
+read -p "Delete the AWX namespace and all AWX resources? [y/N]: " yn
+if [[ "$yn" =~ ^[Yy]$ ]]; then
+  echo "Deleting namespace $NAMESPACE"
+  kubectl delete ns $NAMESPACE --wait=true || true
+  echo "Note: CRDs are not deleted automatically. Remove them manually if desired."
+fi
+
+echo "Cleanup complete."
diff --git a/setup_awx_local.sh b/setup_awx_local.sh
new file mode 100755
index 0000000..4a40cae
--- /dev/null
+++ b/setup_awx_local.sh
@@ -0,0 +1,136 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# setup_awx_local.sh
+# Minimal, idempotent script to deploy awx-operator and an AWX instance on Minikube.
+# Usage: ./setup_awx_local.sh [--port PORT] [--nodeport NODEPORT] [--repo-root PATH]
+
+PORT=8082
+NODEPORT=30081
+AWX_NAMESPACE=awx
+REPO_ROOT="$(pwd)"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --port) PORT="$2"; shift 2 ;;
+    --nodeport) NODEPORT="$2"; shift 2 ;;
+    --namespace) AWX_NAMESPACE="$2"; shift 2 ;;
+    --repo-root) REPO_ROOT="$2"; shift 2 ;;
+    -h|--help) echo "Usage: $0 [--port PORT] [--nodeport NODEPORT] [--namespace NAMESPACE] [--repo-root PATH]"; exit 0 ;;
+    *) echo "Unknown arg: $1"; exit 1 ;;
+  esac
+done
+
+echo "Running AWX local setup"
+echo "Port-forward local port: ${PORT} -> service:80 (bind 0.0.0.0)"
+echo "AWX NodePort to request: ${NODEPORT}"
+
+# prerequisites
+for cmd in kubectl minikube curl ss ip; do
+  if ! command -v $cmd >/dev/null 2>&1; then
+    echo "Missing prerequisite: $cmd"; exit 1
+  fi
+done
+
+# start minikube if needed
+if ! kubectl get nodes >/dev/null 2>&1; then
+  echo "No Kubernetes cluster detected. Starting minikube..."
+  minikube start
+fi
+
+# ensure namespace
+kubectl get ns ${AWX_NAMESPACE} >/dev/null 2>&1 || kubectl create ns ${AWX_NAMESPACE}
+
+# apply CRDs and operator manager from the awx-operator repo
+if [ -d "${REPO_ROOT}/config/crd" ]; then
+  kubectl apply -k "${REPO_ROOT}/config/crd"
+fi
+if [ -d "${REPO_ROOT}/config/rbac" ]; then
+  kubectl apply -k "${REPO_ROOT}/config/rbac"
+fi
+if [ -d "${REPO_ROOT}/config/manager" ]; then
+  kubectl apply -k "${REPO_ROOT}/config/manager" -n ${AWX_NAMESPACE} || true
+fi
+
+# create leader-election RBAC if missing
+cat <<'EOF' | kubectl apply -n ${AWX_NAMESPACE} -f -
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: awx-operator-leader-election
+rules:
+- apiGroups: ["coordination.k8s.io"]
+  resources: ["leases"]
+  verbs: ["get","create","update","patch","delete","watch","list"]
+EOF
+
+kubectl get rolebinding awx-operator-leader-election -n ${AWX_NAMESPACE} >/dev/null 2>&1 || cat <<'EOF' | kubectl apply -n ${AWX_NAMESPACE} -f -
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: awx-operator-leader-election
+subjects:
+- kind: ServiceAccount
+  name: controller-manager
+roleRef:
+  kind: Role
+  name: awx-operator-leader-election
+  apiGroup: rbac.authorization.k8s.io
+EOF
+
+# wait for operator deployment to be available
+echo "Waiting for controller-manager deployment to be available..."
+kubectl -n ${AWX_NAMESPACE} wait --for=condition=available deployment/controller-manager --timeout=180s || true
+
+# Create corrected AWX CR yaml in /tmp and apply
+TMP_CR=/tmp/awx-cr-generated.yaml
+cat > ${TMP_CR} <<EOF
+apiVersion: awx.ansible.com/v1beta1
+kind: AWX
+metadata:
+  name: awx
+  namespace: ${AWX_NAMESPACE}
+spec:
+  service_type: NodePort
+  ingress_type: none
+  hostname: awx.local
+  nodeport_port: ${NODEPORT}
+  no_log: false
+  create_preload_data: true
+  replicas: 1
+EOF
+
+echo "Applying AWX CR from ${TMP_CR}"
+kubectl apply -f ${TMP_CR}
+
+# force reconcile
+kubectl -n ${AWX_NAMESPACE} annotate awx awx awx-operator-refresh=$(date +%s) --overwrite || true
+
+# wait for awx-web pod readiness (give it a long timeout because migrations run)
+echo "Waiting for awx-web pod to become ready (this may take several minutes)..."
+# wait until a pod with label app.kubernetes.io/name=awx-web is ready
+kubectl -n ${AWX_NAMESPACE} wait --for=condition=ready pod -l app.kubernetes.io/name=awx-web --timeout=900s || true
+
+# choose a free local port and start port-forward bound to 0.0.0.0
+for p in ${PORT} $(seq 18080 18090); do
+  ss -ltn | awk '{print $4}' | grep -q ":$p$" || { LISTEN_PORT=$p; break; }
+done
+if [ -z "${LISTEN_PORT:-}" ]; then echo "No free port found to bind port-forward"; exit 1; fi
+kubectl -n ${AWX_NAMESPACE} port-forward --address 0.0.0.0 svc/awx-service ${LISTEN_PORT}:80 &>/tmp/awx-port-forward.log & echo $! > /tmp/awx-pf.pid
+sleep 1
+echo "Port-forward started: host-port ${LISTEN_PORT} -> awx-service:80"
+
+# print access info
+HOST_IPS=$(ip -4 addr show scope global | awk '/inet /{print $2}' | cut -d/ -f1 | tr '\n' ' ')
+echo "Open AWX in your browser using one of these URLs (from another machine on your LAN):"
+for ip in ${HOST_IPS}; do
+  echo "  http://${ip}:${LISTEN_PORT}"
+done
+echo "Or use the Minikube VM NodePort (may not be routable from other LAN hosts):"
+echo "  http://$(minikube ip):${NODEPORT}"
+
+# show admin password
+echo "Admin credentials (user: admin). Retrieve password with this command on the host:"
+echo "  kubectl -n ${AWX_NAMESPACE} get secret awx-admin-password -o jsonpath='{.data.password}' | base64 -d"
+
+echo "Setup finished. Monitor operator logs with: kubectl -n ${AWX_NAMESPACE} logs deployment/controller-manager -c awx-manager --follow"