# Runtime Adapters

ZeroClaw uses the `RuntimeAdapter` trait to abstract the execution environment from the core agent logic. This abstraction allows the same agent code to run natively on a host machine, inside a Docker container, or on restricted edge runtimes without modification to the core loop.

***

## RuntimeAdapter Trait

The `RuntimeAdapter` trait defines the capabilities and interface for any environment ZeroClaw operates within. It is designed to be `Send + Sync` to allow safe sharing across asynchronous tasks.

```rust
pub trait RuntimeAdapter: Send + Sync {
    /// Return the human-readable name of this runtime environment.
    fn name(&self) -> &str;

    /// Report whether this runtime supports shell command execution.
    fn has_shell_access(&self) -> bool;

    /// Report whether this runtime supports filesystem read/write.
    fn has_filesystem_access(&self) -> bool;

    /// Return the base directory for persistent storage on this runtime.
    fn storage_path(&self) -> PathBuf;

    /// Report whether this runtime supports long-running background processes.
    fn supports_long_running(&self) -> bool;

    /// Return the maximum memory budget in bytes for this runtime.
    fn memory_budget(&self) -> u64 {
        0
    }

    /// Build a shell command process configured for this runtime.
    fn build_shell_command(
        &self,
        command: &str,
        workspace_dir: &Path,
    ) -> anyhow::Result<tokio::process::Command>;
}
```

***

## NativeRuntime

The `NativeRuntime` implementation provides direct execution on the host operating system. It represents the least restrictive environment and is typically used for local development or trusted server environments.

* **Shell Access**: Returns `true`. Commands are executed directly via the system shell.
* **Filesystem Access**: Returns `true`. The agent can interact with any path permitted by the user's OS permissions.
* **Memory Limits**: Typically returns `0` (unlimited), relying on the OS to manage process resources.
* **Command Building**: Spawns `tokio::process::Command` directly with the requested command string.

***

## DockerRuntime

The `DockerRuntime` provides isolated execution by wrapping operations in Docker containers. This is the preferred runtime for untrusted code execution or when strict environment reproducibility is required.

* **Shell Access**: Configurable, but generally `true`. Commands are wrapped in `docker exec` calls targeting a specific container.
* **Filesystem Access**: Restricted to the volumes and mounts defined in the container configuration.
* **Memory Budgets**: Returns the memory limits defined for the container, allowing the agent to adapt its cache and buffer sizes.
* **Command Building**: Instead of direct execution, it constructs a command that executes inside the container namespace, often involving complex argument escaping and environment variable injection.

***

## Capability Querying

The agent loop queries the `RuntimeAdapter` before attempting to execute tools or background tasks. This ensures that the agent fails gracefully or skips unavailable functionality based on its environment.

1. **Tool Pre-flight**: Before executing a shell tool, the orchestrator checks `has_shell_access()`.
2. **Persistence Check**: Before initializing disk-based state, the agent checks `has_filesystem_access()`.
3. **Background Services**: The heartbeat loop and gateway server only start if `supports_long_running()` returns `true`.

This pattern prevents runtime errors by verifying environmental support at the logic gate rather than deep within the execution stack.

***

## Command Building

The `build_shell_command` method is the primary bridge between the agent and the OS. It takes a raw command string and a workspace directory, returning a configured `tokio::process::Command`.

Runtimes use this to:
* Prepend sandbox wrappers (e.g., `firejail` or `sudo -u limited`).
* Set environment variables specific to the runtime (e.g., `PATH` or `HOME`).
* Handle working directory mapping (especially important in Docker where host paths and container paths differ).

***

## Tool Routing

Tool execution can be routed through specific runtimes based on security requirements. A "Security Router" might send filesystem operations to a native runtime for speed while routing unknown shell scripts to a Docker runtime for isolation. This routing logic relies on the standardized interface provided by the `RuntimeAdapter`.

***

## Relevance to Luna

Luna currently operates with implicit native execution. As Luna evolves to support tool execution and autonomous tasks, implementing an `IRuntimeAdapter` interface will be critical for safety.

* **Isolation**: Adopting a pattern similar to ZeroClaw's `DockerRuntime` would allow Luna to run generated code in a sandbox without risking the host system.
* **Cross-Platform**: A runtime abstraction simplifies porting Luna to different OSs or containerized environments.
* **Security Integration**: This pairs with [[Security]] patterns to ensure that capabilities are not just checked by the runtime, but also verified against user-defined security policies.

Cross-links: [[Core]], [[Skills]], [[Configuration]].