feature/ Implement docker sandbox (#1)

* feat: implement docker sandbox

* chore: increment versions to 1.0.4 and 0.1.4

Author: yazan-albaiz

CLAUDE.md

@@ -173,9 +173,18 @@ export const DEFAULT_CONFIG = {
   showSplash: true,
   enableNotifications: true,
   enableSound: true,
+  sandbox: false,
 };
 ```
 
+### Docker Sandbox Mode
+
+Run Claude inside a Docker container for isolated execution:
+- Requires Docker Desktop 4.50+ with sandbox plugin
+- Enable with `--sandbox` flag
+- Uses `docker sandbox run --credentials host` to pass credentials
+- Related files: `src/lib/docker.ts`, `src/lib/prompt.ts`
+
 ## History
 
 Runs are saved to `~/.ralph/history/{id}.json` with full iteration records.

README.md

@@ -67,6 +67,8 @@ ralph -m 50 "Implement feature X"
 | `--no-sound` | Disable sound alerts | - |
 | `--debug` | Enable debug logging | false |
 | `--preflight-only` | Only run pre-flight checks | - |
+| `--sandbox` | Run Claude in Docker sandbox | false |
+| `--no-sandbox` | Disable Docker sandbox (default) | - |
 
 ### Keyboard Controls
 
@@ -165,6 +167,43 @@ Ralph runs several checks before starting:
 
 Run `ralph --preflight-only` to test without starting the loop.
 
+## Docker Sandbox Mode
+
+For enhanced security during AFK or overnight runs, Ralph supports running Claude inside a Docker sandbox container.
+
+### Prerequisites
+
+- Docker Desktop 4.50+ installed and running
+- Docker sandbox plugin enabled
+
+### Usage
+
+```bash
+# Run with Docker sandbox
+ralph --sandbox "Your prompt here"
+
+# Combine with other options
+ralph --sandbox -m 100 -M sonnet ./my-prd.md
+```
+
+### How It Works
+
+When sandbox mode is enabled, Ralph runs Claude via Docker's sandbox feature:
+```bash
+docker sandbox run --credentials host claude [args]
+```
+
+This provides:
+- **Isolated execution**: Claude runs in a container, not directly on your host
+- **Controlled access**: Uses `--credentials host` to pass through your Claude credentials
+- **Same functionality**: All Claude features work normally inside the sandbox
+
+### Fallback Behavior
+
+If Docker sandbox is not available (Docker not installed, not running, or missing the sandbox plugin), Ralph will prompt you to:
+- Continue without sandbox (runs Claude directly)
+- Exit and fix Docker setup
+
 ## Development
 
 ```bash

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yazangineering/ralph",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Autonomous AI coding loop CLI using Claude Code - named after Ralph Wiggum's naive, relentless persistence",
   "type": "module",
   "main": "dist/cli.js",

src/cli.tsx

@@ -18,9 +18,11 @@ import { App } from './app.js';
 import { runPreflightChecks, formatPreflightResults } from './lib/preflight.js';
 import { logger, setDebugEnabled } from './lib/logger.js';
 import { setNotificationsEnabled, setSoundEnabled } from './lib/notifications.js';
+import { runDockerPreflightChecks } from './lib/docker.js';
+import { promptSandboxFallback } from './lib/prompt.js';
 
 // Package version (will be replaced by build)
-const VERSION = '1.0.3';
+const VERSION = '1.0.4';
 
 // CLI program
 const program = new Command();
@@ -40,6 +42,8 @@ program
   .option('--no-sound', 'Disable sound alerts')
   .option('--debug', 'Enable debug logging')
   .option('--preflight-only', 'Only run pre-flight checks')
+  .option('--sandbox', 'Run Claude in Docker sandbox for isolation')
+  .option('--no-sandbox', 'Disable Docker sandbox (default)')
   .action(async (promptArg: string | undefined, options) => {
     // Enable debug if requested
     if (options.debug) {
@@ -85,8 +89,25 @@ program
       prompt,
       isFile,
       projectRoot: process.cwd(),
+      sandbox: options.sandbox || false,
     };
 
+    // Run Docker sandbox preflight checks if sandbox mode is enabled
+    if (config.sandbox) {
+      const dockerResult = await runDockerPreflightChecks();
+      if (!dockerResult.passed) {
+        const choice = await promptSandboxFallback(dockerResult);
+        if (choice === 'exit') {
+          process.exit(1);
+        }
+        // Continue without sandbox
+        config.sandbox = false;
+        logger.info('Continuing without Docker sandbox');
+      } else {
+        logger.info('Docker sandbox mode enabled');
+      }
+    }
+
     // Run pre-flight checks
     const preflightResult = await runPreflightChecks(config);
 

src/hooks/useClaudeLoop.ts

@@ -88,6 +88,7 @@ export function useClaudeLoop(options: UseClaudeLoopOptions): UseClaudeLoopRetur
         model: config.model,
         dangerouslySkipPermissions: config.dangerouslySkipPermissions,
         projectRoot: config.projectRoot,
+        sandbox: config.sandbox,
         onOutput: (chunk) => {
           logger.debug(`[STREAM] Received chunk: ${chunk.length} chars`);
           setState((prev) => ({ ...prev, output: [...prev.output, chunk] }));

src/lib/claude.ts

@@ -3,7 +3,7 @@
  */
 
 import { spawn, type ChildProcess } from 'node:child_process';
-import type { ClaudeProcessOptions, ClaudeProcessResult } from '../types/index.js';
+import type { ClaudeProcessOptions, ClaudeProcessResult, SpawnConfig } from '../types/index.js';
 import { parsePromiseTag } from './promiseParser.js';
 import { logger } from './logger.js';
 
@@ -33,18 +33,34 @@ export function buildClaudeArgs(options: ClaudeProcessOptions): string[] {
   return args;
 }
 
+export function buildSpawnConfig(options: ClaudeProcessOptions): SpawnConfig {
+  const claudeArgs = buildClaudeArgs(options);
+
+  if (options.sandbox) {
+    return {
+      command: 'docker',
+      args: ['sandbox', 'run', '--credentials', 'host', 'claude', ...claudeArgs],
+    };
+  }
+
+  return {
+    command: 'claude',
+    args: claudeArgs,
+  };
+}
+
 export async function runClaude(options: ClaudeProcessOptions): Promise<ClaudeProcessResult> {
   const startTime = Date.now();
-  const args = buildClaudeArgs(options);
+  const spawnConfig = buildSpawnConfig(options);
 
-  logger.debug('Running Claude CLI', { args: ['claude', ...args].join(' ') });
+  logger.debug('Running Claude CLI', { args: [spawnConfig.command, ...spawnConfig.args].join(' ') });
 
   return new Promise((resolve) => {
     let stdout = '';
     let stderr = '';
     let hasError = false;
 
-    const proc = spawn('claude', args, {
+    const proc = spawn(spawnConfig.command, spawnConfig.args, {
       cwd: options.projectRoot,
       env: { ...process.env, TERM: 'dumb' },
       stdio: ['ignore', 'pipe', 'pipe'],
@@ -222,6 +238,7 @@ export const claude = {
   runClaudeWithTimeout,
   killActiveProcess,
   buildClaudeArgs,
+  buildSpawnConfig,
   isClaudeAvailable,
   getClaudeVersion,
   createMockClaudeRunner,