# Secure Claude

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

- **Type:** MCP server
- **Install:** `agentstack add mcp-kummahiih-secure-claude`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [kummahiih](https://agentstack.voostack.com/s/kummahiih)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [kummahiih](https://github.com/kummahiih)
- **Source:** https://github.com/kummahiih/secure-claude

## Install

```sh
agentstack add mcp-kummahiih-secure-claude
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/gsd-build/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.
```bash
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`:
```bash
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).
```bash
./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/WORKSPACE_INTERFACE.md](docs/WORKSPACE_INTERFACE.md) for the full contract and extension guide.

**4. Run the Cluster and Execute**
Start the infrastructure, create a plan, and unleash the agent.
```bash
./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).

```text
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`.

```bash
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:
```bash
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.

```bash
./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](https://github.com/kummahiih/secure-coder) and [secure-mcp](https://github.com/kummahiih/secure-mcp).
* MCP security provided by [mcp-watchdog](https://github.com/bountyyfi/mcp-watchdog) by Bountyy Oy.
* Planning task structure inspired by [get-shit-done](https://github.com/gsd-build/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](https://github.com/kummahiih)
- **Source:** [kummahiih/secure-claude](https://github.com/kummahiih/secure-claude)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-kummahiih-secure-claude
- Seller: https://agentstack.voostack.com/s/kummahiih
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.