Struct Sandbox 

pub struct Sandbox<N: NetworkPolicy = DenyAll> { /* private fields */ }

A sandbox for running untrusted code with restricted permissions

All network traffic from sandboxed processes is routed through a local proxy that applies the configured NetworkPolicy for filtering and logging.

When dropped, the sandbox will:

• Stop the network proxy
• Stop the IPC server (if enabled)
• Kill all child processes that were spawned within it
• Delete the working directory if it was auto-created, unless keep_working_dir() was called

Implementations

impl Sandbox<DenyAll>

pub async fn new() -> Result<Self>

Create a new sandbox with default configuration

Uses the global executor from executor-core (initialized with AsyncExecutor if not set). Creates a random working directory in the current directory using four English words connected by hyphens.

By default, all network access is denied (DenyAll policy).

pub async fn with_executor<E: Executor + Clone + 'static>( executor: E, ) -> Result<Self>

Create a new sandbox with a custom executor

Use this when you want to integrate with a specific async runtime (e.g., tokio, async-std) instead of the default executor.

impl<N: NetworkPolicy + 'static> Sandbox<N>

pub async fn with_config(config: SandboxConfig<N>) -> Result<Self>

Create a sandbox with custom configuration

Uses the global executor from executor-core (initialized with AsyncExecutor if not set).

pub async fn with_config_and_executor<E: Executor + Clone + 'static>( config: SandboxConfig<N>, executor: E, ) -> Result<Self>

Create a sandbox with custom configuration and executor

Use this when you want full control over both the configuration and the async runtime executor.

pub fn keep_working_dir(&mut self) -> &mut Self

Keep the working directory after the sandbox is dropped

By default, auto-created working directories are deleted when the sandbox is dropped. User-provided working directories are preserved by default. Call this method to preserve the working directory for inspection or reuse.

Note: Child processes are always killed when the sandbox is dropped, regardless of this setting.

pub fn proxy_url(&self) -> String

Get the proxy URL for environment variables

This URL should be set as HTTP_PROXY and HTTPS_PROXY for processes that need network access through the sandbox’s proxy.

pub fn command(&self, program: impl Into<String>) -> Command<'_>

Create a command builder for running a program in the sandbox

The command will automatically have HTTP_PROXY and HTTPS_PROXY environment variables set to route traffic through the sandbox’s proxy. If IPC is configured, HEEL_IPC_ENDPOINT will also be set.

pub async fn run_python(&self, script: &str) -> Result<Output>

Run a Python script in the sandbox

The script will be executed using the Python interpreter from the configured virtual environment, or the system Python if no venv is configured.

pub fn config(&self) -> &SandboxConfigData

Get a reference to the sandbox configuration data

pub fn working_dir(&self) -> &Path

Get the path to the working directory

Trait Implementations

impl<N: NetworkPolicy> Drop for Sandbox<N>

fn drop(&mut self)

Executes the destructor for this type.