fix(executor): mark pool backend experimental, auto selects ephemeral

[daryllimyt]

What

Marks the pool executor backend as experimental and not production ready, and stops auto from silently selecting it.

• auto now resolves to ephemeral when nsjail is available (previously pool). Fallback to direct is unchanged.
• Explicitly selecting pool logs a warning at backend resolution.
• ExecutorBackendType, PoolBackend, and the TRACECAT__EXECUTOR_BACKEND config docstrings now carry the experimental caveat.
• The pool and test backends are removed from the docs entirely: docs/self-hosting/security.mdx recommends ephemeral for production, and the backend table, Kubernetes guide, and env-var reference now only document direct, ephemeral, and auto. Both remain valid (undocumented) config values.

Why

Pool workers are long-lived and import from registry cache paths that in-process cache leases cannot see. Bounded cache eviction (#3139) therefore has to exempt tarball-bearing entries under the pool backend, which means the executor registry cache can grow without bound in pool mode. Until pool has worker-aware cache ownership (per-worker leases or worker draining/recycling), it should not be selected implicitly or recommended for production.

Notes

• Behavior change: deployments running TRACECAT__EXECUTOR_BACKEND=auto with nsjail available switch from warm pool workers to cold ephemeral sandboxes (~100-200ms → ~4000ms per action) in exchange for bounded cache behavior and full per-action isolation. Explicit pool config is untouched.
• No deployment target in this repo sets TRACECAT__EXECUTOR_BACKEND; the default remains direct.

[zeropath-ai]

✅ No security or compliance issues detected. Reviewed everything up to 8497da2.

Security Overview

• 🔎 Scanned files: 7 changed file(s)
• 🔗 Scan Link: https://zeropath.com/app/repositories/00dffd6c-8834-4dc9-b6d8-b44cd1622986?scanId=410bee65-83a8-4a47-ab15-186108dcaba1&codeScanTypes=PrScan&tab=issues

Detected Code Changes

Change Type	Relevant files
Enhancement	► docs/self-hosting/kubernetes.mdx     Change wording of backend description in security note
Bug Fix	► docs/self-hosting/security.mdx     Update backend options from pool to ephemeral in table and example text ► docs/snippets/environment-variables.mdx     Correct description of TRACECAT__EXECUTOR_BACKEND options and available backends
Enhancement	► tracecat/config.py     Clarify backend descriptions and update auto-backend behavior to prefer ephemeral when nsjail is available; adjust formatting and add explicit note about experimental status for pool backend
Enhancement	► tracecat/executor/backends/pool/backend.py     Add EXPERIMENTAL note and guidance about production readiness
Enhancement	► tracecat/executor/backends/test.py     Add note for AI agents describing non-user-facing backend and usage guidance
Enhancement	► tracecat/executor/schemas.py     Update ExecutorBackendType docstring with experimental status; adjust AUTO backend behavior description to reflect experimental status; add warning when pool backend is selected

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
tracecat	🟢 Ready	View Preview	Jul 28, 2026, 4:12 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 55629a7658

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".