feat: self-contained agnostic runtime with project-local storage

- Rewrite VM backend as vm/ module with separate initramfs builder
- Implement robust BusyBox nc-based agent with handler script pattern
- Add project-local .containust/ directory for per-project state
- Add global ~/.containust/cache/ for shared immutable VM assets
- Inject CPIO directory entries for /tmp /run /var /root /proc /sys /dev
- Fix init script to create directories before mounting
- Fix container chroot setup with proper dynamic library copying
- Fix complex shell command execution via temporary script files
- Add step-by-step colored UX output with timing in CLI
- Fix detect_backend test to account for QEMU availability on macOS
- Add node-hello.ctst example serving Hello World on port 6500
- Refactor engine.rs into smaller focused functions for clippy compliance

Author: RemiPelloux

Cargo.lock

@@ -71,8 +71,12 @@ serde_yaml = "0.9"
 tar = "0.4"
 flate2 = "1"
 
+# HTTP client
+reqwest = { version = "0.12", features = ["blocking"] }
+
 # Utilities
 which = "7"
+ctrlc = "3"
 uuid = { version = "1", features = ["v4", "serde"] }
 chrono = { version = "0.4", features = ["serde"] }
 tempfile = "3"

Cargo.toml

@@ -26,6 +26,7 @@ tokio = { workspace = true }
 serde = { workspace = true }
 serde_yaml = { workspace = true }
 serde_json = { workspace = true }
+ctrlc = { workspace = true }
 
 [lints]
 workspace = true

crates/containust-cli/Cargo.toml

@@ -1,7 +1,12 @@
-//! `ctst run` — Deploy the component graph.
+//! `ctst run` — Deploy and run the component graph.
+
+use std::path::Path;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+use std::time::Instant;
 
 use clap::Args;
-use containust_runtime::engine::Engine;
+use containust_runtime::engine::{DeployedComponent, Engine};
 
 /// Arguments for the `run` command.
 #[derive(Args, Debug)]
@@ -10,34 +15,120 @@ pub struct RunArgs {
     #[arg(default_value = "containust.ctst")]
     pub file: String,
 
-    /// Run in detached mode.
+    /// Run in detached mode (don't wait for Ctrl+C).
     #[arg(short, long)]
     pub detach: bool,
 }
 
+const BOLD: &str = "\x1b[1m";
+const DIM: &str = "\x1b[2m";
+const GREEN: &str = "\x1b[32m";
+const CYAN: &str = "\x1b[36m";
+const YELLOW: &str = "\x1b[33m";
+const RESET: &str = "\x1b[0m";
+
 /// Executes the `run` command.
 ///
-/// Creates an engine instance, checks backend availability,
-/// and deploys all components from the `.ctst` file.
-///
 /// # Errors
 ///
 /// Returns an error if deployment fails.
 pub fn execute(args: RunArgs) -> anyhow::Result<()> {
-    let engine = Engine::new();
+    let total_start = Instant::now();
+    print_header();
 
+    let path = std::path::Path::new(&args.file);
+    if !path.exists() {
+        return Err(anyhow::anyhow!(
+            "Composition file not found: {}\n\
+             Create a .ctst file or specify a path: ctst run <file>",
+            args.file
+        ));
+    }
+
+    let engine = Engine::new();
     if !engine.is_available() {
-        println!("Warning: Native container backend not available on this platform.");
-        println!("A lightweight Linux VM will be used (requires QEMU).");
+        print_vm_notice();
     }
 
-    let path = std::path::Path::new(&args.file);
-    let ids = engine.deploy(path).map_err(|e| anyhow::anyhow!("{e}"))?;
+    let deployed = deploy_and_report(&engine, path, total_start)?;
 
-    println!("Deployed {} container(s):", ids.len());
-    for id in &ids {
-        println!("  {id}");
+    if args.detach {
+        eprintln!();
+        eprintln!("  Running detached. Use {BOLD}ctst stop{RESET} to stop all containers.");
+        return Ok(());
     }
 
+    wait_for_shutdown(&engine, &deployed)
+}
+
+fn print_header() {
+    eprintln!();
+    eprintln!("  {BOLD}Containust{RESET} {DIM}v{}{RESET}", env!("CARGO_PKG_VERSION"));
+    eprintln!();
+}
+
+fn print_vm_notice() {
+    eprintln!("  {YELLOW}Note:{RESET} No native container support on this OS.");
+    eprintln!("        A lightweight Linux VM will be used (requires QEMU).");
+    eprintln!();
+}
+
+fn deploy_and_report(
+    engine: &Engine,
+    path: &Path,
+    total_start: Instant,
+) -> anyhow::Result<Vec<DeployedComponent>> {
+    let deployed = engine.deploy(path).map_err(|e| anyhow::anyhow!("{e}"))?;
+
+    eprintln!();
+    eprintln!(
+        "  {GREEN}{BOLD}Deployed {}{RESET} container(s) in {:.1}s:",
+        deployed.len(),
+        total_start.elapsed().as_secs_f64()
+    );
+    eprintln!();
+
+    for comp in &deployed {
+        let port_info = comp
+            .port
+            .map_or_else(String::new, |p| format!(" {CYAN}->{RESET} http://localhost:{p}"));
+        eprintln!("    {GREEN}●{RESET} {BOLD}{}{RESET} {DIM}[{}]{RESET}{port_info}", comp.name, comp.id);
+    }
+
+    let ports: Vec<_> = deployed.iter().filter_map(|c| c.port).collect();
+    if !ports.is_empty() {
+        eprintln!();
+        for port in &ports {
+            eprintln!("  {CYAN}Access at:{RESET} {BOLD}http://localhost:{port}{RESET}");
+        }
+    }
+
+    let project_dir = containust_common::constants::project_dir(path);
+    eprintln!();
+    eprintln!("  {DIM}Project state: {}{RESET}", project_dir.display());
+
+    Ok(deployed)
+}
+
+fn wait_for_shutdown(engine: &Engine, _deployed: &[DeployedComponent]) -> anyhow::Result<()> {
+    eprintln!();
+    eprintln!("  Press {BOLD}Ctrl+C{RESET} to stop all containers...");
+
+    let running = Arc::new(AtomicBool::new(true));
+    let r = running.clone();
+    ctrlc::set_handler(move || {
+        r.store(false, Ordering::SeqCst);
+    })
+    .map_err(|e| anyhow::anyhow!("failed to set Ctrl+C handler: {e}"))?;
+
+    while running.load(Ordering::SeqCst) {
+        std::thread::sleep(std::time::Duration::from_millis(250));
+    }
+
+    eprintln!();
+    eprintln!("  Stopping containers...");
+    engine.stop_all().map_err(|e| anyhow::anyhow!("{e}"))?;
+    eprintln!("  {GREEN}All containers stopped.{RESET}");
+
     Ok(())
 }

crates/containust-cli/src/commands/run.rs

@@ -6,7 +6,8 @@
 #![allow(
     clippy::unnecessary_wraps,
     clippy::needless_pass_by_value,
-    clippy::print_stdout
+    clippy::print_stdout,
+    clippy::print_stderr
 )]
 
 mod commands;

crates/containust-cli/src/main.rs

@@ -25,6 +25,39 @@ pub fn data_dir() -> &'static PathBuf {
     DATA_DIR.get_or_init(resolve_data_dir)
 }
 
+/// Returns the global cache directory for immutable shared assets
+/// (Alpine kernel, initramfs). Stored at `~/.containust/cache/`.
+pub fn global_cache_dir() -> PathBuf {
+    if let Ok(home) = std::env::var("HOME").or_else(|_| std::env::var("USERPROFILE")) {
+        let cache = PathBuf::from(home).join(".containust").join("cache");
+        let _ = std::fs::create_dir_all(&cache);
+        return cache;
+    }
+    PathBuf::from(SYSTEM_DATA_DIR).join("cache")
+}
+
+/// Resolves the project-local `.containust/` directory next to a `.ctst` file.
+/// Creates the directory if it doesn't exist.
+pub fn project_dir(ctst_path: &std::path::Path) -> PathBuf {
+    let cwd = || std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."));
+    let parent = ctst_path
+        .canonicalize()
+        .ok()
+        .and_then(|p| p.parent().map(std::path::Path::to_path_buf))
+        .unwrap_or_else(|| {
+            ctst_path.parent().map_or_else(cwd, |p| {
+                if p.as_os_str().is_empty() {
+                    cwd()
+                } else {
+                    p.to_path_buf()
+                }
+            })
+        });
+    let project = parent.join(".containust");
+    let _ = std::fs::create_dir_all(&project);
+    project
+}
+
 /// Returns the default state file path.
 pub fn default_state_file() -> String {
     data_dir().join("state.json").to_string_lossy().into_owned()

crates/containust-common/src/constants.rs

@@ -21,6 +21,9 @@ chrono = { workspace = true }
 nix = { workspace = true }
 libc = { workspace = true }
 which = { workspace = true }
+reqwest = { workspace = true }
+flate2 = { workspace = true }
+tar = { workspace = true }
 
 [dev-dependencies]
 tempfile = { workspace = true }

crates/containust-runtime/Cargo.toml

@@ -165,12 +165,17 @@ mod tests {
     }
 
     #[test]
-    fn detect_backend_returns_usable_backend() {
+    fn detect_backend_returns_instance() {
         let backend = detect_backend();
+        // On Linux the native backend is always available.
+        // On macOS/Windows the VM backend is available when QEMU is installed.
         #[cfg(target_os = "linux")]
         assert!(backend.is_available());
         #[cfg(not(target_os = "linux"))]
-        assert!(!backend.is_available());
+        {
+            // Just verify detect_backend returns a valid object.
+            let _ = backend.is_available();
+        }
     }
 
     #[test]