Executor

Executor

Command executors run external processes with controlled environments. Two executor types are available: native OS processes and Docker containers.

Entry Kinds

Kind	Description
exec.native	Execute commands directly on the host OS
exec.docker	Execute commands inside Docker containers

Native Executor

Runs commands directly on the host operating system.

- name: shell
  kind: exec.native
  default_work_dir: /app
  default_env:
    PATH: /usr/local/bin:/usr/bin:/bin
    LANG: en_US.UTF-8
  command_whitelist:
    - git status
    - git diff
    - npm run build

Field	Type	Default	Description
default_work_dir	string	-	Working directory for all commands
default_env	map	-	Environment variables (merged with per-command env)
command_whitelist	string[]	-	If set, only these exact commands are allowed

Native executors use a clean environment by default. Only explicitly configured environment variables are passed to child processes.

Docker Executor

Runs commands inside isolated Docker containers.

- name: sandbox
  kind: exec.docker
  image: python:3.11-slim
  default_work_dir: /workspace
  network_mode: none
  memory_limit: 536870912
  cpu_quota: 50000
  auto_remove: true
  read_only_rootfs: true
  no_new_privileges: true
  cap_drop:
    - ALL
  tmpfs:
    /tmp: rw,noexec,nosuid,size=64m
  volumes:
    - /app/data:/workspace/data:ro

Field	Type	Default	Description
image	string	required	Docker image to use
host	string	unix socket	Docker daemon URL
default_work_dir	string	-	Working directory inside container
default_env	map	-	Environment variables
command_whitelist	string[]	-	Allowed commands (exact match)
network_mode	string	bridge	Network mode: host, bridge, none
volumes	string[]	-	Volume mounts: host:container[:ro]
user	string	-	User to run as inside container
memory_limit	int	0	Memory limit in bytes (0 = unlimited)
cpu_quota	int	0	CPU quota (100000 = 1 CPU, 0 = unlimited)
auto_remove	bool	false	Remove container after exit
read_only_rootfs	bool	false	Make root filesystem read-only
no_new_privileges	bool	false	Prevent privilege escalation
cap_drop	string[]	-	Linux capabilities to drop
cap_add	string[]	-	Linux capabilities to add
pids_limit	int	0	Max processes (0 = unlimited)
tmpfs	map	-	Tmpfs mounts for writable paths

Command Whitelist

Both executor types support command whitelisting. When configured, only exact command matches are allowed:

command_whitelist:
  - ls -la
  - cat /etc/passwd

Commands not in the whitelist are rejected with an error.

Lua API

The Exec Module provides command execution:

local exec = require("exec")

local executor, err = exec.get("app:shell")
if err then return nil, err end

local proc = executor:exec("git status", {
    work_dir = "/app/repo"
})

local stdout = proc:stdout_stream()
proc:start()
local output = stdout:read()
proc:wait()

stdout:close()
executor:release()

See Also

• Exec Module - Lua API reference
• Process Host - Host that runs Wippy processes
• Filesystem - Filesystem entries used as work directories