Scripts

• Before the action, inline, where it can block it with a reason. Example: refuse any file whose content looks like a private key, whatever path it arrived by. The API and the rest of this page call this kind a middleware.
• After the action, in the worker, where it cannot change the outcome. Example: log every model response over a token threshold to your own audit trail. The API and the rest of this page call this kind a hook.

​

Where to find it

​

Events

​

Uploads and created files

​

Reading the file

from noxus_script import Deny, FileUpload
from pypdf import PdfReader


def main(event: FileUpload) -> Deny | None:
    if event.file_path is None:
        return None  # a test run without a file
    if event.file_path.endswith(".pdf"):
        if len(PdfReader(event.file_path).pages) > 200:
            return Deny("PDFs over 200 pages are not accepted")
    return None

​

Writing a script

from noxus_script import Deny, FileUpload


def main(event: FileUpload) -> Deny | None:
    if "BEGIN PRIVATE KEY" in (event.text_excerpt or ""):
        return Deny("Looks like a private key")
    return None

• event is a frozen dataclass for the event the script binds to, so its fields are typed attributes: FileUpload, FileUploaded, LLMRequest (whose messages are LLMMessage dataclasses), LLMResponse and ApiCall. The Event page lists each field with its type, and the editor completes them after event.. The module is built from the platform’s event definitions, so it always matches what is sent.
• For a middleware, return Deny("reason") to block. Returning None or Allow() lets the action through. A plain {"allow": False, "reason": "..."} dict works too.
• The reason is the message the user sees, wherever they uploaded the file or made the request: the run form, a knowledge base, a chat, a table, the API. A refused model call shows it as the workflow run’s error, in agent and Genie chat, in a deployed widget even when its error banners are hidden, and as the reply on Slack, Teams, WhatsApp, Telegram and Google Chat. Leave it out (or return an empty one) and the action just fails with a plain message, This file could not be uploaded. or This request could not be completed., that does not say a middleware blocked it. The script’s name never reaches the user; the run history keeps it, with the reason or the failure, for admins.
• For a hook, the return value is ignored.
• Scripts run in a Python environment of their own with the standard library plus requests, pypdf, python-docx, openpyxl, python-pptx, beautifulsoup4, lxml, pyyaml, python-dateutil and chardet. The editor lists what the running deployment actually provides. Platform packages are never importable.
• Outbound HTTP is disabled by default; set EXTENSIONS_ALLOW_NETWORK=true only with an external egress policy to allow the network modules when a script is saved and, on kernels that support it, TCP at the kernel. Subprocesses, ctypes, multiprocessing and similar modules are always refused.
• The interpreter runs with an empty environment, hard CPU, memory and process limits, and a Landlock ruleset (Linux 5.13 or later) that leaves the filesystem readable only under the interpreter’s own trees and the files name resolution and TLS need, and writable only in a throwaway working directory. On a kernel without Landlock the run fails instead of running unconfined; set EXTENSIONS_REQUIRE_SANDBOX=false only if you accept that.
• The environment is built into the platform image at /opt/extensions-venv; a developer checkout builds it with make extensions-venv, and EXTENSIONS_PYTHON points at a different interpreter if you maintain your own. Without one, scripts get the standard library only.
• print() goes to the run’s captured output, which you can read in the run history.
• The editor completes as you type: the modules this deployment’s scripts can import, a module’s functions and classes with their signature after module. or from module import, and the event’s fields after event.. The list is read from the scripts’ own interpreter, so blocked modules are never suggested.
• A new script starts from a sample for its event, which follows the event until you edit it. Load sample code on the Script page swaps in the sample for the current event, after asking first if it would replace code you wrote.

​

Testing a script

​

Mode, failure policy and scope

​

Run history

​

Managing scripts over the API

curl -s -X POST "$NOXUS_URL/extensions/scripts" \
  -H "X-API-Key: $ADMIN_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "kind": "middleware",
    "event": "file.upload",
    "name": "Block private keys",
    "source": "from noxus_script import Deny, FileUpload\n\ndef main(event: FileUpload):\n    if \"BEGIN PRIVATE KEY\" in (event.text_excerpt or \"\"):\n        return Deny(\"Looks like a private key\")\n    return None\n",
    "enabled": true,
    "dry_run": false,
    "on_error": "fail_closed",
    "timeout_ms": 2000
  }'

​

Limits and guardrails

• Each run is a fresh interpreter with an empty environment: 2 s wall clock (including copying a staged file in), 2 s of CPU, EXTENSIONS_MEMORY_MB (256) of address space, 1 MB per written file, 64 open files, and at most EXTENSIONS_WORKDIR_MB (64) and EXTENSIONS_WORKDIR_FILES (256) written in all; past those the script is killed.
• The kernel decides who dies. The interpreter runs at lower CPU priority and with the highest OOM score, so under memory pressure the kernel prefers the script. Container-level OOM policies can still terminate the whole pod. When the platform runs as root, the script runs as an unprivileged user (uid 65534), so it shares no user with the platform and holds no capabilities. A seccomp filter lets it signal, re-limit or reschedule only itself, never fork or trace, and open only TCP sockets (none at all with the network off). Landlock keeps the filesystem read-only outside a throwaway working directory.
• Network. Network access is disabled by default. To enable outbound HTTP, set EXTENSIONS_ALLOW_NETWORK=true, enforce a deployment egress policy that prevents scripts from reaching private, loopback and metadata destinations directly, and set EXTENSIONS_ASSUME_EGRESS_POLICY=true to attest that policy. This is required on every Landlock ABI. Landlock limits destination ports, not destination addresses; the Python socket wrapper is convenience, not an address-level security boundary. The loopback proxy resolves and pins destinations, checks the platform SSRF policy, and allows only EXTENSIONS_ALLOWED_PORTS. Its checks protect requests that pass through it. EXTENSIONS_REQUIRE_SANDBOX=true refuses a networked run without the external policy attestation. The disabled-network path uses kernel socket restrictions.
• Bursts. A process runs EXTENSIONS_MAX_CONCURRENT (8) scripts at once. A middleware run waits up to EXTENSIONS_SLOT_WAIT_MS (2000) for a slot, then gets its full budget, with at most EXTENSIONS_MAX_QUEUED (128) waiting. Worker hooks run sequentially within each job and wait for execution capacity without the inline admission deadline. A run the platform cannot serve (no slot, a full queue, too little disk) is refused at once, and a refused middleware blocks the action whatever its failure policy says: fail open means the script’s own failures let the action through, never that flooding the platform skips the check. Size a pod for EXTENSIONS_MAX_CONCURRENT x EXTENSIONS_MEMORY_MB on top of its usual use.
• Broken scripts. A script that fails 5 times in a row on its own (error, timeout or rejection) is skipped for 60 s, its failure policy applying meanwhile (fail open lets the action through, fail closed blocks it), then gets one try; platform refusals do not count, and the Test page still runs it. Saving a new version starts it afresh.
• Fan-out. At most EXTENSIONS_MAX_SCRIPTS_PER_EVENT (5) enabled scripts per event and kind; several middleware on one event run concurrently and any denial blocks.
• Disk. An upload is written to disk once and copied, read-only, into each script’s working directory. Staging keeps EXTENSIONS_MIN_FREE_DISK_MB (1024) free on the temp volume, or the action is refused; working directories a crashed process left behind are removed on start.
• Records. A script writes at most 300 live run rows a minute per process; the rest are counted in metrics only. Enforced blocks get ten times that room (3000 a minute). Rows are kept EXTENSIONS_RUN_RETENTION_DAYS (30) days.
• Hooks run on the worker’s own extensions pool, WORKER_EXTENSIONS_CONCURRENCY (4) at a time. An event older than EXTENSIONS_HOOK_MAX_AGE_SECONDS (900) when its turn comes is dropped, so a backlog after an outage does not replay stale side effects. An upload’s file.uploaded and file.created hooks run in one job on one download of the file. Audit bodies over 64 KB are not passed on. A hook may see an event twice after a worker restart, and one can be lost if the process exits between committing the action and queueing the hook: make repeats harmless, and do not use hooks as the only record of anything. A queued hook job holds its event, so an llm.response answer excerpt or an opted-in api body sits in the job queue table until the job is cleaned up.
• Sizes. 64 KB of source, 64 KB of excerpt and transcript, 64 KB of result; 64 MB of downloaded file for a file.uploaded hook (an upload middleware gets the whole file).

​

Before and after in Settings

​

Operational metrics