ContainerClaw is a secure, defense-in-depth, and containerized runtime for autonomous AI agents. Unlike traditional agents that run natively on your machine, ContainerClaw executes in an isolated sandbox, shielding your host files and credentials from prompt-injection attacks and rouge AI behavior.

The Dockerfile requires compiling a fluss-rust repo as the Python library is not ready. Rust must be installed on your machine to build these components. This is done via a git submodule located in ./vendor/fluss-rust.

git clone https://github.com/qzyu999/containerclaw.git cd containerclaw

git submodule update --init --recursive

The second command will also git clone the required submodule for the Python fluss library to work correctly.

• Docker & Docker Compose
• A Gemini API Key (from Google AI Studio)
• Rust (Required to build dependencies)

ContainerClaw uses a centralized config.yaml to define your agent roster, credentials, and provider endpoints.

1. Configure System Defaults: Edit config.yaml in the project root. By default, it supports local inference (MLX/vLLM) and Cloud APIs (Gemini/OpenAI).
2. Add Secrets: Create a secrets directory. Add your text files exactly matching the secret names referenced in config.yaml:

   mkdir -p secrets
   echo "your-api-key-here" > secrets/gemini_api_key.txt

You can also update your local git to untrack those files after adding your API key: bash git update-index --skip-worktree secrets/gemini_api_key.txt 3. Customize Agents (Optional): Define new agents in the agents.roster section of config.yaml. You can assign different models or providers securely on a per-agent basis.

Use the provided claw.sh script to manage the lifecycle of your agent sessions.

# Start a new session
./claw.sh up my-first-session

# View the status of the containers
docker ps

In this Phase 1 MVP, the Agent is a background service. You can interact with the components:

• Dashboard: Open http://localhost:3000 in your browser to interact with the modern React dashboard.
• Log Streaming: Follow the live logs to see what's happening:

  ./claw.sh logs

• Agent Sandbox: The agent's workspace is mirrored to your local directory. Any files the agent creates will appear in your project root, but it cannot access files outside this folder.

To stop the session gracefully:

./claw.sh down

ContainerClaw follows a Microservices Security Pattern:

1. Isolated Agent: The agent runs as a rootless user with a restrictive Seccomp profile and no internet access. It is restricted to an internal Docker network.
2. LLM Gateway: Only this hardened container has access to your API keys (via Docker Secrets). The agent must ask the Gateway to make LLM calls on its behalf.
3. Audited Logs: All agent actions are designed to be streamed to an external Log Streamer (Apache Fluss) so they cannot be tampered with by a compromised agent.

• agent/: The autonomous execution engine.
• llm-gateway/: The credential-isolated proxy for LLM APIs.
• bridge/: Flask proxy bridging gRPC streams to SSE for the browser.
• ui/: Modern Vite/React frontend dashboard.
• proto/: gRPC definitions for internal communication.
• claw.sh: The main control script.

• Phase 2: Implement full gRPC protocol for Agent ↔ UI interaction.
• Phase 2b: Session Persistence — the agent resumes its thought process after a restart.
• Phase 3: Real-time log processing and anomaly detection via Apache Fluss.