Skip to content

Add Z.ai / GLM 5.2 support as alternative agent backend #92

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
valITino merged 1 commit into from
Jun 23, 2026
Merged

Add Z.ai / GLM 5.2 support as alternative agent backend #92

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .env.example
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,12 @@
# The key is passed to Claude Code as ANTHROPIC_AUTH_TOKEN at runtime.
# Get your key at: https://platform.deepseek.com/api_keys
# DEEPSEEK_API_KEY=sk-...
#
# Z.ai / GLM 5.2 container (--profile zai / `make zai`):
# Runs the Claude Code image pointed at Z.ai's Anthropic-compatible API.
# The key is passed to Claude Code as ANTHROPIC_AUTH_TOKEN at runtime.
# Get your key at: https://z.ai/manage-apikey/apikey-list
# ZAI_API_KEY=

# ══════════════════════════════════════════════════════════════════════
# OPTIONAL — Defaults work out of the box
Expand Down
16 changes: 16 additions & 0 deletions DOCKER.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -197,6 +197,7 @@ Skills are available in the container via two mechanisms:
| `portainer` | `portainer/portainer-ce:latest` | `9443` | default | Docker management UI (HTTPS) |
| `claude-code` | `crhacky/blhackbox:claude-code` | — | `claude-code` | Claude Code CLI client (Docker) |
| `deepseek` | `crhacky/blhackbox:claude-code` | — | `deepseek` | DeepSeek agent — Claude Code image + DeepSeek API (Docker) |
| `zai` | `crhacky/blhackbox:claude-code` | — | `zai` | Z.ai / GLM 5.2 agent — Claude Code image + Z.ai API (Docker) |
| `mcp-gateway` | `docker/mcp-gateway:latest` | `8080` | `gateway` | Single MCP entry point (host clients) |
| `neo4j` | `neo4j:5` | `7474` / `7687` | `neo4j` | Cross-session knowledge graph |

Expand Down Expand Up @@ -245,6 +246,7 @@ Requires `--profile gateway` (`make up-gateway`).
|:--|:--|:--|
| `ANTHROPIC_API_KEY` | — | Required for the Claude Code container (`--profile claude-code`) |
| `DEEPSEEK_API_KEY` | — | Required for the DeepSeek container (`--profile deepseek`); passed to Claude Code as `ANTHROPIC_AUTH_TOKEN` |
| `ZAI_API_KEY` | — | Required for the Z.ai / GLM 5.2 container (`--profile zai`); passed to Claude Code as `ANTHROPIC_AUTH_TOKEN` |
| `MCP_GATEWAY_PORT` | `8080` | MCP Gateway host port (optional) |
| `MSF_TIMEOUT` | `300` | Metasploit command timeout in seconds |
| `NEO4J_URI` | `bolt://neo4j:7687` | Neo4j connection URI (optional) |
Expand Down Expand Up @@ -321,6 +323,20 @@ The Claude Code container includes the full skills system. Skills (`.claude/skil

The `deepseek` profile runs the **same Claude Code image** as `--profile claude-code`, only with environment variables that route the model backend to DeepSeek's Anthropic-compatible endpoint. There is no separate image to build, push, or maintain, and the full skills system (slash commands) works exactly as it does with Claude Code. Launch it with `make deepseek` or `docker compose --profile deepseek run --rm deepseek`.

### Z.ai / GLM 5.2 — `zai` profile (reuses `crhacky/blhackbox:claude-code`)

| | |
|:--|:--|
| **Image** | Same as Claude Code — `crhacky/blhackbox:claude-code` (no separate image) |
| **Agent** | Claude Code CLI, pointed at the Z.ai API |
| **Entrypoint** | `claude-code-entrypoint.sh` (health checks + launch) |
| **MCP config** | Direct Streamable HTTP to each server (no gateway dependency) |
| **Provider** | `ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic` + `ANTHROPIC_AUTH_TOKEN` from `ZAI_API_KEY` env (never written to disk) |
| **Models** | `glm-5.2` (default), `glm-4.5-air` (Haiku tier) — per [Z.ai's Claude Code guide](https://docs.z.ai/devpack/tool/claude) |
| **Requires** | `ZAI_API_KEY` in `.env` |

The `zai` profile runs the **same Claude Code image** as `--profile claude-code`, only with environment variables that route the model backend to Z.ai's Anthropic-compatible endpoint. There is no separate image to build, push, or maintain, and the full skills system (slash commands) works exactly as it does with Claude Code. Launch it with `make zai` or `docker compose --profile zai run --rm zai`.

---

## Portainer
Expand Down
22 changes: 17 additions & 5 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
.PHONY: help setup up up-full up-gateway down logs test test-local lint format clean nuke \
pull status health portainer gateway-logs \
claude-code deepseek \
claude-code deepseek zai \
neo4j-browser logs-kali \
logs-wireshark logs-screenshot \
restart-kali \
Expand All @@ -27,7 +27,7 @@ up: ## Start default stack (7 containers: Kali, WireMCP, Screenshot, HexStrike A
$(COMPOSE) up -d

down: ## Stop all services (default + auxiliary profiles)
$(COMPOSE) --profile gateway --profile neo4j --profile claude-code --profile deepseek down
$(COMPOSE) --profile gateway --profile neo4j --profile claude-code --profile deepseek --profile zai down

logs: ## Tail logs from all services
$(COMPOSE) logs -f
Expand Down Expand Up @@ -83,15 +83,15 @@ boaz-bridge: ## Run local BOAZ MCP helper server
python boaz-mcp/server.py

clean: ## Remove containers, volumes, networks, and build artifacts (keeps images)
$(COMPOSE) --profile gateway --profile neo4j --profile claude-code --profile deepseek down -v --remove-orphans
$(COMPOSE) --profile gateway --profile neo4j --profile claude-code --profile deepseek --profile zai down -v --remove-orphans
find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
rm -rf dist/ build/ *.egg-info

nuke: ## Full cleanup: containers + volumes + ALL images (frees max disk space)
@echo "\033[1;33m WARNING: This will remove ALL blhackbox containers, volumes, AND images.\033[0m"
@echo "\033[2m You will need to 'docker compose pull' or 'docker compose build' again.\033[0m"
@echo ""
$(COMPOSE) --profile gateway --profile neo4j --profile claude-code --profile deepseek down -v --remove-orphans --rmi all
$(COMPOSE) --profile gateway --profile neo4j --profile claude-code --profile deepseek --profile zai down -v --remove-orphans --rmi all
@echo ""
@echo "\033[2m Pruning dangling images and build cache...\033[0m"
docker image prune -f
Expand Down Expand Up @@ -131,12 +131,24 @@ deepseek: ## Launch the DeepSeek agent in a Docker container (reuses the Claude
@echo ""
$(COMPOSE) --profile deepseek run --rm deepseek

# ── Z.ai / GLM 5.2 (Docker — Claude Code pointed at the Z.ai API) ──
zai: ## Launch the Z.ai / GLM 5.2 agent in a Docker container (reuses the Claude Code image)
$(COMPOSE) --profile zai pull zai || $(COMPOSE) --profile claude-code build claude-code
@echo ""
@echo "\033[1m Pre-flight Container Status\033[0m"
@echo "\033[2m ──────────────────────────────────────\033[0m"
@$(COMPOSE) ps --format "table {{.Name}}\t{{.Status}}" 2>/dev/null || $(COMPOSE) ps
@echo ""
@echo "\033[2m Waiting for all dependencies to become healthy...\033[0m"
@echo ""
$(COMPOSE) --profile zai run --rm zai

# ── Health & Status ──────────────────────────────────────────────
status: ## Health status of all containers
@echo ""
@echo "\033[1m blhackbox Container Status\033[0m"
@echo "\033[2m ──────────────────────────────────────\033[0m"
@$(COMPOSE) --profile gateway --profile neo4j --profile claude-code --profile deepseek ps --format "table {{.Name}}\t{{.Status}}\t{{.Ports}}" 2>/dev/null || $(COMPOSE) ps
@$(COMPOSE) --profile gateway --profile neo4j --profile claude-code --profile deepseek --profile zai ps --format "table {{.Name}}\t{{.Status}}\t{{.Ports}}" 2>/dev/null || $(COMPOSE) ps
@echo ""

health: ## Quick health check of all MCP servers
Expand Down
38 changes: 34 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@
|---|---|
| **Getting Started** | [How It Works](#how-it-works) · [Architecture](#architecture) · [Prerequisites](#prerequisites) · [Installation](#installation) |
| **Skills** | [Skills Overview](#skills--slash-commands) · [Available Skills](#available-skills) · [How Skills Work](#how-skills-work) |
| **Tutorials** | [Claude Code (Docker)](#tutorial-1-claude-code-docker--recommended) · [DeepSeek (Docker)](#tutorial-1b-deepseek-docker) · [Claude Code (Web)](#tutorial-2-claude-code-web) · [Claude Desktop](#tutorial-3-claude-desktop-host--gateway) · [ChatGPT / OpenAI](#tutorial-4-chatgpt--openai-host--gateway) |
| **Tutorials** | [Claude Code (Docker)](#tutorial-1-claude-code-docker--recommended) · [DeepSeek (Docker)](#tutorial-1b-deepseek-docker) · [Z.ai / GLM 5.2 (Docker)](#tutorial-1c-zai--glm-52-docker) · [Claude Code (Web)](#tutorial-2-claude-code-web) · [Claude Desktop](#tutorial-3-claude-desktop-host--gateway) · [ChatGPT / OpenAI](#tutorial-4-chatgpt--openai-host--gateway) |
| **Advanced** | [Advanced Usage & FAQ](#advanced-usage--faq) |
| **Reference** | [Components](#components) · [Output Files](#output-files) · [CLI Reference](#cli-reference) · [Makefile Shortcuts](#makefile-shortcuts) · [Docker Hub Images](#docker-hub-images) |
| **Operations** | [Prompt Flow](#how-prompts-flow-through-the-system) · [MCP Gateway](#do-i-need-the-mcp-gateway) · [Portainer Setup](#portainer-setup) · [Neo4j](#neo4j-optional) · [Troubleshooting](#troubleshooting) |
Expand Down Expand Up @@ -309,7 +309,7 @@ cd blhackbox
The setup wizard walks you through everything interactively:

1. **Check prerequisites** (Docker, Docker Compose, Git, disk space)
2. **Choose your AI client** — Claude (Claude Code in Docker, Claude Code Web, or Claude Desktop), ChatGPT/OpenAI, or DeepSeek. The choice decides which agent/profile starts and which key (if any) you need.
2. **Choose your AI client** — Claude (Claude Code in Docker, Claude Code Web, or Claude Desktop), ChatGPT/OpenAI, DeepSeek, or Z.ai / GLM 5.2. The choice decides which agent/profile starts and which key (if any) you need.
3. **Configure API keys with guidance** — for each key it explains what it's for, where it's used, and the exact steps to obtain it; every key is optional/skippable.
4. **Pick a knowledge graph** — none, local Neo4j (Docker), or Neo4j Aura (cloud). Aura mode walks you through `console.neo4j.io` and stores your connection details without starting a local container.
5. **Optionally add recon API keys** (WPScan, Shodan, VirusTotal, SecurityTrails) — all skippable; tools run without them.
Expand Down Expand Up @@ -426,6 +426,8 @@ You are now inside an interactive Claude Code session.

> **Prefer DeepSeek?** Set `DEEPSEEK_API_KEY` in `.env` and run `make deepseek` (or `docker compose --profile deepseek run --rm deepseek`). This runs the **same Claude Code image** pointed at DeepSeek's Anthropic-compatible API — same MCP wiring, same skills, only the model backend differs. See [Tutorial 1b](#tutorial-1b-deepseek-docker).

> **Prefer GLM 5.2 (Z.ai)?** Set `ZAI_API_KEY` in `.env` and run `make zai` (or `docker compose --profile zai run --rm zai`). This runs the **same Claude Code image** pointed at Z.ai's Anthropic-compatible API — same MCP wiring, same skills, only the model backend differs. See [Tutorial 1c](#tutorial-1c-zai--glm-52-docker).

### Step 3 — Verify the connection

```
Expand Down Expand Up @@ -496,6 +498,32 @@ The entrypoint checks each MCP server, then drops you into an interactive sessio

---

## Tutorial 1c: Z.ai / GLM 5.2 (Docker)

Prefer Z.ai's GLM 5.2 over Claude? The `zai` profile runs the **same Claude Code image** as Tutorial 1, just pointed at Z.ai's Anthropic-compatible API via `ANTHROPIC_BASE_URL` + `ANTHROPIC_AUTH_TOKEN` (following [Z.ai's Claude Code guide](https://docs.z.ai/devpack/tool/claude)). The MCP wiring, the skills system, and the entrypoint are identical — only the model backend changes. There is no separate image to build or maintain.

### Step 1 — Set your Z.ai key

Put `ZAI_API_KEY` in `.env` (subscribe to the GLM Coding Plan and create a key at [z.ai/manage-apikey/apikey-list](https://z.ai/manage-apikey/apikey-list)). `setup.sh` prompts for it, or add it manually. The key is read from the environment at runtime, passed to Claude Code as `ANTHROPIC_AUTH_TOKEN`, and never written into the image.

### Step 2 — Launch the agent

```bash
make zai
```

Or manually:

```bash
docker compose --profile zai run --rm zai
```

The entrypoint checks each MCP server, then drops you into an interactive session with all the pentest tools available. The default model is **glm-5.2** (background tasks use **glm-4.5-air**); switch the active model in-session with `/model`. For GLM 5.2's full 1M-token context window, uncomment the `glm-5.2[1m]` option in `docker-compose.yml`.

> **Note:** Because this is Claude Code under the hood, the full skills system works — `/full-pentest`, `/quick-scan`, and the rest of the slash commands behave exactly as in Tutorial 1.

---

## Tutorial 2: Claude Code (Web)

Claude Code on [claude.ai/code](https://claude.ai/code) works as a web-based coding agent. When you open this repo in a web session, the MCP server configures itself automatically.
Expand Down Expand Up @@ -762,6 +790,7 @@ STEP 7 ─ (OPTIONAL) RESULTS STORED IN NEO4J
|:--|:--:|:--|
| **Claude Code (Docker)** | No | Direct Streamable HTTP to each MCP server over Docker network |
| **DeepSeek (Docker)** | No | Claude Code image + DeepSeek API; direct Streamable HTTP to each MCP server over Docker network |
| **Z.ai / GLM 5.2 (Docker)** | No | Claude Code image + Z.ai API; direct Streamable HTTP to each MCP server over Docker network |
| **Claude Code (Web)** | No | Stdio MCP server from `.mcp.json` |
| **Claude Desktop** | **Yes** | Host GUI app → `localhost:8080/mcp` gateway |
| **ChatGPT / OpenAI** | **Yes** | Host GUI/web app → `localhost:8080/mcp` gateway |
Expand Down Expand Up @@ -883,6 +912,7 @@ blhackbox mcp # Start MCP server
| `make down` | Stop all services |
| `make claude-code` | Build and launch Claude Code in Docker |
| `make deepseek` | Launch the DeepSeek agent in Docker (Claude Code image + DeepSeek API) |
| `make zai` | Launch the Z.ai / GLM 5.2 agent in Docker (Claude Code image + Z.ai API) |
| `make status` | Container status table |
| `make health` | Quick health check of all services |
| `make test` | Run tests |
Expand Down Expand Up @@ -920,7 +950,7 @@ All custom images are published to `crhacky/blhackbox`:
| `crhacky/blhackbox:hexstrike-ai` | HexStrike Gamma API container |
| `crhacky/blhackbox:hexstrike-mcp` | Upstream HexStrike Gamma MCP server over Streamable HTTP |
| `crhacky/blhackbox:boaz-mcp` | Upstream BOAZ-MCP Gamma server over Streamable HTTP |
| `crhacky/blhackbox:claude-code` | Claude Code CLI client (direct Streamable HTTP to MCP servers); also used by the `deepseek` profile pointed at the DeepSeek API |
| `crhacky/blhackbox:claude-code` | Claude Code CLI client (direct Streamable HTTP to MCP servers); also used by the `deepseek` and `zai` profiles, pointed at the DeepSeek and Z.ai APIs |

Official images pulled directly:

Expand Down Expand Up @@ -985,7 +1015,7 @@ blhackbox/
│ ├── kali-mcp.Dockerfile Kali Linux + Metasploit Framework
│ ├── wire-mcp.Dockerfile
│ ├── screenshot-mcp.Dockerfile
│ ├── claude-code.Dockerfile MCP client container (also used by the deepseek profile)
│ ├── claude-code.Dockerfile MCP client container (also used by the deepseek and zai profiles)
│ └── claude-code-entrypoint.sh Startup script with health checks
├── kali-mcp/ Kali MCP server (70+ tools + Metasploit)
├── wire-mcp/ WireMCP server (tshark, 7 tools)
Expand Down
66 changes: 66 additions & 0 deletions docker-compose.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
# docker compose --profile gateway up -d Start with MCP Gateway
# docker compose --profile claude-code up -d Start with Claude Code container
# docker compose --profile deepseek run --rm deepseek Run the DeepSeek agent (Claude Code + DeepSeek API)
# docker compose --profile zai run --rm zai Run the Z.ai / GLM 5.2 agent (Claude Code + Z.ai API)
# docker compose --profile neo4j up -d Start with Neo4j
# docker compose build Build all custom images locally
#
Expand Down Expand Up @@ -432,6 +433,71 @@ services:
networks:
- blhackbox_net

# -- Z.ai / GLM 5.2 (OPTIONAL) ---------------------------------------------
# Z.ai (GLM) agent running inside Docker -- no host install needed.
# Enable with: docker compose --profile zai run --rm zai
# (or `make zai`)
#
# Reuses the Claude Code image and points it at Z.ai's Anthropic-compatible
# API via ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN, following Z.ai's official
# Claude Code guide:
# https://docs.z.ai/devpack/tool/claude
# Same MCP wiring, skills, and entrypoint as the claude-code service — only the
# model backend differs, so there is no separate image to build or maintain.
# Requires ZAI_API_KEY (read from env, never written to disk).
zai:
image: crhacky/blhackbox:claude-code
container_name: blhackbox-zai
profiles: ["zai"]
stdin_open: true
tty: true
environment:
# Route Claude Code at Z.ai's Anthropic-compatible endpoint.
# ANTHROPIC_AUTH_TOKEN is sent as the Authorization: Bearer header.
ANTHROPIC_BASE_URL: "https://api.z.ai/api/anthropic"
ANTHROPIC_AUTH_TOKEN: "${ZAI_API_KEY:-}"
# Map Claude's model tiers onto GLM models (per Z.ai's Claude Code guide).
# Switch the active model in-session with /model.
ANTHROPIC_MODEL: "glm-5.2"
ANTHROPIC_DEFAULT_OPUS_MODEL: "glm-5.2"
ANTHROPIC_DEFAULT_SONNET_MODEL: "glm-5.2"
ANTHROPIC_DEFAULT_HAIKU_MODEL: "glm-4.5-air"
# GLM reasoning can run long; Z.ai recommends a generous client timeout.
API_TIMEOUT_MS: "3000000"
# Optional: use GLM 5.2's full 1M-token context (uncomment both lines).
# ANTHROPIC_DEFAULT_SONNET_MODEL: "glm-5.2[1m]"
# CLAUDE_CODE_AUTO_COMPACT_WINDOW: "1000000"
# Don't phone home to Anthropic for telemetry/auto-update.
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1"
# Bypass egress proxies (e.g. GitHub Codespaces) for internal Docker traffic
no_proxy: "mcp-gateway,kali-mcp,wire-mcp,screenshot-mcp,hexstrike-ai,hexstrike-bridge-mcp,boaz-mcp,localhost,127.0.0.1"
NO_PROXY: "mcp-gateway,kali-mcp,wire-mcp,screenshot-mcp,hexstrike-ai,hexstrike-bridge-mcp,boaz-mcp,localhost,127.0.0.1"
dns:
- 8.8.8.8
- 1.1.1.1
volumes:
- ./output/screenshots:/tmp/screenshots:ro
- ./output/reports:/root/reports
- ./output/sessions:/root/results
# Shared working data from Kali MCP (recon files, tool artifacts)
- shared-output:/root/kali-data:ro
# Mount skills and project instructions so Claude Code discovers them
- ./.claude/skills:/root/.claude/skills:ro
- ./CLAUDE.md:/root/CLAUDE.md:ro
depends_on:
kali-mcp:
condition: service_healthy
wire-mcp:
condition: service_healthy
screenshot-mcp:
condition: service_healthy
hexstrike-bridge-mcp:
condition: service_healthy
boaz-mcp:
condition: service_healthy
networks:
- blhackbox_net

# -- PORTAINER CE ----------------------------------------------------------
# Web UI for container management -- https://localhost:9443
# Source: https://github.com/portainer/portainer
Expand Down
Loading