diff --git a/.claude/skills/convert-to-docker/SKILL.md b/.claude/skills/convert-to-docker/SKILL.md index abc382c..51d73b2 100644 --- a/.claude/skills/convert-to-docker/SKILL.md +++ b/.claude/skills/convert-to-docker/SKILL.md @@ -36,7 +36,7 @@ If Docker is not installed: Edit `src/container-runner.ts`: -### 1a. Update module comment (line 3) +### 1a. Update module comment (around line 3) ```typescript // Before: diff --git a/.claude/skills/setup/SKILL.md b/.claude/skills/setup/SKILL.md index 2e3ba9e..b4d6507 100644 --- a/.claude/skills/setup/SKILL.md +++ b/.claude/skills/setup/SKILL.md @@ -13,15 +13,40 @@ Run all commands automatically. Only pause when user action is required (scannin npm install ``` -## 2. Install Apple Container +## 2. Install Container Runtime -Check if Apple Container is installed: +First, detect the platform and check what's available: ```bash -which container && container --version || echo "Not installed" +echo "Platform: $(uname -s)" +which container && echo "Apple Container: installed" || echo "Apple Container: not installed" +which docker && docker info >/dev/null 2>&1 && echo "Docker: installed and running" || echo "Docker: not installed or not running" ``` -If not installed, tell the user: +### If NOT on macOS (Linux, etc.) + +Apple Container is macOS-only. Use Docker instead. + +Tell the user: +> You're on Linux, so we'll use Docker for container isolation. Let me set that up now. + +**Use the `/convert-to-docker` skill** to convert the codebase to Docker, then continue to Section 3. + +### If on macOS + +**If Apple Container is already installed:** Continue to Section 3. + +**If Apple Container is NOT installed:** Ask the user: +> NanoClaw needs a container runtime for isolated agent execution. You have two options: +> +> 1. **Apple Container** (default) - macOS-native, lightweight, designed for Apple silicon +> 2. **Docker** - Cross-platform, widely used, works on macOS and Linux +> +> Which would you prefer? + +#### Option A: Apple Container + +Tell the user: > Apple Container is required for running agents in isolated environments. > > 1. Download the latest `.pkg` from https://github.com/apple/container/releases @@ -39,6 +64,13 @@ container --version **Note:** NanoClaw automatically starts the Apple Container system when it launches, so you don't need to start it manually after reboots. +#### Option B: Docker + +Tell the user: +> You've chosen Docker. Let me set that up now. + +**Use the `/convert-to-docker` skill** to convert the codebase to Docker, then continue to Section 3. + ## 3. Configure Claude Authentication Ask the user: @@ -95,10 +127,14 @@ Build the NanoClaw agent container: This creates the `nanoclaw-agent:latest` image with Node.js, Chromium, Claude Code CLI, and agent-browser. -Verify the build succeeded (the `container images` command may not work due to a plugin issue, so we verify by running a simple test): +Verify the build succeeded by running a simple test (this auto-detects which runtime you're using): ```bash -echo '{}' | container run -i --entrypoint /bin/echo nanoclaw-agent:latest "Container OK" || echo "Container build failed" +if which docker >/dev/null 2>&1 && docker info >/dev/null 2>&1; then + echo '{}' | docker run -i --entrypoint /bin/echo nanoclaw-agent:latest "Container OK" || echo "Container build failed" +else + echo '{}' | container run -i --entrypoint /bin/echo nanoclaw-agent:latest "Container OK" || echo "Container build failed" +fi ``` ## 5. WhatsApp Authentication @@ -363,7 +399,9 @@ The user should receive a response in WhatsApp. **Service not starting**: Check `logs/nanoclaw.error.log` **Container agent fails with "Claude Code process exited with code 1"**: -- Ensure Apple Container is running: `container system start` +- Ensure the container runtime is running: + - Apple Container: `container system start` + - Docker: `docker info` (start Docker Desktop on macOS, or `sudo systemctl start docker` on Linux) - Check container logs: `cat groups/main/logs/container-*.log | tail -50` **No response to messages**: diff --git a/README.md b/README.md index bcccfda..0c0644f 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@
- My personal Claude assistant that runs securely in Apple containers. Lightweight and built to be understood and customized for your own needs. + My personal Claude assistant that runs securely in containers. Lightweight and built to be understood and customized for your own needs.
## Why I Built This @@ -26,7 +26,7 @@ Then run `/setup`. Claude Code handles everything: dependencies, authentication, **Small enough to understand.** One process, a few source files. No microservices, no message queues, no abstraction layers. Have Claude Code walk you through it. -**Secure by isolation.** Agents run in Linux containers (Apple Container). They can only see what's explicitly mounted. Bash access is safe because commands run inside the container, not on your Mac. +**Secure by isolation.** Agents run in Linux containers (Apple Container on macOS, or Docker). They can only see what's explicitly mounted. Bash access is safe because commands run inside the container, not on your host. **Built for one user.** This isn't a framework. It's working software that fits my exact needs. You fork it and have Claude Code make it match your exact needs. @@ -47,7 +47,7 @@ Then run `/setup`. Claude Code handles everything: dependencies, authentication, - **Main channel** - Your private channel (self-chat) for admin control; every other group is completely isolated - **Scheduled tasks** - Recurring jobs that run Claude and can message you back - **Web access** - Search and fetch content -- **Container isolation** - Agents sandboxed in Apple containers +- **Container isolation** - Agents sandboxed in Apple Container (macOS) or Docker (macOS/Linux) - **Optional integrations** - Add Gmail (`/add-gmail`) and more via skills ## Usage @@ -105,10 +105,10 @@ Skills we'd love to see: ## Requirements -- macOS Tahoe (26) or later - runs great on Mac Mini +- macOS or Linux - Node.js 20+ - [Claude Code](https://claude.ai/download) -- [Apple Container](https://github.com/apple/container) +- [Apple Container](https://github.com/apple/container) (macOS) or [Docker](https://docker.com/products/docker-desktop) (macOS/Linux) ## Architecture @@ -133,11 +133,11 @@ Because I use WhatsApp. Fork it and run a skill to change it. That's the whole p **Why Apple Container instead of Docker?** -Lightweight, fast, and built into macOS. Requires macOS Tahoe and runs great on a Mac Mini. Contribute a skill to convert to Docker if you want Docker. +On macOS, Apple Container is lightweight, fast, and optimized for Apple silicon. But Docker is also fully supported—during `/setup`, you can choose which runtime to use. On Linux, Docker is used automatically. **Can I run this on Linux?** -Yes. Run Claude Code and say "make this run on Linux." ~30 min of back-and-forth and it'll work. When you're done, ask Claude to create a skill explaining how to make it work on Linux, then contribute the skill back to the project. +Yes. Run `/setup` and it will automatically configure Docker as the container runtime. Thanks to [@dotsetgreg](https://github.com/dotsetgreg) for contributing the `/convert-to-docker` skill. **Is this secure?**