Skip to content

runtime

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 are
  • RunInput - Lib-level input for [execute_run]. The CLI layer (in the firma

Functions


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 the
  • on_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

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 raw
  • identity_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 the
  • sidecar_startup_timeout_secs: u64 - Seconds to wait for the autostarted sidecar’s ready line.
  • 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. Default developer.
  • user_config_path: Option<std::PathBuf> - Optional override of the user-config path. Default
  • allow_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

Function

Execute firma run.

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>

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.