Secure Claude

Secure Claude Code Cluster

> A hardened, containerized environment for running Claude Code as an AI agent with access to local tools via the Model Context Protocol (MCP).

Why secure-claude?

AI coding agents are highly privileged targets. Recent real-world attacks prove that you cannot rely on an AI to "behave safely." secure-claude relies on hard architectural boundaries instead.

• Stopping the Git Hook Worms (MCP Sandboxing): In early 2026, malware worms specifically targeted AI tool configs to install persistent, malicious Git hooks. We use strictly managed MCP services to sandbox file-system access, physically preventing the AI from modifying hidden .git directories or installing these hooks.
• Stopping Infostealers & Agentic XSS (Caddy Egress Filtering): Attackers use hidden prompt injections to trick agents into leaking data, and supply chain attacks (like the massive LiteLLM infostealer in March 2026) silently sweep environments for secrets to send to attacker-controlled servers. Caddy acts as a strict egress firewall for the agent and LiteLLM. Even if the proxy is poisoned or the agent is hijacked, unauthorized outbound network requests are completely blocked.

Token usage optimization

As this is a study project i have tried several token usage optimizations. One of such is plan-then-execute workflow. You create a structured plan with plan.sh, and the agent executes tasks one at a time with query.sh. This planning structure is inspired by get-shit-done.

---

Security Guarantees

The cluster-level guarantees are designed for maximum defense-in-depth:

• Credential Isolation: The agent operates using an ephemeral DYNAMIC_AGENT_KEY, never touching your real ANTHROPIC_API_KEY.
• Network Isolation: Both claude-server and the proxy live exclusively on an internal network (int_net). The proxy intentionally has no direct external network access.
• Filesystem Jail: Workspace access is governed by Go's os.OpenRoot at /workspace, blocking path traversal attacks at the runtime level.
• Per-Service Auth: Strict token scoping is enforced. CLAUDE_API_TOKEN is required for ingress, while individual backend servers require specific tokens (MCP_API_TOKEN, PLAN_API_TOKEN, TESTER_API_TOKEN, GIT_API_TOKEN, LOG_API_TOKEN).
• Zero-Privilege Compute: All containers run as non-root (UID 1000) with cap_drop: ALL. They are strictly bound by memory, CPU, and PID limits.
• Test Isolation: The tester-server runs tests as subprocesses with the workspace mounted as read-only.
• TLS Everywhere: Uses an internal CA to ensure all service-to-service communication occurs over HTTPS.
• MCP Security Proxy (mcp-watchdog): All tool use is actively monitored. The proxy actively scans and blocks over 40 distinct attack classes on all JSON-RPC traffic between the agent and its tools.

---

Quick Start

1. Clone the repository Be sure to include submodules to pull in the agent, planner, and tester services.

git clone --recurse-submodules [https://github.com/kummahiih/secure-claude](https://github.com/kummahiih/secure-claude)
cd secure-claude
cp .secrets.env.example .secrets.env

(If you already cloned without submodules, run: git submodule update --init)

2. Configure your API Keys Add your Anthropic key to .secrets.env:

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...          # Optional: required only for codex-server

(To use a Pro subscription OAuth token, run npm install -g @anthropic-ai/claude-code, then claude login and claude setup-token, and copy the token into your .secrets.env)

3. Initialize and Test Set up the environment and verify unit tests (no Docker or secrets required for tests).

./init_build.sh
./test.sh

> Note: test.sh in each workspace sub-repo runs inside the tester-server container (built from cluster/Dockerfile.tester). The container pre-installs Go 1.26 and Python 3.12/pytest. If your project's tests require additional runtimes (e.g. Node.js, Ruby), you must add install steps to Dockerfile.tester and rebuild the image (docker compose build tester-server). See [docs/WORKSPACEINTERFACE.md](docs/WORKSPACEINTERFACE.md) for the full contract and extension guide.

4. Run the Cluster and Execute Start the infrastructure, create a plan, and unleash the agent.

./run.sh
./plan.sh claude-sonnet-4-6 "add input validation to the read endpoint"
./query.sh claude-sonnet-4-6 "work on the current tasks"

---

System Architecture

The environment relies on nine containers orchestrated by Docker Compose. The /workspace mount is swappable, allowing you to point it at any repository that follows the [workspace interface spec](docs/WORKSPACE_INTERFACE.md).

Host / Network
└─> Caddy:8443 (TLS 1.3 + reverse proxy)
     ├─> claude-server:8000 (FastAPI + Claude Code)
     │    ├─> MCP stdio servers (inside claude-server)
     │    └─> proxy:4000 (LiteLLM) ──> Anthropic API (no direct external access; int_net only)
     ├─> codex-server:8000 (FastAPI + OpenAI Codex)
     │    ├─> MCP stdio servers (inside codex-server)
     │    └─> proxy:4000 (LiteLLM) ──> OpenAI API (via caddy-sidecar)
     ├─> mcp-server:8443 (Go REST, filesystem jail)
     │    └─> /workspace (bind mount → active sub-repo)
     ├─> plan-server:8443 (Python REST, plan state)
     │    └─> /plans (bind mount → plans/)
     ├─> tester-server:8443 (Go REST, test runner)
     │    └─> /workspace:ro (bind mount → active sub-repo)
     ├─> git-server:8443 (Go REST, git operations)
     │    ├─> /workspace:ro (bind mount → active sub-repo)
     │    └─> /gitdir (bind mount → active sub-repo .git, rw)
     └─> log-server:8443 (Go REST, structured session logs)
          └─> /logs (bind mount → logs/)

Sub-Repositories

The architecture is modular, split across dedicated sub-repositories containing their own architecture (docs/CONTEXT.md) and roadmap (docs/PLAN.md) files:

• [secure-claude-agent](cluster/agent/): MCP tool servers (files, git, docs, planner, tester, logs wrappers) + Claude Code integration.
• [secure-claude-planner](cluster/planner/): Plan-server REST API for task state management.
• [secure-claude-tester](cluster/tester/): Tester-server REST API for running workspace tests.

The parent repo also contains cluster/log-server/ — a Go REST service that stores and queries structured session logs (LLM calls, tool calls, file reads, test runs). It is not a separate submodule because it is infrastructure owned by the parent, like plan-server.

---

🛠️ Operational Commands

| Command | Description | | :--- | :--- | | ./run.sh | Start cluster (generates certs + tokens) | | ./plan.sh "" | Create a plan without executing code | | ./query.sh "" | Send a query or execute a task | | ./dev-loop.sh | Automated plan-execute loop (runs until complete/blocked) | | ./logs.sh | Tail all container logs | | ./test.sh | Run unit tests (no Docker/network needed) | | ./test-integration.sh | Run CVE audits + Docker integration tests |

---

Switching Workspaces

The workspace is a simple symlink located at cluster/workspace. Because Docker Compose mounts via ./workspace, you can change the target dynamically without editing your docker-compose.yml.

cd cluster
ln -sfn planner workspace      # Example: switch from agent to planner

Note: Restart the cluster after switching workspaces. Ensure your target repository follows the [workspace interface](docs/WORKSPACE_INTERFACE.md).

Self-Development Mode: To have the agent work on the secure-claude repo itself, clone a separate working copy and point the symlink at it:

git clone --recurse-submodules [https://github.com/kummahiih/secure-claude](https://github.com/kummahiih/secure-claude) /path/to/secure-claude-work
cd /path/to/secure-claude/cluster
ln -sfn /path/to/secure-claude-work workspace

---

Security & Quality Auditing

We take security seriously. You can audit the entire stack locally.

./test.sh                 # Unit tests — runnable from a fresh clone
./test-integration.sh     # Full security + integration suite

Audit Tools Included:

• pytest & go test: Unit testing across agent, planner, fileserver, and tester modules.
• pip-audit, govulncheck, npm audit: Comprehensive CVE scanning for Python, Go, and JS dependencies.
• hadolint: Dockerfile linting for all images.
• trivy: Misconfiguration scanning for docker-compose.yml and images.

---

Credits

• Architecture inspired by secure-coder and secure-mcp.
• MCP security provided by mcp-watchdog by Bountyy Oy.
• Planning task structure inspired by get-shit-done by TÂCHES (MIT).
• Some of the code was produced using Google Gemini, some of it was done using Claude.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kummahiih
• Source: kummahiih/secure-claude
• License: MIT

Install and usage instructions live in the source repository linked above.