From: David Uhden Collado <daviduhden@gmail.com>
Subject: Improve devel/codex README
To: ports@openbsd.org, kirill@korins.ky
Date: Fri, 28 Aug 2026 19:32:00 +0000

Hello,

I'd like to propose the attached improvement to the devel/codex
pkg-readme.

The current README only mentions that Codex may require more memory and
file descriptors and suggests increasing datasize and maxfiles limits.
The new version expands this into a more practical OpenBSD-specific
guide.

It explains that larger Codex workloads may consume significant memory,
spawn many subprocesses, and use a large number of file descriptors,
especially when multiple agents are running in parallel.

Rather than recommending that users raise limits globally, the updated
README suggests creating a dedicated "codex" login class in
/etc/login.conf with higher openfiles, maxproc, datasize, and stacksize
limits.

It also documents the complete procedure:

- adding the login class;
- rebuilding login.conf.db with cap_mkdb(8);
- assigning the class with usermod(8);
- starting a new login session so the limits actually take effect;
- checking the resulting limits with ulimit.

The proposed values are explicitly described as starting points for
heavier workloads rather than requirements.

The final section also makes a distinction between per-user login class
limits and system-wide kern.maxproc/kern.maxfiles limits, recommending
that the latter only be changed if they are actually the bottleneck.

I think this is more useful than the current generic recommendation,
while keeping resource-limit changes scoped to users who actually run
Codex.

Thank you for your time and consideration.

Best regards,
David.
Index: pkg/README
===================================================================
RCS file: /cvs/ports/devel/codex/pkg/README,v
diff -u -p -u -r1.2 README
--- pkg/README	24 Aug 2026 16:39:57 -0000	1.2
+++ pkg/README	28 Aug 2026 19:26:48 -0000
@@ -14,9 +14,60 @@ one you should add into ~/.codex/config.
 	base_url = "http://127.0.0.1:8080/v1"
 	wire_api = "responses"
 
-${PKGSTEM} uses a lot of memory, it starts with 256Mb per agent/worker
-thread, and you may need to bump your limits (`ulimit -d`) or raise
-datasize limit in used login class..
+Resource limits
 
-Also, ${PKGSTEM} may use a lot of open files, you may need to raise both
-the system-wide maxfiles and used login class limits.
+Codex can spawn multiple subprocesses (shell, ripgrep, git, python,
+etc.), run several agents in parallel, and use a significant number of
+file descriptors and a lot of memory when working on large
+repositories. On current OpenBSD, the default login class limits
+datasize to 1536M, maxproc to 128 and openfiles to 512. Small sessions
+fit within these limits, but large or highly parallel Codex workloads
+may hit them.
+
+Recommended login class
+
+If Codex fails to spawn processes, runs out of memory, or reports
+"too many open files", consider creating a dedicated login class
+instead of raising the limits of every user. Add this to
+/etc/login.conf:
+
+codex:\
+	:openfiles-cur=1024:\
+	:openfiles-max=2048:\
+	:maxproc-cur=512:\
+	:maxproc-max=1024:\
+	:datasize-cur=8G:\
+	:datasize-max=16G:\
+	:stacksize-cur=8M:\
+	:stacksize-max=16M:\
+	:tc=default:
+
+Rebuild the login class database so the change takes effect:
+
+	# cap_mkdb /etc/login.conf
+
+Apply the class
+
+Assign the class to the user who runs Codex:
+
+	# usermod -L codex <user>
+
+Start a new login session afterwards: log out and log in again so
+that the new limits are applied. Merely starting a new shell does not
+update the login class of the current session.
+
+Verify
+
+Check the effective limits from the user's session:
+
+	$ ulimit -a
+
+The relevant entries are nofiles (openfiles), processes (maxproc) and
+data (datasize). In the default ksh you can also query them
+individually with `ulimit -n`, `ulimit -p` and `ulimit -d`.
+
+Increase these values only as needed; the values above are starting
+points for heavier workloads. Login-class limits are preferable to
+raising system-wide kernel limits; consider kern.maxproc and
+kern.maxfiles only if the kernel limits turn out to be the actual
+bottleneck after raising the login class.