Raise Docker image nofile soft limit on startup
Configure the Docker image initializer to raise the container soft nofile limit to a safer default when Docker's hard limit allows it. Document the new-image behavior and optional A0_NOFILE_LIMIT override without requiring users to add Docker ulimit flags.
Alessandro committed
May 2, 2026 at 20:37 UTC
7bd70fa8b73daac5bfbf79da632365c27b68b677
3 files changed
+45
-1
docker/run/fs/exe/initialize.sh
+37
@@ -2,6 +2,43 @@
2
3
echo "Running initialization script..."
4
5
+configure_nofile_limit() {
6
+ local desired="${A0_NOFILE_LIMIT:-65535}"
7
+ local hard_limit
8
+ local soft_limit
9
+ local target
10
+
11
+ if ! [[ "$desired" =~ ^[0-9]+$ ]] || [ "$desired" -le 0 ]; then
12
+ echo "Invalid A0_NOFILE_LIMIT '$desired'; keeping current nofile limit $(ulimit -Sn)."
13
+ return
14
+ fi
15
+
16
+ hard_limit="$(ulimit -Hn 2>/dev/null || true)"
17
+ soft_limit="$(ulimit -Sn 2>/dev/null || true)"
18
+ target="$desired"
19
+ if [[ "$hard_limit" =~ ^[0-9]+$ ]] && [ "$hard_limit" -gt 0 ] && [ "$target" -gt "$hard_limit" ]; then
20
+ target="$hard_limit"
21
+ fi
22
+
23
+ if [ "$soft_limit" = "unlimited" ]; then
24
+ echo "Keeping nofile soft limit: unlimited (hard: $(ulimit -Hn))"
25
+ return
26
+ fi
27
+
28
+ if [[ "$soft_limit" =~ ^[0-9]+$ ]] && [ "$soft_limit" -ge "$target" ]; then
29
+ echo "Keeping nofile soft limit: $soft_limit (hard: $(ulimit -Hn))"
30
+ return
31
+ fi
32
+
33
+ if ulimit -Sn "$target" 2>/dev/null; then
34
+ echo "Configured nofile soft limit: $(ulimit -Sn) (hard: $(ulimit -Hn))"
35
+ else
36
+ echo "Could not raise nofile soft limit to $target; current: $(ulimit -Sn) (hard: $(ulimit -Hn))"
37
+ fi
38
+}
39
+
40
+configure_nofile_limit
41
+
42
# branch from parameter
43
if [ -z "$1" ]; then
44
echo "Error: Branch parameter is empty. Please provide a valid branch name."
docs/guides/troubleshooting.md
+6
-1
@@ -43,7 +43,12 @@ Use the model rate limit fields in Settings (Main Model and Utility Model sectio
43
- On macOS, grant Docker Desktop access to your project files.
44
- Verify that the Docker image is updated.
45
46
-**13. Can Agent Zero interact with external APIs or services (e.g., WhatsApp)?**
46
+**13. I see `OSError: [Errno 24] Too many open files`. What should I check?**
47
+Long-running Docker containers with browser tabs, terminal sessions, sockets, and logs need a higher file-descriptor limit than Docker's low default soft limit on some hosts. New Docker images raise the soft `nofile` limit when Docker's hard limit allows it. Set `A0_NOFILE_LIMIT` only if you need a different startup target.
48
+
49
+You can verify the active limit with `docker exec -it <container> sh -lc 'cat /proc/1/limits | grep "Max open files"'`.
50
+
51
+**14. Can Agent Zero interact with external APIs or services (e.g., WhatsApp)?**
52
Yes, by creating custom tools or using MCP servers. See [Extensions](../developer/extensions.md) and [MCP Setup](mcp-setup.md).
53
54
## Troubleshooting
docs/setup/installation.md
+2
@@ -295,6 +295,7 @@ docker run -p 0:80 -v /path/to/your/work_dir:/a0/usr agent0ai/agent-zero
295
```
296
297
- Replace `0` with a fixed port if you prefer (e.g., `50080:80`)
298
+- New Docker images raise their own soft `nofile` limit when Docker allows it. Set `A0_NOFILE_LIMIT` only if you need a different target.
299
300
---
301
@@ -623,6 +624,7 @@ docker run -p 50080:80 \
624
625
- These provide initial default values when settings.json doesn't exist or when new settings are added to the application. Once a value is saved in settings.json, it takes precedence over these environment variables.
626
- Sensitive settings (API keys, passwords) use their existing environment variables
627
+- `A0_NOFILE_LIMIT` can override the image startup soft file-descriptor target; the default is `65535` and cannot exceed Docker's hard limit.
628
- Container/process restart required for changes to take effect
629
630
---