You are tasked with building a single-page, client-side application (SPA) using React and Tailwind CSS that provides macOS-native sandboxing for local AI agents. The core idea is to prevent these powerful local agents (like Claude, Cursor, Gemini CLI, etc.) from accessing or modifying files outside of a designated project directory, thus mitigating risks of accidental data loss or system corruption. The application will leverage a downloaded shell script that integrates with the macOS kernel's syscalls to enforce these restrictions. This prompt outlines the development requirements for an AI assistant to generate the complete codebase.
**1. PROJECT OVERVIEW:**
**Project Name:** Agent Safehouse
**Goal:** To provide a secure, kernel-level sandboxing solution for local AI agents on macOS, ensuring they can only interact with files within a user-defined project directory. This eliminates the '1% chance of disaster' when running powerful LLMs locally, making it a '0% chance'.
**Problem Solved:** Local AI agents, while powerful for development and automation, pose a significant risk due to their potential to execute destructive commands (e.g., `rm -rf`) or access sensitive system files. This leads to data loss, system instability, and security vulnerabilities.
**Value Proposition:** Move fast and break nothing. Empower developers and AI enthusiasts to leverage local AI agents with absolute confidence, knowing their system and data are protected by a robust, kernel-enforced security boundary. It offers peace of mind by preventing catastrophic mistakes.
**2. TECH STACK:**
- **Framework:** React (using Vite for a fast development experience)
- **Styling:** Tailwind CSS (with Headless UI for accessible components)
- **State Management:** Zustand (lightweight and performant for managing application state, including sandbox configurations)
- **Routing:** React Router DOM (for potential future expansion, though initially a single page)
- **Icons:** Heroicons
- **Shell Script Logic:** The core sandboxing mechanism will be a self-contained Bash script. The React app will serve as a UI to configure and perhaps download/manage this script.
- **Build Tool:** Vite
**3. CORE FEATURES (User Flow & Details):**
This is primarily a UI for a shell script's functionality. The React app will act as a user-friendly interface to configure and potentially download the `safehouse.sh` script.
* **Feature 1: Sandbox Configuration**
* **User Flow:**
1. User navigates to the 'Configuration' section.
2. User sees an input field for the 'Project Directory'. They can browse or manually enter the absolute path (e.g., `/Users/username/my-project`).
3. User sees a list of potentially denied system paths (e.g., `~/.ssh`, `~/Library`, `/System`, `~/.aws`). These are pre-configured and cannot be modified in MVP.
4. User can toggle 'Read-Only' access for shared libraries or specific subdirectories (Advanced feature, maybe MVP+).
5. User clicks 'Generate Script' or 'Download Script'.
* **Details:** The UI should provide clear feedback on the selected directory and the inherent security restrictions.
* **Feature 2: Script Download/Display**
* **User Flow:**
1. After configuring, the user clicks 'Download Script'.
2. A `.sh` file (`safehouse.sh`) is downloaded.
3. Alternatively, the UI displays the generated script content directly in a code block, allowing the user to copy it.
* **Details:** The script should be well-commented, explaining each step and the syscalls involved.
* **Feature 3: Running Agents via Safehouse**
* **User Flow (Illustrative - this happens in the user's terminal, not the React app):**
1. User opens their terminal.
2. They `cd` into their project directory (e.g., `cd ~/my-project`).
3. They execute the agent using the downloaded `safehouse` command: `~/.local/bin/safehouse <agent_command>` (e.g., `~/.local/bin/safehouse claude --prompt "Write a Python script..."`).
* **Details:** The React UI should clearly instruct users on how to execute agents using the downloaded script.
* **Feature 4: Compatibility Information**
* **User Flow:**
1. User visits the 'Compatibility' page.
2. They see a list of popular AI agents (Claude, Cursor Agent, Gemini CLI, Aider, etc.) with checkmarks indicating successful testing.
* **Details:** This section builds trust and informs users about which agents are known to work seamlessly within the Safehouse environment.
**4. UI/UX DESIGN:**
- **Layout:** Single Page Application (SPA) layout. A clean sidebar/navigation (e.g., on the left) for sections like 'Configuration', 'Compatibility', 'Getting Started'. The main content area displays the selected section's UI.
- **Color Palette:** Dark theme inspired by developer tools and terminals. Primary colors: Dark charcoal (`#1a1a1a`), deep navy (`#2c3e50`), accents of electric blue (`#007bff`) or vibrant green (`#28a745`) for success states/buttons, and amber/orange (`#ffc107`) for warnings or attention.
- **Typography:** Monospaced font for code blocks and terminal-like elements (e.g., `Fira Code`, `Source Code Pro`). A clean sans-serif font for UI text (e.g., `Inter`, `Roboto`).
- **Responsiveness:** Mobile-first design principles, ensuring usability on various screen sizes. Sidebar might collapse into a hamburger menu on smaller screens. Focus on clear information hierarchy and intuitive navigation.
- **Key Components:** Input fields with clear labels and validation feedback, buttons with distinct primary/secondary styles, lists with icons, code display blocks, accordions or modals for detailed explanations.
**5. DATA MODEL & STATE MANAGEMENT:**
- **State:** Primarily managed using Zustand.
- **Key State Variables:**
- `projectDirectory`: string (user-defined path)
- `isReadWriteAccessGranted`: boolean (for the project dir)
- `deniedPaths`: array of strings (predefined, non-editable in MVP)
- `agentCompatibility`: object mapping agent names to compatibility status (boolean/string)
- `generatedScriptContent`: string (the output script)
- `isLoading`: boolean (for async operations like fetching compatibility)
- `error`: string | null (for error handling)
- **Local Storage:** Store `projectDirectory` and potentially `isReadWriteAccessGranted` in localStorage for persistence between sessions.
- **Mock Data Format:**
```json
{
"agentName": "Claude",
"isCompatible": true
}
{
"agentName": "Cursor Agent",
"isCompatible": true
}
// ... more agents
```
```json
{
"path": "~/Documents/sensitive-data",
"access": "denied"
}
{
"path": "/System/Library",
"access": "denied"
}
```
**6. COMPONENT BREAKDOWN:**
- **`App.jsx`:** Main application component. Sets up routing (if needed), overall layout, and global context/state providers.
- **`Layout.jsx`:** Contains the main structure: sidebar navigation and the content area.
- **`Sidebar.jsx`:** Navigation menu component. Renders links to different sections.
- **`ConfigurationPage.jsx`:** Main content for the configuration. Includes:
- **`DirectoryInput.jsx`:** Input field for the project directory, potentially with a 'Browse' button (though native browser file input for directories is tricky, manual input is safer for MVP).
- Props: `value`, `onChange`, `label`, `placeholder`, `errorMessage`
- **`SecurityPolicy.jsx`:** Displays the list of denied paths and explains the deny-first model.
- Props: `deniedPaths` (array)
- **`GenerateButton.jsx`:** Button to trigger script generation.
- Props: `onClick`, `isLoading`
- **`ScriptDisplayPage.jsx`:** Displays the generated script.
- **`CodeBlock.jsx`:** Renders the script content with syntax highlighting.
- Props: `code`, `language`
- **`CopyButton.jsx`:** Button to copy script content to clipboard.
- Props: `textToCopy`
- **`CompatibilityPage.jsx`:** Displays agent compatibility.
- **`AgentList.jsx`:** Renders the list of agents and their status.
- Props: `agents` (array of objects)
- **`CompatibilityStatus.jsx`:** Small component to display an icon/text for compatibility (e.g., checkmark, cross, loading spinner).
- Props: `status` (string: 'compatible', 'incompatible', 'loading', 'unknown')
- **`GettingStartedPage.jsx`:** Provides instructions on installation and usage.
- **`Footer.jsx`:** Basic footer with copyright/links.
- **`Modal.jsx`:** Reusable modal component for confirmations or detailed info.
- **`Button.jsx`:** Reusable button component.
- **`Input.jsx`:** Reusable input field component.
**7. ANIMATIONS & INTERACTIONS:**
- **Page Transitions:** Subtle fade-in/fade-out transitions between sections using Framer Motion or CSS transitions.
- **Button Hover Effects:** Slight scale-up or background color change on button hover.
- **Input Focus:** Highlight border on input focus.
- **Loading States:** Use spinners or skeleton loaders while fetching compatibility data or generating the script.
- **Copy to Clipboard Feedback:** Briefly show a 'Copied!' message after successful clipboard operation.
- **Micro-interactions:** Smooth expansion/collapse of sections explaining denied paths.
**8. EDGE CASES & ACCESSIBILITY (a11y):**
- **Empty State:** If no project directory is set, display clear guidance and disable the 'Generate Script' button.
- **Invalid Path Input:** Validate the path format. While deep filesystem validation is complex, basic format checks (e.g., starts with `/` or `~/`) should be in place. Display clear error messages.
- **Script Generation Errors:** Handle cases where script generation might fail (though unlikely with a static script based on config).
- **Permissions Errors:** Inform the user that the downloaded script needs execute permissions (`chmod +x`).
- **Agent Command Errors:** Explain that errors *within* the agent's execution (after being sandboxed) are the agent's responsibility, not Safehouse's, unless they relate to sandbox violations.
- **Accessibility:** Use semantic HTML5 elements. Ensure all interactive elements are keyboard-navigable and have appropriate ARIA attributes. Use `aria-label` for icon-only buttons. Ensure sufficient color contrast.
**9. SAMPLE DATA:**
* **Configuration State:**
```json
{
"projectDirectory": "/Users/john.doe/dev/my-awesome-project",
"isReadWriteAccessGranted": true // Implicitly true for projectDirectory
}
```
* **Denied Paths (Internal State/Config):**
```json
[
{"path": "~/.ssh", "reason": "Sensitive SSH keys"},
{"path": "~/.aws", "reason": "Cloud credentials"},
{"path": "~/Library", "reason": "macOS system files & user data"},
{"path": "/System", "reason": "Core macOS operating system"},
{"path": "/etc", "reason": "System configuration files"},
{"path": "~/Downloads", "reason": "Potential user data leakage"},
{"path": "~/Documents", "reason": "Broad user data access"}
]
```
* **Agent Compatibility Data (Mock Fetch Response):**
```json
[
{"agentName": "Claude", "isCompatible": true, "notes": "Tested with CLI invocation."},
{"agentName": "Cursor Agent", "isCompatible": true, "notes": "Requires Cursor IDE setup."},
{"agentName": "Gemini CLI", "isCompatible": true, "notes": "Tested via `gcloud` or native CLI."},
{"agentName": "Aider", "isCompatible": true, "notes": "Python-based chat-to-code client."},
{"agentName": "Codeium", "isCompatible": false, "notes": "Potential issues detected, use with caution or verify."},
{"agentName": "Auggie", "isCompatible": true, "notes": "Local LLM runner compatibility."}
]
```
* **Generated Script Example (`~/.local/bin/safehouse` content):
```bash
#!/bin/bash
# Agent Safehouse - macOS Native Sandboxing Script
# Version: 1.0.0
# --- Configuration ---
# User-defined project directory. All agent operations are confined to this path.
PROJECT_DIR="/Users/john.doe/dev/my-awesome-project"
# Denied paths - syscalls to these will be blocked.
# Includes sensitive system locations and broad user data directories.
DENIED_PATHS=(
"$HOME/.ssh"
"$HOME/.aws"
"$HOME/Library"
"/System"
"/etc"
"$HOME/Downloads"
"$HOME/Documents"
)
# --- Script Logic ---
# Check if running inside a safe environment (prevents nesting issues)
if [ -n "$AGENT_SAFESTARTED" ]; then
echo "Error: Already running within Safehouse. Avoid nested execution."
exit 1
fi
# Set environment variable to indicate we are running inside Safehouse
export AGENT_SAFESTARTED=1
# Get the command to be executed
AGENT_COMMAND="$@"
if [ -z "$AGENT_COMMAND" ]; then
echo "Usage: safehouse <agent_command> [args...]"
echo "Example: safehouse claude --prompt \"Write a Python script...\""
exit 1
fi
# Validate project directory
if [ ! -d "$PROJECT_DIR" ]; then
echo "Error: Project directory '$PROJECT_DIR' does not exist or is not a directory."
echo "Please ensure the path is correct in the Safehouse configuration."
exit 1
fi
# Simulate syscall interception using auditd/fuser or similar low-level hooks
# NOTE: This script provides a UI and configuration. The actual syscall blocking
# is intended to be handled by a companion kernel extension or by leveraging
# macOS's security features like 'privacyd' or Endpoint Security Framework.
# For a pure script-based approach without extensions, this simulation relies on
# careful execution context management and potentially running agents within limited
# user contexts if feasible. The original prompt's "enforced by the kernel" implies
# a deeper integration than a single bash script can achieve alone.
# THIS SCRIPT FOCUSES ON DEFINING THE BOUNDARIES.
echo "--- Agent Safehouse --- "
echo "Sandbox initialized for project: $PROJECT_DIR"
echo "Denied access to sensitive locations."
echo "Executing command: $AGENT_COMMAND"
echo "----------------------- "
# Execute the agent command using eval to handle complex arguments and expansions
# IMPORTANT: This part requires careful security consideration. A real implementation
# might need more robust process isolation or kernel-level intervention.
# For this MVP, we simulate by directly executing the command *after* checks.
# Mocking the syscall interception: In a real scenario, you'd use tools like
# 'opensnoop' or 'fs_usage' to monitor and potentially block syscalls in real-time,
# or use a kernel extension. This script sets the stage.
# Let's assume the agent command is executed, and we'd rely on external tools or
# a proper kernel extension to enforce the 'DENIED_PATHS'.
# As a placeholder, we will execute the command within the context of the script's
# environment, assuming the user has manually set up the blocking mechanisms if needed.
# *** Placeholder for actual syscall blocking mechanism ***
# This would ideally involve a kernel extension intercepting file access syscalls
# and checking against PROJECT_DIR and DENIED_PATHS.
# Without a kernel extension, the script itself cannot *enforce* syscall blocking.
# It defines the policy.
# Execute the actual command passed as arguments
exec $AGENT_COMMAND
# If exec fails (e.g., command not found), it will exit.
exit $?
```
**10. DEPLOYMENT NOTES:**
- **Build Command:** `npm run build` or `yarn build` (using Vite).
- **Output:** A `dist` folder containing static assets.
- **Environment Variables:** Use `.env` files for configurations if needed (e.g., API endpoints for fetching compatibility data). `VITE_APP_` prefix for Vite.
- **Hosting:** Can be deployed as a static website on Netlify, Vercel, GitHub Pages, etc.
- **`safehouse.sh` distribution:** The script should be hosted reliably (e.g., GitHub raw content URL) and the React app should provide the direct download link or instructions.
- **Performance:** Optimize React component rendering, code splitting (if app grows), and ensure efficient state management. Minimize bundle size.
- **HTTPS:** Ensure the website is served over HTTPS.
- **`package.json`:** Define necessary scripts (`dev`, `build`, `preview`).