runtime
Module: runtime
Section titled “Module: runtime”Contents
Section titled “Contents”Modules
secret_shims- Secret-mediation shim injection (Unix/bwrap). Wires the broker + shim mounts
Structs
LaunchHooks- Callbacks fired around the tty-handoff to the wrapped agent. Both hooks areRunInput- Lib-level input for [execute_run]. The CLI layer (in thefirma
Functions
execute_run- Executefirma run.
firma_run::runtime::LaunchHooks
Section titled “firma_run::runtime::LaunchHooks”Struct
Callbacks fired around the tty-handoff to the wrapped agent. Both hooks are optional; the default is a no-op on each.
Generic Parameters:
- ‘a
Fields:
on_agent_launch: Option<&'a dyn Fn>- Invoked immediately after the agent process is spawned and owns theon_agent_exit: Option<&'a dyn Fn>- Invoked once the agent has been reaped, before teardown runs.
Traits: Copy
Trait Implementations:
- Clone
fn clone(self: &Self) -> Self
- Default
fn default() -> Self
firma_run::runtime::RunInput
Section titled “firma_run::runtime::RunInput”Struct
Lib-level input for [execute_run]. The CLI layer (in the firma
host crate) builds this from its clap-derived args struct.
Fields:
profile: String- Built-in profile id to use.config: Option<std::PathBuf>- Optional runtime config path (.toml, .yaml, .yml).backend: Option<crate::backend::BackendKind>- Override backend selection.sidecar_cli: crate::sidecar::SidecarCli- CLI value of--sidecar(local|<tcp://...|unix:///...>| unset).capability_file: Option<std::PathBuf>- Optional canonical signed capability seed TOML. Run exports only its rawidentity_mode: Option<crate::config::SandboxIdentityMode>- Override sandbox identity mode.preserve_host_user: bool- Preserve host user identity inside sandbox for compatibility workflows.print_effective_config: bool- Print the resolved effective config as JSON before execution.no_autostart: bool- When set, never autostart — fail with a typed error if thesidecar_startup_timeout_secs: u64- Seconds to wait for the autostarted sidecar’sreadyline.command: Vec<String>- Wrapped command and args.authority_cli: crate::authority::AuthorityCli- CLI value of--authority(local|<url>| unset).authority_profile: String- CLI value of--authority-profile. Defaultdeveloper.user_config_path: Option<std::PathBuf>- Optional override of the user-config path. Defaultallow_non_structural: bool- When true, allow non-structural (proxy-only) backends without
Trait Implementations:
- Debug
fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result
- Clone
fn clone(self: &Self) -> Self
firma_run::runtime::execute_run
Section titled “firma_run::runtime::execute_run”Function
Execute firma run.
Errors
Section titled “Errors”Returns an error when config resolution, backend lifecycle operations, or wrapped process supervision fails.
fn execute_run(args: &RunInput, hooks: &LaunchHooks) -> Result<i32, crate::error::RunError>Module: secret_shims
Section titled “Module: secret_shims”Secret-mediation shim injection (Unix/bwrap). Wires the broker + shim mounts
into a launch when the profile lists secret_providers.
Secret-mediation shim injection into the sandbox.
When a profile lists secret_providers, this wires the secret machinery
into a launch: it starts the per-run secret gateway and the out-of-sandbox
broker, and prepares the backend-specific shim path. Host-filesystem
sandboxes receive bind mounts and the broker environment; isolated guests
receive typed launch metadata for staging and their broker bridge.
The broker runs the real tool on the host (outside the sandbox) and returns its redacted output to the shim. The sandbox never sees plaintext secrets: the plaintext-holding gateway socket lives in the per-run control-plane directory, which bwrap masks from the agent, while only the redaction-only broker socket is reachable from inside the sandbox.
Provider invocations are noninteractive: stdin is null, and stdout/stderr are buffered in full before replay. Output that exceeds the broker capture limit is rejected without returning partial output.