cayu.testing.LocalRunner

Part of cayu.testing.base. Read the Python API overview and install the required extra.

from cayu.testing import LocalRunner

Executes local commands with cwd restricted under one root.

This is not a sandbox. Commands still run with the permissions of the current OS user and can access absolute paths allowed by the OS.

Host environment inheritance is fail-closed: by default commands see only a minimal operational base env (SAFE_LOCAL_ENV_KEYS) plus explicit per-call env, so host secrets are not leaked into agent commands. Pass inherit_env=True to opt in to the full host environment. Declared secret_env entries are resolved through secret_resolver at exec time and their values are redacted from captured output.

Bases: Runner, RunnerBinaryStreamCapability.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
isolation	class attribute	'local'
default_cwd	str	'/'
system_execution_mode	RunnerSystemExecutionMode	'shared'

workload_authority (method)

LocalRunner.workload_authority(name: str) -> RunnerWorkloadAuthority | None

Return runner-owned authority for an exact provisioned workload.

execution_environment_authority (method)

LocalRunner.execution_environment_authority() -> ExecutionEnvironmentAuthority

Return the exact environment boundary that owns this runner.

output_secret_values_present (method)

LocalRunner.output_secret_values_present() -> bool | None

Report whether command output can contain runner-owned secret values.

None is fail-closed unknown authority. Wrappers must merge their own secret registry with the wrapped runner’s declaration.

browser_control_endpoint_reachable (method)

LocalRunner.browser_control_endpoint_reachable(endpoint: str) -> bool | None

Report whether the guest can dial a browser control or recording endpoint.

None makes no declaration: reachability then rests on deployment configuration, as with Docker’s colocated control-server alias. A runner whose guest has a fixed, verified control path returns False for every endpoint outside it, so no control credential is sent there.

browser_recording_supported (method)

LocalRunner.browser_recording_supported() -> bool

Declare that this runner captures and finalizes browser recordings.

execution_profile_identity (property)

LocalRunner.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Return a stable application declaration, or None when non-portable.

preflight_exec (method)

LocalRunner.preflight_exec(command: ExecCommand, *, cwd: str | None=None, env: dict[str, str] | None=None, env_remove: tuple[str, ...]=(), timeout_s: int | None=None, stdin: str | None=None, output_limit_bytes: int | None=DEFAULT_EXEC_OUTPUT_LIMIT_BYTES) -> None

Validate Local’s complete environment ownership contract.

exec (method)

async LocalRunner.exec(command: ExecCommand, *, cwd: str | None=None, env: dict[str, str] | None=None, env_remove: tuple[str, ...]=(), timeout_s: int | None=None, stdin: str | None=None, output_limit_bytes: int | None=DEFAULT_EXEC_OUTPUT_LIMIT_BYTES) -> ExecResult

exec_redacted (method)

async LocalRunner.exec_redacted(command: ExecCommand, *, redactor: SecretRedactor, cwd: str | None=None, env: dict[str, str] | None=None, env_remove: tuple[str, ...]=(), timeout_s: int | None=None, stdin: str | None=None, output_limit_bytes: int | None=DEFAULT_EXEC_OUTPUT_LIMIT_BYTES) -> ExecResult

exec_system (method)

async LocalRunner.exec_system(command: ExecCommand, *, cwd: str | None=None, env: dict[str, str] | None=None, env_remove: tuple[str, ...]=(), timeout_s: int | None=None, stdin: str | None=None, output_limit_bytes: int | None=DEFAULT_EXEC_OUTPUT_LIMIT_BYTES) -> ExecResult

Execute a control-plane lifecycle command on the declared system lane.

close (method)

async LocalRunner.close() -> None

Release the runner. The default implementation only marks it closed.

await_pending_command_settlement (method)

async LocalRunner.await_pending_command_settlement() -> bool

Wait for command cleanup deferred beyond an exec result.

Return True only when every command-cleanup operation dispatched before this call has positively reached its terminal boundary. This hook is consulted only after a runner explicitly reports deferred cleanup. Such runners must override it; the default fails closed so an unknown extension cannot turn absence of evidence into quiescence.

refresh_execution_admission (method)

async LocalRunner.refresh_execution_admission() -> None

Re-probe live admission evidence when supported by this runner.

The default makes no new claim. A supporting implementation may renew only the exact runner represented by its current admission candidate; it must not replace the environment, immutable image, or toolchain identity. It must also settle every dispatched probe, or transfer an authenticated settlement owner, before returning or raising. Callers must re-read and validate the complete candidate after this hook; requesting renewal never authorizes execution by itself.

execution_admission_candidate (method)

LocalRunner.execution_admission_candidate() -> ExecutionAdmissionCandidate

Expose the local runner’s explicit non-isolation evidence to Cayu.

collect_execution_admission_candidate (method)

async LocalRunner.collect_execution_admission_candidate() -> ExecutionAdmissionCandidate | None

Collect final evidence after lifecycle-owned mutating setup completes.

The default adapts existing side-effect-free snapshot implementations. Runners whose evidence depends on live external state override this hook and complete or positively transfer settlement ownership for every dispatched probe before returning or raising for any reason.

execution_admission_candidate_for (method)

LocalRunner.execution_admission_candidate_for(requirements: ExecutionRequirements) -> ExecutionAdmissionCandidate

Observe availability in this local workload’s own execution namespace.

execution_admission_observer (method)

LocalRunner.execution_admission_observer(requirements: ExecutionRequirements) -> RunnerExecutionAdmissionObserver

Create a request-scoped evidence owner for this exact runner.

Creation is side-effect-free. The lifecycle owns collection, renewal, and any transferred settlement tasks; the observer cannot admit work.

collect_execution_admission_candidate_for (method)

async LocalRunner.collect_execution_admission_candidate_for(requirements: ExecutionRequirements) -> ExecutionAdmissionCandidate

resource_key (property)

LocalRunner.resource_key() -> tuple[object, ...] | None

Stable identity of the runner-owned execution resource, when known.

is_closed (property)

LocalRunner.is_closed() -> bool

Whether terminal runner finalization has completed.

lifecycle_state (property)

LocalRunner.lifecycle_state() -> RunnerLifecycleState

Observe execution eligibility without exposing provider internals.

workspace_capability (method)

LocalRunner.workspace_capability(capability_type: type[RunnerWorkspaceCapabilityT]) -> RunnerWorkspaceCapabilityT | None

Return a narrow native-workspace capability, when supported.

The returned object has no lifecycle methods. Callers must continue to finalize the owning runner or environment; they cannot close an unmanaged provider runner through this composition path.

binary_stream_capability (method)

LocalRunner.binary_stream_capability() -> RunnerBinaryStreamCapability | None

Return bounded binary execution when its support is already known.

Discovery must not provision a runner or execute commands. Wrappers with an unknown target return None until support is established, so workspace transfers can retain their text transport fallback. Returned capabilities must preserve the owning runner’s execution fences.

reopen_exec (method)

LocalRunner.reopen_exec() -> None

Clear an intentional execution fence on an otherwise-open runner.

This is not recovery authority for inconclusive command cleanup. Poisoned instances cannot be reopened, including after a late cleanup acknowledgement; a new independently verified allocation owner is needed.

resolve_cwd (method)

LocalRunner.resolve_cwd(cwd: str | None=None) -> str

aenter (method)

async LocalRunner.__aenter__() -> Self

aexit (method)

async LocalRunner.__aexit__(exc_type: Any, exc_val: Any, exc_tb: Any) -> bool

exec_stream (method)

async LocalRunner.exec_stream(command: ExecCommand, *, cwd: str | None=None, env: dict[str, str] | None=None, env_remove: tuple[str, ...]=(), timeout_s: int | None=None, stdin: BinaryIO | None=None, stdout: BinaryIO | None=None, stdout_limit_bytes: int | None=None, output_limit_bytes: int | None=DEFAULT_EXEC_OUTPUT_LIMIT_BYTES) -> ExecResult

execution_capability_evidence (method)

LocalRunner.execution_capability_evidence() -> ExecutionCapabilityEvidence

Declare the local-process boundary without representing it as isolation.

init (method)

LocalRunner.__init__(root: str | Path, *, inherit_env: bool=False, secret_env: Sequence[SecretEnv] | Mapping[str, SecretRef]=(), secret_resolver: SecretResolver | None=None, credential_mode: CredentialModeInput=CredentialMode.RAW_ENV, allow_raw_secret_env: bool=True) -> None

Release source · Runtime guarantees · Capability guides