coding-guardrails 0.2.0

Safe, reliable local coding agent backend. Forge + coding-specific guardrails.

coding-guardrails

Safe, reliable local coding agent backend. Open-source, pip-installable.

coding-guardrails is a proxy that sits between your coding agent and a local LLM, adding two layers of protection:

1. Forge (Layer 1) — Rescue parsing, retries, validation. Makes local models actually work for tool calling.
2. Coding Guardrails (Layer 2) — Read-before-edit, path safety, command blocking, secret masking, test-after-change suggestions.

One command to go from "I have a GPU" to "I have a safe local coding agent backend."

Quick Start

# Install
pip install coding-guardrails

# Start llama-server (your local LLM backend)
llama-server -m Qwen3.5-9B-UD-Q4_K_XL.gguf --jinja --flash-attn auto \
  --port 8080 -c 200000 --spec-type draft-mtp -np 1

# Start the proxy
coding-guardrails serve \
  --backend-url http://localhost:8080 \
  --model Qwen3.5-9B-UD-Q4_K_XL \
  --port 8081

# Point your agent at http://localhost:8081/v1

That's it. Your agent sees a standard OpenAI-compatible API.

What It Blocks

Rule	Blocks	Example
Path safety	Reads/writes outside workspace	read_file("/etc/passwd") ❌
Command safety	Destructive shell commands	bash("rm -rf /") ❌
Secret detection	API keys, tokens, private keys	bash("export AWS_SECRET_ACCESS_KEY=...") ❌
Prerequisites	Edit before read (soft nudge)	edit_file() without read_file() ⚠️
Sequencing	Missing test runs (soft nudge)	Edit without pytest ⚠️
Tool resolution	Empty/error results (soft nudge)	Tool returns "" ⚠️

All rules are configurable. See docs/rules.md.

Supported Models

Optimized for consumer GPUs (24 GB VRAM) with llama-server:

Model	VRAM	Context	Speed	Notes
Qwen3.5-9B ⭐	18 GB	200K	~53 tok/s	Dense, MTP, best quality
Gemma 4 26B-A4B	21 GB	200K	~50 tok/s	MoE, vision, Google
Qwen3.6-35B-A3B	22.5 GB	32K	~22 tok/s	Legacy

Works with any OpenAI-compatible backend. See docs/models.md.

Agent Setup

Point any OpenAI-compatible agent at http://localhost:8081/v1:

• Pi — api_base: "http://localhost:8081/v1"
• Claude Code — OPENAI_BASE_URL=http://localhost:8081/v1
• OpenCode — add provider with baseURL: http://localhost:8081/v1
• Aider — OPENAI_API_BASE=http://localhost:8081/v1
• Continue — "apiBase": "http://localhost:8081/v1"
• Cline / Roo — set API base in settings

See docs/agents.md for detailed setup guides.

Configuration

Create a guardrail-config.yaml (or use defaults):

path_safety:
  enabled: true
  blocked_prefixes: ["/etc/", "/sys/", "/proc/"]

command_safety:
  enabled: true
  strength: hard  # hard = block, soft = warn

secrets:
  enabled: true
  strength: hard
  mask_value: "[REDACTED]"

Pass with --config guardrail-config.yaml.

Architecture

Agent → coding-guardrails (:8081) → llama-server (:8080) → GPU
            │
            ├─ Layer 1 (Forge): rescue, validate, retry
            └─ Layer 2 (Guardrails): 6 safety rules

See docs/architecture.md for details.

Docker

docker compose up

Or standalone:

docker run -p 8081:8081 ghcr.io/stawils/coding-guardrails:latest \
  serve --backend-url http://host.docker.internal:8080 --model your-model

Eval

coding-guardrails eval --backend-url http://localhost:8081

Runs scenarios from eval/scenarios/ and reports pass/fail by category.

Development

git clone https://github.com/stawils/coding-guardrails.git
cd coding-guardrails
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"

# Run tests
pytest tests/unit/ -v

# Run against live backend
pytest tests/integration/ -v -m integration

License

MIT