Exec factory

exec stages declared pond inputs, runs an explicitly named host program in a Linux Bubblewrap sandbox, and commits approved outputs on clean completion. It requires a real writable pond, Linux user-namespace support, bwrap, and the program/runtime. It is not supported by host-only sitegen mode or macOS.

Example configuration

program: /usr/bin/sha256sum  # Required: example absolute executable path.
inputs: [/data/input.txt]   # Required: example pond file, staged read-only.
args: [data/input.txt]      # Example checksum argument; default is [].
env: {}                    # Default: no extra environment variables.
host_inputs: []            # Default: no files from the operator's -d root.
outputs: []                # Default: no ordinary files committed back.
series_outputs: []         # Default: no append-only output paths.
network: false             # Default: network isolation.
interactive: false         # Default: detached sandbox session.
timeout_seconds: null      # Default: 60 seconds; unlimited if interactive=true.

Use and behavior

This prerequisite-dependent sample prints a checksum; it does not persist stdout. Install with pond mknod exec /etc/checksum --config-path exec.yaml, then pond run /etc/checksum. Inspect inputs/committed outputs with cat; update configuration with mknod ... --overwrite.

For an explicit host input, replace host_inputs: [] with a list of {source: /input.txt, target: /data/input.txt} mappings and supply pond -d. Both paths are required; source is inside the operator-selected host root, not an arbitrary ambient host path. Set timeout_seconds: 0 only to explicitly disable the timeout.

Full configuration

Settings

FieldAccepted typeRequiredDefaultDescription
argsarray of stringno[]Literal argument vector passed to the program. Never shell-interpreted; if shell semantics are wanted, spell them out explicitly, e.g. program: /bin/bash, args: ["-c", "..."].
envmap of stringno{}Explicit environment variables set inside the sandbox. Empty by default -- nothing is inherited from the pond process environment.
host_inputsarray of Host Inputno[]Read-only paths from the explicit pond -d hostmount root. The exec run fails unless the operator supplied -d; pond-stored configuration can never select an ambient host filesystem root by itself.
inputsarray of stringyesnot specifiedExact pond paths staged read-only into the sandbox before exec.
interactivebooleannofalseRun the program without bwrap's --new-session isolation, so a real interactive program (a REPL, hledger add, etc.) keeps normal terminal job control (Ctrl-C, Ctrl-Z) instead of losing it to a detached session. This trades away --new-session's defense against the sandboxed program injecting fake keystrokes back at the controlling terminal (TIOCSTI) -- acceptable only because running a program interactively is already an explicit, attended choice by the operator. See docs/exec-factory-design.md's interactive sessions section.
networkbooleannofalseAllow network access inside the sandbox. false unless a concrete use case needs it; bookkeeping tools are local-file-only.
outputsarray of stringno[]Pond paths (exact files) or directory prefixes (trailing /) that may be created or modified by the program. Anything written outside these paths in the staging directory is discarded, not committed. Deletions of a path that matched outputs before exec are always treated as an error (see design doc, "Deletions, failure, and commit semantics").
programstringyesnot specifiedAbsolute path to the program to execute. Never searched on $PATH: the config is pond-versioned, so the exact binary invoked should be an explicit, auditable value.
series_outputsarray of stringno[]Exact pond paths (no directory prefixes) treated as append-only tinyfs::EntryType::FilePhysicalSeries files: the program sees the path's full prior content staged read-write (series versions are concatenated on read), and on clean exit only the new suffix bytes -- not the whole file -- are committed as the series' next version. A natural fit for append-only formats like Ledger journals. If the program leaves behind anything that isn't a byte-for-byte extension of what it started with (edited, truncated, or deleted), the whole run is rejected and the pond is left unchanged, same as any other output error.
timeout_secondsinteger | nullnonullKill the program if it hasn't exited within this many seconds. None resolves via [ExecConfig::effective_timeout]: 60s for ordinary runs, no timeout at all for interactive: true runs. Some(0) always means "no timeout", for either kind of run. Constraints: format="uint64"; minimum=0.

Host Input

A read-only path projected from the operator-selected hostmount root into the external program's bubblewrap sandbox.

FieldAccepted typeRequiredDefaultDescription
sourcestringyesnot specifiedAbsolute path within the pond -d hostmount namespace.
targetstringyesnot specifiedAbsolute path at which the source is visible inside the sandbox.

Boundaries and commit semantics

program must be absolute; arguments are literal, not shell-expanded. Use an explicit shell only when its semantics are intended. inputs are exact pond paths; outputs can be exact files or directory prefixes ending /. They are not globs. Environment is explicitly configured, not inherited wholesale. Network is disabled by default; enabling it permits external side effects which a pond rollback cannot undo.

At least one input/output/series-output is required. Ordinary outputs commit approved changes; writes outside approved output paths are discarded. Deletion of an existing approved output is an error. series_outputs are exact append-only raw file series: prior content must remain a byte-for-byte prefix and only the suffix becomes the next version. Editing, truncating, deleting, or conflicting output declarations rejects the run.

A nonzero exit, timeout, or invalid output leaves pond outputs uncommitted. The default wall timeout is 60 seconds; interactive runs default to unlimited; explicit zero is unlimited in either mode. Interactive mode relaxes session isolation for job control and is an attended operator decision, not a daemon default. Existing 740/744 tests are Linux execution evidence; this page does not claim its sample ran on a non-Linux workstation.