Crate nyx_agent_sandbox 

Sandbox layer. Each backend isolates a single short-lived child process that runs an agent task (a dynamic verify, a payload-runner, an ai-tool call). The trait stays independent of every other nyx-agent crate so a future VM backend can ship without dragging core/api/ai changes along.

This crate is published so the nyx-agent binary can be installed from crates.io with versioned internal dependencies. It is an implementation detail of Nyx Agent, not a stable public API.

Backends shipped today:

• process: fork+exec with no isolation upgrade. The unhardened default used when an operator picks the process backend, or when no stronger backend is available on this host.
• birdcage: wraps the birdcage crate, which compiles to Linux landlock + seccomp or macOS Seatbelt. FS deny-by-default plus a single workspace-write exception; network deny unless SandboxOpts::allow_loopback is set.
• libkrun: macOS-first microVM via HVF (Linux+KVM also supported). Routed through a libkrun-runner helper binary so FFI symbol drift cannot crash the daemon.
• firecracker: Linux+KVM microVM. Routed through a nyx-fc-runner helper binary.
• docker: fallback container backend used when no stronger isolation is available; the chain-lane delegates to the docker-compose env-builder for the actual spin-up.

Re-exports

pub use backend::birdcage::BirdcageSandbox;

pub use backend::firecracker::firecracker_host_supported;

pub use backend::firecracker::FirecrackerSandbox;

pub use backend::firecracker::FirecrackerSpec;

pub use backend::libkrun::libkrun_host_supported;

pub use backend::libkrun::LibkrunSandbox;

pub use backend::libkrun::LibkrunSpec;

pub use backend::process::ProcessSandbox;

pub use chain_runner::ChainResult;

pub use chain_runner::ChainRun;

pub use chain_runner::ChainRunner;

pub use chain_runner::ChainRunnerError;

pub use chain_runner::ChainStep;

pub use chain_runner::ChainStepCapture;

pub use chain_runner::ChainVerdict;

pub use chain_runner::InconclusiveReason;

pub use payload_runner::HarnessSource;

pub use payload_runner::HarnessSpecInput;

pub use payload_runner::PayloadRun;

pub use payload_runner::PayloadRunner;

pub use payload_runner::PayloadRunnerError;

Modules

backend

Concrete crate::Sandbox implementations.

chain_runner

Cross-repo chain attack runner.

env

Env-builder: detect docker-compose files across connected repos, merge into a super-compose, spin up via docker compose, and tear down at run completion.

payload_runner

Deterministic payload runner.

shim

Wire format shared between crate::BirdcageSandbox and the nyx-sandbox-shim helper binary.

workspace

Workspace snapshot setup for sandboxed runs.

Structs

BackendSelection

Which backend the selector chose, plus a human-readable reason the doctor / live-scan UI surfaces verbatim.

LaneConcurrency

Per-lane simultaneous-spinup caps. The chain lane defaults to 2 (a full env-replay can easily consume several GB of RAM); the fast lane defaults to 8 (matches the static_concurrency ceiling on a typical 8-core dev box).

SandboxOpts

Options for a single sandboxed child.

SandboxOutcome

The captured result of a single sandboxed run.

Enums

BackendChoice

Operator-facing backend label. Mirrors nyx_agent_core::config::SandboxBackend but lives in this crate so the sandbox layer does not depend on core.

BackendKind

Which backend produced (or is about to produce) a SandboxOutcome.

Lane

Which scan lane the sandbox runs under. The chain lane spins up the full dev-env replay alongside the AI-driven exploitation, which is expensive; it gets a stricter concurrency cap than the fast lane.

SandboxError

Sandbox error surface. Backend-specific failures are folded into the closest matching variant so callers can program against the trait without reaching for downcasts.

SandboxStatus

Final state of a sandboxed child.

Traits

Sandbox

The sandbox surface used by every consumer (chain lane, payload runner, dynamic verifier). Implementors own a single child at a time: call Sandbox::run once, then either Sandbox::wait or Sandbox::kill before another run.

Functions

available_backends

Lightweight readiness probe: returns the static set of backends that the platform could run. Construction-time probes (probe) further check that the kernel surface + helper binaries are present.

permits_loopback

Refuse (Lane::Fast, BackendKind::Birdcage) when a caller asks for allow_loopback. Birdcage cannot scope loopback any tighter than “all network or none” (the field-level note on SandboxOpts::allow_loopback covers this), so opening it on the fast lane hands the lightweight verifier child a full egress channel it should never need. Chain-lane tasks legitimately want loopback to reach env-builder services on the host. Every other lane/backend combination passes through unchanged; backends that can scope loopback at the kernel (libkrun, firecracker) are free to allow it on either lane.

probe

Return Ok(()) if backend can be constructed on this host, else describe why it cannot. Callers use this to short-circuit a doctor check or to fall back to a weaker backend.

select_backend

Pick a backend for lane honouring the operator’s choice. Auto picks the strongest backend that can run on this host: