Deployment — OS limits for multi-tenant pools

Running one brain per user (e.g. Workshop) puts many isolated brains in one process. Each is lean — a few open files + a few mmap regions — but they add up. Two OS limits can bottleneck a pool before RAM does:

A single big brain (e.g. Venue) doesn't need these raised. They matter at pool scale (hundreds–thousands of brains in one process).

What cor does automatically

• Raises its own soft nofile limit toward the hard cap on startup — no privilege needed, safe, zero-config (native/src/resource_limits.rs). So you only ever need to manage the hard cap.

• Warns once at pool scale if the hard cap or vm.max_map_count is below the projected need, with the exact fix command (so a missing setting is never silent). Single-brain deployments stay quiet.

• getOpenFileLimitInfo() exposes the live numbers for health checks / dashboards.

A process cannot raise its hard nofile cap or vm.max_map_count — those are the two things the deployment must set.

Recommended values

Per brain, post-lazy-shard: ~10–16 open files + ~24 mmap regions (with margin). For headroom to thousands of pooled brains:

ulimit -n        = 65536      (hard; cor raises soft to match)
vm.max_map_count = 262144

Copy-paste config

Docker (Workshop runs on Docker/GCE):

docker run \
  --ulimit nofile=65536:65536 \
  --sysctl vm.max_map_count=262144 \
  …your-image

Docker Compose:

services:
  workshop:
    ulimits:
      nofile: { soft: 65536, hard: 65536 }
    sysctls:
      vm.max_map_count: 262144

Kubernetes (vm.max_map_count is a non-namespaced sysctl on most clusters → set it on the node, e.g. via a privileged initContainer or node tuning; nofile via the runtime):

# Node-level (initContainer or DaemonSet):
#   sysctl -w vm.max_map_count=262144
# Pod:
spec:
  containers:
    - name: workshop
      # container runtime nofile via securityContext / runtime config

Bare GCE / host (persistent):

# /etc/sysctl.d/99-cor.conf
echo 'vm.max_map_count=262144' | sudo tee /etc/sysctl.d/99-cor.conf
sudo sysctl --system
# /etc/security/limits.d/99-cor.conf
echo '* hard nofile 65536' | sudo tee /etc/security/limits.d/99-cor.conf

Verify

ulimit -Hn                      # hard open-file cap
cat /proc/sys/vm/max_map_count  # mmap region cap

Cor logs both at pool scale if they're low. If you see the warning, apply the config above and restart.

Note: vm.max_map_count is Linux-only. On a macOS dev laptop it doesn't exist (and rarely matters at dev scale); ulimit -n applies on both. Production (Linux/Docker/GCE) needs both.