feat(agent): enforce per-sandbox cgroup v2 memory limits

.env.example

@@ -153,6 +153,12 @@ TRACECAT__RESULT_EXTERNALIZATION_THRESHOLD_BYTES=128000
 # --- Agent filesystem persistence ---
 # Maximum compressed bytes retained in each worker's local agent snapshot archive cache.
 TRACECAT__AGENT_FS_ARCHIVE_CACHE_MAX_BYTES=10737418240
+# Per-sandbox cgroup memory limit and executor memory reserved outside activity slots.
+TRACECAT__AGENT_SANDBOX_MEMORY_MB=4096
+TRACECAT__AGENT_SANDBOX_CGROUP_ENABLED=true
+TRACECAT__AGENT_EXECUTOR_MEMORY_RESERVE_MB=4096
+# Readiness sentinel path shared by the worker and the compose healthcheck.
+TRACECAT__AGENT_EXECUTOR_READY_FILE=/var/run/tracecat/agent-executor-ready
 
 # --- Local registry ---
 # Enable this only for local-registry development. Leave disabled for normal remote/builtin registry use.

docker-compose.dev.yml

@@ -394,6 +394,10 @@ services:
       TRACECAT__AGENT_EXECUTOR_QUEUE: ${TRACECAT__AGENT_EXECUTOR_QUEUE:-shared-agent-executor-queue}
       TRACECAT__EXECUTOR_QUEUE: ${TRACECAT__EXECUTOR_QUEUE:-shared-action-queue}
       TRACECAT__AGENT_EXECUTOR_MAX_CONCURRENT_ACTIVITIES: ${TRACECAT__AGENT_EXECUTOR_MAX_CONCURRENT_ACTIVITIES:-1}
+      TRACECAT__AGENT_SANDBOX_MEMORY_MB: ${TRACECAT__AGENT_SANDBOX_MEMORY_MB:-4096}
+      TRACECAT__AGENT_SANDBOX_CGROUP_ENABLED: ${TRACECAT__AGENT_SANDBOX_CGROUP_ENABLED:-true}
+      TRACECAT__AGENT_EXECUTOR_MEMORY_RESERVE_MB: ${TRACECAT__AGENT_EXECUTOR_MEMORY_RESERVE_MB:-4096}
+      TRACECAT__AGENT_EXECUTOR_READY_FILE: ${TRACECAT__AGENT_EXECUTOR_READY_FILE:-/var/run/tracecat/agent-executor-ready}
       TRACECAT__LLM_PROXY_READ_TIMEOUT: ${TRACECAT__LLM_PROXY_READ_TIMEOUT:-600}
       TRACECAT__LLM_GATEWAY_CREDENTIAL_CACHE_TTL_SECONDS: ${TRACECAT__LLM_GATEWAY_CREDENTIAL_CACHE_TTL_SECONDS:-60}
       TRACECAT__LLM_GATEWAY_HEALTHCHECK_INTERVAL_SECONDS: ${TRACECAT__LLM_GATEWAY_HEALTHCHECK_INTERVAL_SECONDS:-30}
@@ -418,6 +422,11 @@ services:
       - ${TRACECAT__LOCAL_REPOSITORY_PATH}:/app/local_registry
       - sandbox-cache:/var/lib/tracecat/sandbox-cache
     command: ["python", "-m", "tracecat.agent.executor_worker"]
+    healthcheck:
+      test: ["CMD", "test", "-f", "${TRACECAT__AGENT_EXECUTOR_READY_FILE:-/var/run/tracecat/agent-executor-ready}"]
+      interval: 30s
+      retries: 3
+      start_period: 120s
     depends_on:
       litellm:
         condition: service_healthy

docker-compose.local.yml

@@ -416,6 +416,10 @@ services:
       TRACECAT__AGENT_EXECUTOR_QUEUE: ${TRACECAT__AGENT_EXECUTOR_QUEUE:-shared-agent-executor-queue}
       TRACECAT__EXECUTOR_QUEUE: ${TRACECAT__EXECUTOR_QUEUE:-shared-action-queue}
       TRACECAT__AGENT_EXECUTOR_MAX_CONCURRENT_ACTIVITIES: ${TRACECAT__AGENT_EXECUTOR_MAX_CONCURRENT_ACTIVITIES:-1}
+      TRACECAT__AGENT_SANDBOX_MEMORY_MB: ${TRACECAT__AGENT_SANDBOX_MEMORY_MB:-4096}
+      TRACECAT__AGENT_SANDBOX_CGROUP_ENABLED: ${TRACECAT__AGENT_SANDBOX_CGROUP_ENABLED:-true}
+      TRACECAT__AGENT_EXECUTOR_MEMORY_RESERVE_MB: ${TRACECAT__AGENT_EXECUTOR_MEMORY_RESERVE_MB:-4096}
+      TRACECAT__AGENT_EXECUTOR_READY_FILE: ${TRACECAT__AGENT_EXECUTOR_READY_FILE:-/var/run/tracecat/agent-executor-ready}
       TRACECAT__LLM_PROXY_READ_TIMEOUT: ${TRACECAT__LLM_PROXY_READ_TIMEOUT:-600}
       TRACECAT__LLM_GATEWAY_CREDENTIAL_CACHE_TTL_SECONDS: ${TRACECAT__LLM_GATEWAY_CREDENTIAL_CACHE_TTL_SECONDS:-60}
       TRACECAT__LLM_GATEWAY_HEALTHCHECK_INTERVAL_SECONDS: ${TRACECAT__LLM_GATEWAY_HEALTHCHECK_INTERVAL_SECONDS:-30}
@@ -438,6 +442,11 @@ services:
       - ${TRACECAT__LOCAL_REPOSITORY_PATH}:/app/local_registry
       - sandbox-cache:/var/lib/tracecat/sandbox-cache
     command: ["python", "-m", "tracecat.agent.executor_worker"]
+    healthcheck:
+      test: ["CMD", "test", "-f", "${TRACECAT__AGENT_EXECUTOR_READY_FILE:-/var/run/tracecat/agent-executor-ready}"]
+      interval: 30s
+      retries: 3
+      start_period: 120s
     depends_on:
       litellm:
         condition: service_healthy

docker-compose.sandbox.yml

@@ -21,8 +21,24 @@ services:
     # Required for nsjail sandbox execution.
     cap_add:
       - SYS_ADMIN
+    # Start the entrypoint as root so it can delegate the container's cgroup
+    # v2 subtree to apiuser for per-sandbox memory limits; it drops privileges
+    # before the worker starts. The flag is coupled to user "0:0" — override
+    # neither independently.
+    user: "0:0"
+    environment:
+      TRACECAT__ENTRYPOINT_CGROUP_DELEGATE: "true"
+      TRACECAT__AGENT_SANDBOX_MEMORY_MB: ${TRACECAT__AGENT_SANDBOX_MEMORY_MB:-4096}
+      TRACECAT__AGENT_SANDBOX_CGROUP_ENABLED: ${TRACECAT__AGENT_SANDBOX_CGROUP_ENABLED:-true}
+      TRACECAT__AGENT_EXECUTOR_MEMORY_RESERVE_MB: ${TRACECAT__AGENT_EXECUTOR_MEMORY_RESERVE_MB:-4096}
+      TRACECAT__AGENT_EXECUTOR_READY_FILE: ${TRACECAT__AGENT_EXECUTOR_READY_FILE:-/var/run/tracecat/agent-executor-ready}
     security_opt:
       - seccomp:unconfined
       - systempaths=unconfined
     devices:
       - /dev/net/tun:/dev/net/tun
+    healthcheck:
+      test: ["CMD", "test", "-f", "${TRACECAT__AGENT_EXECUTOR_READY_FILE:-/var/run/tracecat/agent-executor-ready}"]
+      interval: 30s
+      retries: 3
+      start_period: 120s

docker-compose.yml

@@ -407,6 +407,10 @@ services:
         TRACECAT__AGENT_EXECUTOR_QUEUE: ${TRACECAT__AGENT_EXECUTOR_QUEUE:-shared-agent-executor-queue}
         TRACECAT__EXECUTOR_QUEUE: ${TRACECAT__EXECUTOR_QUEUE:-shared-action-queue}
         TRACECAT__AGENT_EXECUTOR_MAX_CONCURRENT_ACTIVITIES: ${TRACECAT__AGENT_EXECUTOR_MAX_CONCURRENT_ACTIVITIES:-1}
+        TRACECAT__AGENT_SANDBOX_MEMORY_MB: ${TRACECAT__AGENT_SANDBOX_MEMORY_MB:-4096}
+        TRACECAT__AGENT_SANDBOX_CGROUP_ENABLED: ${TRACECAT__AGENT_SANDBOX_CGROUP_ENABLED:-true}
+        TRACECAT__AGENT_EXECUTOR_MEMORY_RESERVE_MB: ${TRACECAT__AGENT_EXECUTOR_MEMORY_RESERVE_MB:-4096}
+        TRACECAT__AGENT_EXECUTOR_READY_FILE: ${TRACECAT__AGENT_EXECUTOR_READY_FILE:-/var/run/tracecat/agent-executor-ready}
         TRACECAT__LLM_PROXY_READ_TIMEOUT: ${TRACECAT__LLM_PROXY_READ_TIMEOUT:-600}
         TRACECAT__LLM_GATEWAY_CREDENTIAL_CACHE_TTL_SECONDS: ${TRACECAT__LLM_GATEWAY_CREDENTIAL_CACHE_TTL_SECONDS:-60}
         TRACECAT__LLM_GATEWAY_HEALTHCHECK_INTERVAL_SECONDS: ${TRACECAT__LLM_GATEWAY_HEALTHCHECK_INTERVAL_SECONDS:-30}
@@ -433,6 +437,11 @@ services:
         - ${TRACECAT__LOCAL_REPOSITORY_PATH}:/app/local_registry
         - sandbox-cache:/var/lib/tracecat/sandbox-cache
       command: ["python", "-m", "tracecat.agent.executor_worker"]
+      healthcheck:
+        test: ["CMD", "test", "-f", "${TRACECAT__AGENT_EXECUTOR_READY_FILE:-/var/run/tracecat/agent-executor-ready}"]
+        interval: 30s
+        retries: 3
+        start_period: 120s
       depends_on:
         litellm:
           condition: service_healthy

docker/scripts/entrypoint.sh

@@ -1,6 +1,22 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+# When started as root with delegation requested (the sandbox Compose overlay
+# pairs TRACECAT__ENTRYPOINT_CGROUP_DELEGATE with user: "0:0"), hand the
+# container's cgroup v2 subtree to apiuser so agent sandbox memory limits can
+# be prepared without root, then drop privileges before doing anything else.
+if [[ "$(id -u)" == "0" && "${TRACECAT__ENTRYPOINT_CGROUP_DELEGATE:-false}" == "true" ]]; then
+    if mount -o remount,rw /sys/fs/cgroup &&
+        chown apiuser:apiuser /sys/fs/cgroup /sys/fs/cgroup/cgroup.procs \
+            /sys/fs/cgroup/cgroup.subtree_control /sys/fs/cgroup/cgroup.threads; then
+        echo "Delegated /sys/fs/cgroup to apiuser."
+    else
+        echo "Unable to delegate /sys/fs/cgroup to apiuser; agent sandbox" \
+            "cgroup limits will be unavailable." >&2
+    fi
+    exec setpriv --reuid=apiuser --regid=apiuser --init-groups /app/entrypoint.sh "$@"
+fi
+
 # Function to run migrations
 run_migrations() {
     echo "Running database migrations..."