zephyr.process

Restricted process execution for trusted system modules. Functions require `process:exec` and are additionally gated by a hardcoded system-module allowlist in the host runtime.

1 function

exec

process:exec

zephyr.process.exec(opts)

Run a local process and capture its output.

Only hardcoded system modules may execute binaries. Module-sandbox paths are resolved before execution. Arguments may be strings or { path = "/cache/file.mp3" } tables, where path arguments are resolved to host paths inside the caller module's data directory.

Parameters

optstable

{ program, args?, env?, cwd?, timeout_ms?, max_output_bytes? }. program is either a PATH command name or a module-sandbox path such as /bin/youtube-dl.

Returns

table

{ status, success, stdout, stderr, stdout_truncated, stderr_truncated, timed_out }.

Raises an error if

the process:exec permission is not granted
the caller module is not in the hardcoded system-module allowlist
the program or cwd path escapes the module data directory

Example

lua

local result = zephyr.process.exec({
  program = "/bin/youtube-dl",
  args = { "--version" },
  timeout_ms = 5000,
})