Merge pull request #12 from penso/web-browsing

feat(tools): add web_search and web_fetch agent tools

Author: penso

CLAUDE.md

@@ -142,6 +142,61 @@ biome check --write      # Lint & format JavaScript files (installed via mise)
 When editing `Cargo.toml` or other TOML files, run `taplo fmt` to format them
 according to the project's `taplo.toml` configuration.
 
+## Sandbox Architecture
+
+The gateway runs user commands inside isolated containers (Docker or Apple
+Container). Key files:
+
+- `crates/tools/src/sandbox.rs` — `Sandbox` trait, `DockerSandbox`,
+  `AppleContainerSandbox`, `SandboxRouter`, image build/list/clean helpers
+- `crates/tools/src/exec.rs` — `ExecTool` that routes commands through the
+  sandbox
+- `crates/cli/src/sandbox_commands.rs` — `moltis sandbox` CLI subcommands
+- `crates/config/src/schema.rs` — `SandboxConfig` with default packages list
+
+### Pre-built images
+
+Both backends support `build_image`: generate a Dockerfile with `FROM <base>`
++ `RUN apt-get install ...`, then run `docker build` / `container build`.
+The image tag is a deterministic hash of the base image + sorted package
+list (`sandbox_image_tag`). The gateway pre-builds at startup; if the image
+already exists it's a no-op.
+
+### Config-driven packages
+
+Default packages are defined in `default_sandbox_packages()` in `schema.rs`.
+On first run (no config file), a `moltis.toml` is written with all defaults
+including the full packages list. Users edit that file to add/remove packages
+and restart — the image tag changes automatically, triggering a rebuild.
+
+### Shared helpers
+
+`sandbox_image_tag`, `sandbox_image_exists`, `list_sandbox_images`,
+`remove_sandbox_image`, `clean_sandbox_images` are module-level public
+functions in `sandbox.rs`, parameterised by CLI binary name. The
+`SandboxConfig::from(&config_schema::SandboxConfig)` impl converts the
+config-crate types to tools-crate types — use it instead of manual
+field-by-field conversion.
+
+## Security
+
+### WebSocket Origin validation (CSWSH protection)
+
+The WebSocket upgrade handler in `server.rs` validates the `Origin` header.
+Cross-origin requests are rejected with 403. Loopback variants (`localhost`,
+`127.0.0.1`, `::1`) are treated as equivalent. Non-browser clients (no
+Origin header) are allowed through.
+
+This prevents the attack class from GHSA-g8p2-7wf7-98mq where a malicious
+webpage could connect to the local gateway WebSocket from the victim's
+browser.
+
+### SSRF protection
+
+`web_fetch.rs` resolves DNS and checks the resulting IP against blocked
+ranges (loopback, private, link-local, CGNAT) before making HTTP requests.
+Any changes to web_fetch must preserve this check.
+
 ## CLI Auth Commands
 
 The `auth` subcommand (`crates/cli/src/auth_commands.rs`) provides:
@@ -150,6 +205,15 @@ The `auth` subcommand (`crates/cli/src/auth_commands.rs`) provides:
 - `moltis auth reset-identity` — clear identity and user profile (triggers
   onboarding on next load)
 
+## CLI Sandbox Commands
+
+The `sandbox` subcommand (`crates/cli/src/sandbox_commands.rs`) provides:
+
+- `moltis sandbox list` — list pre-built `moltis-sandbox:*` images
+- `moltis sandbox build` — build image from config (base + packages)
+- `moltis sandbox remove <tag>` — remove a specific image
+- `moltis sandbox clean` — remove all sandbox images
+
 ## Sensitive Data Handling
 
 Never use plain `String` for passwords, API keys, tokens, or any secret
@@ -185,7 +249,6 @@ Rules:
 - **RwLock guards**: when a `RwLock<Option<Secret<String>>>` read guard is
   followed by a write in the same function, scope the read guard in a block
   `{ let guard = lock.read().await; ... }` to avoid deadlocks.
-
 ## Provider Implementation Guidelines
 
 ### Async all the way down

Cargo.lock

@@ -19,14 +19,22 @@ multiple LLM providers and communication channels, inspired by
   management
 - **Memory and knowledge base** — embeddings-powered long-term memory
 - **Skills and plugins** — extensible skill system and plugin architecture
+- **Web browsing** — web search (Brave, Perplexity) and URL fetching with
+  readability extraction and SSRF protection
 - **Scheduled tasks** — cron-based task execution
 - **OAuth flows** — built-in OAuth2 for provider authentication
 - **TLS support** — automatic self-signed certificate generation
 - **Observability** — OpenTelemetry tracing with OTLP export
+- **Sandboxed execution** — Docker and Apple Container backends with pre-built
+  images, configurable packages, and per-session isolation
 - **Authentication** — password and passkey (WebAuthn) authentication with
   session cookies, API key support, and a first-run setup code flow
+- **WebSocket security** — Origin validation to prevent Cross-Site WebSocket
+  Hijacking (CSWSH)
 - **Onboarding wizard** — guided setup for agent identity (name, emoji,
   creature, vibe, soul) and user profile
+- **Default config on first run** — writes a complete `moltis.toml` with all
+  defaults so you can edit packages and settings without recompiling
 - **Configurable directories** — `--config-dir` / `--data-dir` CLI flags and
   `MOLTIS_CONFIG_DIR` / `MOLTIS_DATA_DIR` environment variables
 
@@ -60,6 +68,20 @@ cargo run -- gateway --config-dir /path/to/config --data-dir /path/to/data
 cargo test --all-features
 ```
 
+### Sandbox Image Management
+
+```bash
+moltis sandbox list          # List pre-built sandbox images
+moltis sandbox build         # Build image from configured base + packages
+moltis sandbox clean         # Remove all pre-built sandbox images
+moltis sandbox remove <tag>  # Remove a specific image
+```
+
+The gateway pre-builds a sandbox image at startup from the base image
+(`ubuntu:25.10`) plus the packages listed in `moltis.toml`. Edit the
+`[tools.exec.sandbox] packages` list and restart — a new image with a
+different tag is built automatically.
+
 ## Project Structure
 
 Moltis is organized as a Cargo workspace with the following crates:

README.md

@@ -37,6 +37,7 @@ moltis-gateway     = { workspace = true }
 moltis-oauth       = { workspace = true }
 moltis-onboarding  = { workspace = true }
 moltis-skills      = { workspace = true }
+moltis-tools       = { workspace = true }
 open               = { workspace = true }
 reqwest            = { workspace = true }
 tokio              = { workspace = true }

crates/cli/Cargo.toml

@@ -1,4 +1,5 @@
 mod auth_commands;
+mod sandbox_commands;
 
 use {
     clap::{Parser, Subcommand},
@@ -82,6 +83,11 @@ enum Commands {
         #[command(subcommand)]
         action: SkillAction,
     },
+    /// Sandbox image management.
+    Sandbox {
+        #[command(subcommand)]
+        action: sandbox_commands::SandboxAction,
+    },
     /// Install the Moltis CA certificate into the system trust store.
     #[cfg(feature = "tls")]
     TrustCa,
@@ -266,6 +272,7 @@ async fn main() -> anyhow::Result<()> {
         },
         Commands::Onboard => moltis_onboarding::wizard::run_onboarding().await,
         Commands::Auth { action } => auth_commands::handle_auth(action).await,
+        Commands::Sandbox { action } => sandbox_commands::handle_sandbox(action).await,
         Commands::Skills { action } => handle_skills(action).await,
         #[cfg(feature = "tls")]
         Commands::TrustCa => trust_ca().await,

crates/cli/src/main.rs

@@ -0,0 +1,108 @@
+use {anyhow::Result, clap::Subcommand};
+
+use moltis_tools::sandbox;
+
+#[derive(Subcommand)]
+pub enum SandboxAction {
+    /// List pre-built sandbox images.
+    List,
+    /// Build a sandbox image from the configured base + packages.
+    Build,
+    /// Remove a specific sandbox image by tag.
+    Remove {
+        /// Image tag (e.g. moltis-sandbox:abc123).
+        tag: String,
+    },
+    /// Remove all pre-built sandbox images.
+    Clean,
+}
+
+pub async fn handle_sandbox(action: SandboxAction) -> Result<()> {
+    match action {
+        SandboxAction::List => list().await,
+        SandboxAction::Build => build().await,
+        SandboxAction::Remove { tag } => remove(&tag).await,
+        SandboxAction::Clean => clean().await,
+    }
+}
+
+async fn list() -> Result<()> {
+    let images = sandbox::list_sandbox_images().await?;
+    if images.is_empty() {
+        println!("No sandbox images found.");
+        return Ok(());
+    }
+    println!("{:<45} {:>10}  CREATED", "TAG", "SIZE");
+    for img in &images {
+        println!("{:<45} {:>10}  {}", img.tag, img.size, img.created);
+    }
+    Ok(())
+}
+
+async fn build() -> Result<()> {
+    let config = moltis_config::discover_and_load();
+    let sandbox_config = sandbox::SandboxConfig::from(&config.tools.exec.sandbox);
+
+    let packages = sandbox_config.packages.clone();
+    if packages.is_empty() {
+        println!("No packages configured — nothing to build.");
+        println!("Add packages to [tools.exec.sandbox] in your config file.");
+        return Ok(());
+    }
+
+    let base = sandbox_config
+        .image
+        .clone()
+        .unwrap_or_else(|| sandbox::DEFAULT_SANDBOX_IMAGE.to_string());
+    let tag = sandbox::sandbox_image_tag(&base, &packages);
+    println!("Base:     {base}");
+    println!("Packages: {}", packages.join(", "));
+    println!("Tag:      {tag}");
+    println!();
+
+    // Force mode to All so create_sandbox returns a real backend.
+    let sandbox_config = sandbox::SandboxConfig {
+        mode: sandbox::SandboxMode::All,
+        ..sandbox_config
+    };
+    let backend = sandbox::create_sandbox(sandbox_config);
+    match backend.build_image(&base, &packages).await? {
+        Some(result) => {
+            if result.built {
+                println!("Image built successfully: {}", result.tag);
+            } else {
+                println!("Image already exists: {}", result.tag);
+            }
+        },
+        None => {
+            println!(
+                "Backend '{}' does not support image building.",
+                backend.backend_name()
+            );
+        },
+    }
+    Ok(())
+}
+
+async fn remove(tag: &str) -> Result<()> {
+    sandbox::remove_sandbox_image(tag).await?;
+    println!("Removed: {tag}");
+    Ok(())
+}
+
+async fn clean() -> Result<()> {
+    let count = sandbox::clean_sandbox_images().await?;
+    if count == 0 {
+        println!("No sandbox images to remove.");
+    } else {
+        println!(
+            "Removed {count} sandbox image{}.",
+            if count == 1 {
+                ""
+            } else {
+                "s"
+            }
+        );
+    }
+    Ok(())
+}

crates/cli/src/sandbox_commands.rs

@@ -63,7 +63,12 @@ pub fn discover_and_load() -> MoltisConfig {
             },
         }
     } else {
-        debug!("no config file found, using defaults");
+        debug!("no config file found, writing default config");
+        let config = MoltisConfig::default();
+        if let Err(e) = write_default_config(&config) {
+            warn!(error = %e, "failed to write default config file");
+        }
+        return config;
     }
     MoltisConfig::default()
 }
@@ -170,6 +175,23 @@ fn save_config_inner(config: &MoltisConfig) -> anyhow::Result<PathBuf> {
     Ok(path)
 }
 
+/// Write the default config file to the user-global config path.
+/// Only called when no config file exists yet.
+fn write_default_config(config: &MoltisConfig) -> anyhow::Result<()> {
+    let path = find_or_default_config_path();
+    if path.exists() {
+        return Ok(());
+    }
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent)?;
+    }
+    let toml_str =
+        toml::to_string_pretty(config).map_err(|e| anyhow::anyhow!("serialize config: {e}"))?;
+    std::fs::write(&path, &toml_str)?;
+    debug!(path = %path.display(), "wrote default config file");
+    Ok(())
+}
+
 fn parse_config(raw: &str, path: &Path) -> anyhow::Result<MoltisConfig> {
     let ext = path.extension().and_then(|e| e.to_str()).unwrap_or("toml");