Skip to content

AgentGuardHQ/shellforge

BranchesTags

Repository files navigation

ShellForge

Governed local AI agents — one Go binary, zero cloud.

Go GitHub Pages License: MIT AgentGuard

Run autonomous AI agents on your machine with policy enforcement on every tool call. No cloud. No API keys. No data leaves your laptop.

Website · Docs · Roadmap · AgentGuard

ShellForge — Local Governed Agent Runtime

Quick Start (Mac)

1. Install ShellForge

brew tap AgentGuardHQ/tap
brew install shellforge

Or from source: git clone https://github.com/AgentGuardHQ/shellforge.git && cd shellforge && go build -o shellforge ./cmd/shellforge/

2. Install Ollama (if you haven't already)

brew install ollama
ollama serve                     # start the model server (leave running)

3. Pull a model

ollama pull qwen3:8b             # 8B — good balance (needs ~6GB RAM)
# or: ollama pull qwen3:30b      # 30B — best quality (needs ~19GB, M4 Pro recommended)
# or: ollama pull qwen3:1.7b     # 1.7B — fastest, minimal RAM

4. Run setup inside any repo

cd ~/your-project                # navigate to any repo you want to work in
shellforge setup                 # creates agentguard.yaml + output dirs

This creates agentguard.yaml (governance policy) in your project root. Edit it to customize which actions are allowed/denied.

5. Run an agent

shellforge agent "describe what this project does"
shellforge agent "find test gaps and suggest improvements"
shellforge agent "create a hello world program"

Every tool call (file reads, writes, shell commands) passes through governance before execution.

Requirements: macOS (Apple Silicon or Intel) or Linux

What Is ShellForge?

ShellForge is a governed agent runtime — not an agent framework, not an orchestration layer, not a prompt wrapper.

It sits between any agent driver and the real world. The agent decides what it wants to do. ShellForge decides whether it's allowed.

Agent Driver (Goose, Claude Code, Copilot CLI)
  → ShellForge Governance (allow / deny / correct)
    → Your Environment (files, shell, git)

The core insight: ShellForge's value is governance, not the agent loop. Goose handles local agent execution. Dagu handles workflow orchestration. ShellForge wraps them all with AgentGuard policy enforcement on every tool call.

The Stack

Layer Project What It Does
Infer Ollama Local LLM inference (Metal GPU on Mac)
Optimize RTK Token compression — 70-90% reduction on shell output
Execute Goose AI coding agent with native Ollama support (headless)
Orchestrate Dagu YAML DAG workflows with scheduling and web UI
Govern AgentGuard Policy enforcement on every action — allow/deny/correct
Sandbox OpenShell Kernel-level isolation (Docker on macOS)
Scan DefenseClaw Supply chain scanner — AI Bill of Materials 
shellforge status
# Ollama        running (qwen3:30b loaded)
# RTK           v0.4.2
# AgentGuard    enforce mode (5 rules)
# Dagu          connected (web UI at :8080)
# OpenShell     Docker sandbox active
# DefenseClaw   scanner ready

CLI Commands

Command Description
shellforge run <driver> "prompt" Run a governed agent (goose, claude, copilot, codex, gemini)
shellforge setup Install Ollama, create governance config, verify stack
shellforge agent "prompt" Run a governed agent — every tool call checked
shellforge qa [dir] QA analysis — find test gaps and issues
shellforge report [repo] Generate a status report from git + logs
shellforge serve agents.yaml Daemon mode — run a 24/7 agent swarm
shellforge status Show ecosystem health
shellforge version Print version

Multi-Driver Governance

ShellForge governs any CLI agent driver via AgentGuard hooks. Each driver keeps its own model and agent loop — ShellForge ensures governance is active and spawns the driver as a subprocess.

# Run any driver with governance
shellforge run claude "review this code"
shellforge run codex "generate tests"
shellforge run copilot "update docs"
shellforge run gemini "security audit"

Orchestrate multiple drivers in a single Dagu DAG:

dagu start dags/multi-driver-swarm.yaml

See dags/multi-driver-swarm.yaml and dags/workspace-swarm.yaml for examples.

Architecture

┌───────────────────────────────────────────────────┐
│  Dagu (Orchestration)                              │
│  YAML DAGs · Cron scheduling · Web UI · Retries    │
└────────────────────┬──────────────────────────────┘
                     │ task
┌────────────────────▼──────────────────────────────┐
│  Goose (Execution Engine)                          │
│  Agent loop · Tool calling · Ollama-native         │
│  Uses Ollama for inference                         │
└────────────────────┬──────────────────────────────┘
                     │ tool call
          ═══════════╪═══════════
          ║  AgentGuard          ║
          ║  Governance Kernel   ║
          ║  allow · deny · audit║
          ║  every. single. call.║
          ═══════════╪═══════════
                     │ approved
┌────────────────────▼──────────────────────────────┐
│  Your Environment                                  │
│  Files · Shell (RTK) · Git · Network               │
│  Sandboxed by OpenShell                            │
└───────────────────────────────────────────────────┘

Governance

ShellForge's core value. Every tool call passes through agentguard.yaml before execution.

# agentguard.yaml — policy-as-code for every agent action
mode: enforce  # enforce | monitor

policies:
  - name: no-force-push
    action: deny
    pattern: "git push --force"

  - name: no-destructive-rm
    action: deny
    pattern: "rm -rf"

  - name: no-secret-access
    action: deny
    pattern: "*.env|*id_rsa|*id_ed25519"

When an action is denied, ShellForge's correction engine feeds structured feedback back to the model so it can self-correct — not just fail.

Swarm Mode

Run a 24/7 agent swarm on your Mac with memory-aware scheduling:

shellforge serve agents.yaml

Auto-detects RAM, calculates max parallel Ollama slots, queues the rest.

# agents.yaml
max_parallel: 0     # 0 = auto-detect from RAM
model_ram_gb: 19    # qwen3:30b Q4

agents:
  - name: qa-agent
    system: "You are a QA engineer."
    prompt: "Analyze the repo for test gaps."
    schedule: "4h"
    priority: 2
    timeout: 300
    enabled: true

Memory budget (qwen3:30b Q4):

Mac RAM Free for KV Max Parallel
M4 Pro 48GB 48 GB ~25 GB 3-4 agents
M4 32GB 32 GB ~9 GB 1-2 agents

Tip: OLLAMA_KV_CACHE_TYPE=q8_0 halves KV cache memory — doubles agent capacity.

Model Options

Model Params RAM Best For
qwen3:1.7b 1.7B ~1.2 GB Fast tasks, prototyping
qwen3:4b 4B ~3 GB Balanced reasoning
qwen3:30b 30B ~19 GB Production quality (M4 Pro 48GB)
mistral:7b 7B ~5 GB Complex analysis

macOS (Apple Silicon / M4)

  • Ollama uses Metal GPU acceleration — no CUDA needed
  • KV cache quantization (OLLAMA_KV_CACHE_TYPE=q8_0) halves memory per agent slot
  • OpenShell requires Docker via Colima

The AgentGuard Platform

Project What It Does
AgentGuard Governance kernel — policy enforcement for any agent driver
AgentGuard Cloud SaaS dashboard — observability, session replay, compliance
ShellForge Governed local agent runtime — the onramp to AgentGuard

Contributing

git checkout -b feat/my-feature
go build ./cmd/shellforge/
go test ./...

See docs/roadmap.md for what's planned.

Website · Star on GitHub · AgentGuard

Built by humans and agents

MIT License

About

🔥 Forge local AI agents. Governed. Private. Unstoppable. — Ollama + AgentGuard + OpenShell + DefenseClaw

agentguardhq.github.io/shellforge

Topics

security governance ai-agents apple-silicon local-llm ollama agentic-ai openshell agentguard defenseclaw

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 21

v0.6.1 Latest
Mar 27, 2026
+ 20 releases

Packages

 
 
 

Contributors

Languages