tiny.sandbox

Overview · API · Code relationships · Verification · Audit

Overview

Executes a single command in a temporary working tree so callers can inspect filesystem changes before deciding what to retain. A disposable directory serves as the layer, while execution returns a Result holding captured child output and the report of observed filesystem changes.

Four selectable backends provide execution environments: copied staging on any host, a Linux Bubblewrap overlay, macOS staging, and Windows staging. With copied staging, the runner clones the source directory into the layer and sets the child process working directory to that copy. This backend supplies no operating system confinement against absolute paths, parent directory traversals, or symlinks that reach outside the layer for reads and writes, so arbitrary child commands can modify the original source tree. Bubblewrap provides a dedicated process namespace, with a private network namespace enabled when selected by policy.

Execution relies on a borrowed run plan naming arguments, directories, isolation policy, and limits on run time and output bytes. Each run records an Audit describing the backend configuration across filesystem, process, network, and environment dimensions. The implementation constructs this record from the chosen runner and plan rather than by measuring actual isolation, allowing callers to compare supported dimensions against required policy instead of assuming every request was granted.

The package does not apply recorded layer changes back to the source tree. Callers must copy any files they want to retain out of the layer before calling Result.deinit, which deletes the layer directory.

Definitions

Actions

Public operations.

• backendPolicyName
• backendPolicyFromName
• execute: Executes a run plan within a disposable layer directory, returning a Result that owns captured standard streams, the detected change set, an Audit record, and the layer directory handle.

Types and contracts

Public types and contracts.

• Snapshot
• ChangeSet
• Entry
• Audit: Describes the backend configuration that supported an execution result, reported across filesystem, process, network, and environment dimensions.
• BackendPolicy
• Environment
• Filesystem
• Kind
• Layer
• Network
• Operation
• Plan: One execution request, borrowed for the length of the call: the slices and directory handles in it belong to the caller and have to outlive execute .
• Preference
• Process
• Runner
• Status
• Change
• Result: Holds the resources and captured outputs of an execution, owning the standard output and standard error buffers, the recorded change set, the configuration Audit, and the layer directory.
• Policy: States what isolation a run has to have before the run starts: the policy records what the caller asks of the filesystem, process, and network dimensions, each judged on its own.

Namespaces

Public namespaces.

• audit
• command
• resolve
• confined
• change
• policy
• backend
• cwd
• scan
• plan
• layer
• result
• bwrap
• copied
• macos
• windows
• run

Code relationships

Direct static dependencies extracted from parsed source by semantic graph analysis.

Uses: tiny.bench, tiny.hypothesis, tiny.sys
Used by: None

Verification

No verification records are cataloged for this module in this build.

Audit