Agent Orchestration & Security Template

An AI safety engineering portfolio combining production tooling, detection research, and risk analysis—structured as a reusable template.

Important: This is an advanced template repository designed for experienced developers working with autonomous AI agents. Before diving in, we strongly recommend:

1. Read the AI Safety Training Guide - Essential concepts for safe human-AI collaboration, including deception detection, scalable oversight, and control protocols

2. Take an AI Safety course at BlueDot Impact - Free, rigorous training programs covering AI safety fundamentals, governance, and alignment. Highly recommended for anyone building with autonomous agents.

Working with AI agents introduces risks that differ fundamentally from traditional software. Understanding these risks isn't optional - it's a prerequisite for responsible development.

Project Philosophy

This project follows a container-first approach:

• All tools and CI/CD operations run in Docker containers for maximum portability
• Zero external dependencies - runs on any Linux system with Docker
• Self-hosted infrastructure - no cloud costs, full control over runners
• Single maintainer design - optimized for individual developer productivity
• Modular MCP architecture - Separate specialized servers for different functionalities

Quick Start

New to the template? Check out our Template Quickstart Guide for step-by-step customization instructions!

1. Prerequisites: Linux system with Docker (v20.10+) and Docker Compose (v2.0+)

2. Clone and setup

   git clone https://github.com/AndrewAltimit/template-repo
   cd template-repo
   pip3 install -e ./packages/github_agents
   

3. Set API keys (if using AI features)

   export OPENROUTER_API_KEY="your-key-here"  # For OpenCode/Crush
   export GEMINI_API_KEY="your-key-here"      # For Gemini
   

4. Use with Claude Code: MCP servers are configured in .mcp.json and auto-started by Claude. See MCP Configuration for essential vs full setups.

5. Run CI/CD operations

   ./automation/ci-cd/run-ci.sh full  # Full pipeline
   

For detailed setup, see CLAUDE.md and Template Quickstart Guide.

AI Agents

Six AI agents for development and automation. See AI Agents Documentation for details.

All code generation agents (Codex, OpenCode, Crush) provide equivalent functionality - choose based on your API access.

Security: Keyword triggers, user allow list, secure token management. See Security Model

Safety Training: Essential AI safety concepts for human-AI collaboration. See Human Training Guide

Sleeper Agents: Create and evaluate sleeper agents in order to detect misalignment and probe for deception. See Sleeper Agents Package

Agentic Git Workflow

AI agents autonomously manage the development lifecycle from issue creation through PR merge:

Issue Created → Admin Approval → Agent Claims → PR Created → AI Review → Human Merge

The Flow:

1. Issue Creation - Issues are created manually or by agents via backlog-refinement.yml, automatically added to the GitHub Projects board
2. Admin Approval - An authorized user comments [Approved][Claude] (or another agent name) to authorize work
3. Agent Claims - board-agent-worker.yml finds approved issues, the agent claims the issue and creates a working branch
4. Implementation - The agent implements the fix/feature and opens a PR
5. AI Review - pr-validation.yml triggers Gemini code review; pr-review-monitor.yml lets agents iterate on feedback
6. Human Merge - Admin reviews and merges the PR

Security Model:

• Approval Required - Agents cannot work on issues without explicit [Approved][Agent] comment
• Authorized Users Only - Only users listed in .agents.yaml → security.agent_admins can approve
• Pattern Validation - Must use [Action][Agent] format (e.g., [Approved][Claude]) to prevent false positives
• Claim Tracking - Agents post claim comments with timestamps to prevent conflicts

See Security Documentation for the complete security model.

Reports & Research

Technical reports and guides exploring AI risks, safety frameworks, and philosophical questions. PDFs are automatically built from LaTeX source and published with each release.

Emerging Technology Risk Assessments

Scenario-based projection reports analyzing potential futures involving advanced AI systems. See Projections Documentation.

Technical Guides

Philosophy Papers

Philosophical explorations of minds, experience, and intelligence. See Philosophy Papers Documentation.

Build Status:

Packages

Four standalone packages addressing different aspects of AI agent development and safety:

# Install Python packages
pip install -e ./packages/github_agents
pip install -e ./packages/sleeper_agents
pip install -e ./packages/economic_agents

# Build Rust package (requires Rust toolchain)
cd packages/injection_toolkit && cargo build --release

Features

• 18 MCP Servers - Code quality, content creation, AI assistance, 3D graphics, video editing, speech synthesis, and more
• 6 AI Agents - Autonomous development workflow from issue to merge
• 4 Packages - GitHub automation, sleeper agent detection, economic agent simulation, runtime injection toolkit
• Container-First Architecture - Maximum portability and consistency
• Self-Hosted CI/CD - Zero-cost GitHub Actions infrastructure
• Company Integration - Corporate proxy builds for enterprise AI APIs (Docs)

Enterprise & Corporate Setup

For enterprise environments requiring custom certificates, customize automation/corporate-proxy/shared/scripts/install-corporate-certs.sh. This script runs during Docker builds for all containers. See the customization guide for details.

Project Structure

.
├── .github/workflows/        # GitHub Actions workflows
├── docker/                   # Docker configurations
├── packages/                 # Installable packages
│   ├── github_agents/        # Multi-agent GitHub automation
│   ├── sleeper_agents/       # AI backdoor detection framework
│   ├── economic_agents/      # Autonomous economic agents
│   └── injection_toolkit/    # Rust runtime injection framework
├── tools/
│   ├── mcp/                  # 18 MCP servers (see MCP Servers section)
│   └── cli/                  # Agent runners and utilities
├── automation/               # CI/CD and automation scripts
├── tests/                    # Test files
├── docs/                     # Documentation
└── config/                   # Configuration files

MCP Servers

Available Servers

1. Code Quality - Formatting, linting, auto-formatting
2. Content Creation - Manim animations, LaTeX, TikZ diagrams
3. Gaea2 - Terrain generation (Documentation)
4. Blender - 3D content creation, rendering, physics simulation (Documentation)
5. Gemini - AI consultation (containerized and host modes available)
6. Codex - AI-powered code generation and completion
7. OpenCode - Code generation via OpenRouter
8. Crush - Code generation via OpenRouter
9. Meme Generator - Create memes with templates
10. ElevenLabs Speech - Advanced TTS with v3 model, 50+ audio tags, 74 languages (Documentation)
11. Video Editor - AI-powered video editing with transcription and scene detection (Documentation)
12. Virtual Character - AI agent embodiment in virtual worlds (VRChat, Blender, Unity) (Documentation)
13. GitHub Board - GitHub Projects v2 board management, work claiming, agent coordination (Documentation)
14. AI Toolkit - LoRA training interface (remote: 192.168.0.222:8012)
15. ComfyUI - Image generation interface (remote: 192.168.0.222:8013)
16. AgentCore Memory - Multi-provider AI memory (AWS AgentCore or ChromaDB) (Documentation)
17. Reaction Search - Semantic search for anime reaction images (Documentation)
18. Desktop Control - Cross-platform desktop automation for Linux and Windows (Documentation)

Usage Modes

• STDIO Mode (local MCPs): Configured in .mcp.json, auto-started by Claude
• HTTP Mode (remote MCPs): Run the MCP using docker-compose on the remote node.

See MCP Architecture Documentation and STDIO vs HTTP Modes for details.

Tool Reference

For complete tool listings, see MCP Tools Reference

Configuration

Environment Variables

See .env.example for all available options.

Key Configuration Files

• .mcp.json - MCP server configuration for Claude Code
• docker-compose.yml - Container services configuration
• CLAUDE.md - Project-specific Claude Code instructions (root directory)
• AGENTS.md - Universal AI agent configuration and guidelines (root directory)
• docs/agents/project-context.md - Context for AI reviewers

Setup Guides

• Self-Hosted Runner Setup
• GitHub Environments Setup
• Gemini Setup
• Containerized CI

Development Workflow

Container-First Development

All Python operations run in Docker containers:

# Run CI operations
./automation/ci-cd/run-ci.sh format      # Check formatting
./automation/ci-cd/run-ci.sh lint-basic  # Basic linting
./automation/ci-cd/run-ci.sh test        # Run tests
./automation/ci-cd/run-ci.sh full        # Full CI pipeline

# Run specific tests
docker-compose run --rm python-ci pytest tests/test_mcp_tools.py -v

GitHub Actions

• Pull Request Validation - Automatic Gemini AI review
• Continuous Integration - Full CI pipeline
• Code Quality - Multi-stage linting (containerized)
• Automated Testing - Unit and integration tests
• Security Scanning - Bandit and safety checks

All workflows run on self-hosted runners for zero-cost operation.

Documentation

Core Documentation

• AGENTS.md - Universal AI agent configuration and guidelines
• CLAUDE.md - Claude-specific instructions and commands
• MCP Architecture - Modular server design
• AI Agents Documentation - AI agents overview

Quick References

• Codex Setup Guide
• AI Code Agents Quick Reference
• MCP Tools Reference
• Gaea2 Quick Reference

Integration Guides

• Codex Integration
• AI Code Agents Integration
• AI Toolkit & ComfyUI Integration
• Gaea2 Documentation

Setup & Configuration

• Template Quickstart Guide - Customize the template for your needs
• Self-Hosted Runner Setup
• GitHub Environments Setup
• Containerized CI

License

This project is released under the Unlicense (public domain dedication).

For jurisdictions that do not recognize public domain: As a fallback, this project is also available under the MIT License.