adding cuda readme setup instructions
deci committed
May 20, 2025 at 10:38 UTC
425c245777795a1b0f697dd0afded04f96299a84
1 file changed
+104
docs/cuda_docker_setup.md
new
+104
@@ -0,0 +1,104 @@
1
+# Agent Zero: CUDA GPU Support 🚀
2
+
3
+This guide explains how to build and run Agent Zero with NVIDIA GPU acceleration using CUDA. Running with CUDA enables faster performance for AI workloads by leveraging your GPU.
4
+
5
+---
6
+
7
+## Prerequisites
8
+
9
+Before you begin, ensure you have:
10
+
11
+1. **NVIDIA GPU** with CUDA capability
12
+2. **NVIDIA Driver** installed on your host system
13
+3. **NVIDIA Container Toolkit** ([Install Guide](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html))
14
+ _This enables Docker to access your GPU_
15
+4. **Docker** and **Docker Compose** installed
16
+
17
+---
18
+
19
+## 1. Build the CUDA Docker Image
20
+
21
+Open a terminal in this directory and run:
22
+
23
+```bash
24
+# Set the branch you want to build from (default: main)
25
+$branch="main"
26
+docker build --no-cache -t frdel/agent-zero-run-cuda:testing --build-arg BRANCH=$branch -f Dockerfile.cuda .
27
+```
28
+
29
+---
30
+
31
+## 2. Run Agent Zero with CUDA Support
32
+
33
+You can start Agent Zero with GPU support using Docker Compose:
34
+
35
+```bash
36
+# On Linux, macOS, or Windows PowerShell:
37
+docker-compose -f docker-compose.cuda.yml up -d
38
+```
39
+
40
+- This will launch Agent Zero in the background with GPU acceleration enabled.
41
+
42
+---
43
+
44
+## 3. Access Agent Zero
45
+
46
+Once the container is running, open your browser and go to:
47
+
48
+[http://localhost:50080](http://localhost:50080)
49
+
50
+---
51
+
52
+## 4. Stopping Agent Zero
53
+
54
+To stop the CUDA-enabled Agent Zero container:
55
+
56
+```bash
57
+docker-compose -f docker-compose.cuda.yml down
58
+```
59
+
60
+---
61
+
62
+## 5. Switching Between CPU and GPU Versions
63
+
64
+You can easily switch between the CPU and GPU versions:
65
+
66
+1. **Stop the currently running version:**
67
+ ```bash
68
+ # For CPU version:
69
+ docker-compose down
70
+ # For GPU version:
71
+ docker-compose -f docker-compose.cuda.yml down
72
+ ```
73
+
74
+2. **Start the version you want:**
75
+ ```bash
76
+ # CPU version:
77
+ docker-compose -f docker-compose.yml up -d
78
+
79
+ # GPU (CUDA) version:
80
+ docker-compose -f docker-compose.cuda.yml up -d
81
+ ```
82
+
83
+---
84
+
85
+## Troubleshooting & Tips
86
+
87
+- **First time setup may take several minutes** as dependencies are downloaded and installed.
88
+- If you encounter issues with GPU access, verify your NVIDIA drivers and the NVIDIA Container Toolkit are correctly installed.
89
+- To check if CUDA is available inside the container, you can run:
90
+ ```bash
91
+ docker exec -it <container_name> python3 -c "import torch; print(torch.cuda.is_available())"
92
+ ```
93
+- For advanced configuration, see the comments in [`Dockerfile.cuda`](mdc:docker/run/Dockerfile.cuda).
94
+
95
+---
96
+
97
+## More Information
98
+
99
+- [NVIDIA Container Toolkit Documentation](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html)
100
+- [Agent Zero Project](https://github.com/frdel/agent-zero) (replace with your actual repo link if different)
101
+
102
+---
103
+
104
+**Enjoy accelerated AI with Agent Zero and CUDA!**