Operational Boundaries¶

This document defines the operational boundaries and constraints for Project Aegis.

Overview¶

Aegis operates as an autonomous AI agent within defined security, financial, and operational boundaries. These boundaries ensure safe operation while enabling genuine autonomy.

Container Filesystem Boundaries¶

Accessible Paths¶

Aegis operates within an LXC container with access to:

Path	Access	Purpose
`/home/agent/`	Read/Write	Agent home directory (primary workspace)
`/home/agent/.secure/`	Read-only (via Docker mount)	Credentials storage
`/home/agent/memory/`	Read/Write	Memory hierarchy (episodic, semantic, procedural)
`/home/agent/projects/`	Read/Write	Project repositories
`/home/agent/.claude/`	Read/Write	Claude Code configuration
`/var/run/docker.sock`	Read-only (via Docker mount)	Docker container management
`/tmp/`	Read/Write	Temporary files

Restricted Paths¶

Aegis cannot access (LXC isolation):

Path	Reason
Host filesystem (`/mnt/host/`)	No mount configured
Other LXC containers	Isolated by Proxmox
Proxmox host (`/srv/`)	No access from container
Dockerhost LXC filesystem	Accessible only via SSH

Enforcement Mechanisms¶

LXC Isolation: Kernel namespaces prevent escape to host filesystem
Docker Volume Mounts: Only specified directories mounted in containers
Security Hooks: block-sensitive-files.py prevents modification of protected files
File Permissions: .secure/ has 700 permissions (owner only)

Boundary Testing¶

# These operations are BLOCKED
ls /mnt/host  # No such directory
cat /srv/dockerdata/traefik/config.yml  # Permission denied
edit ~/.ssh/id_ed25519  # Blocked by security hook

# These operations are ALLOWED
ls /home/agent/memory  # Success
edit /home/agent/projects/aegis-core/aegis/dashboard/app.py  # Success
docker ps  # Success (read-only socket)

Financial Controls¶

Monthly Budget¶

Total: $50/month (Privacy.com virtual card)

Budget Breakdown: | Category | Monthly Allocation | |----------|-------------------| | API costs (Z.ai, Perplexity) | $30 | | Domain renewals (aegisagent.ai) | $10 | | External services (Stripe, Resend) | $5 | | Emergency buffer | $5 |

Enforcement: Privacy.com card has hard limit of $50/month (declines transactions above limit)

Spending Authority by Phase¶

Phase	Time Period	Per-Transaction Limit	Approval Required
Phase 1	Days 1-3	$0	N/A (no spending)
Phase 2	Days 4-10	$5	Auto-approve
Phase 3	Day 11+	$10	Auto-approve

Current Phase: Phase 3 (operational since Jan 2026)

Transaction Approval Workflow¶

# Conceptual workflow (not implemented)
def can_approve_transaction(amount: float, phase: int) -> bool:
    limits = {1: 0, 2: 5, 3: 10}
    if amount > limits[phase]:
        return False  # Requires human approval

    # Check wallet balance
    balance = get_monthly_balance()  # From Privacy.com
    if balance + amount > 50:
        return False  # Would exceed monthly budget

    return True

Transaction Logging¶

Location: ~/memory/ledger.json

Format:

{
  "transactions": [
    {
      "date": "2026-01-25",
      "amount": 2.50,
      "vendor": "Z.ai",
      "category": "api_costs",
      "description": "GLM-4.7 API usage",
      "approved_by": "auto",
      "phase": 3
    }
  ],
  "monthly_total": 42.50,
  "remaining_budget": 7.50
}

Wallet MCP Verification¶

MCP Server: wallet (TODO: implement)

Usage:

# Before making purchase
balance = mcp__wallet__get_balance()
if balance + purchase_amount <= 50:
    proceed_with_purchase()
else:
    log_to_discord("#alerts", "Budget limit reached")

Financial Alerts¶

Trigger Discord/Telegram alerts when: - Single transaction >$5 - Monthly total >$40 (80% of budget) - Monthly total >$50 (budget exceeded) - Unusual spending pattern (e.g., 5+ transactions in 1 hour)

Resource Discipline¶

Memory Limits¶

Container RAM: 110GB (LXC allocation)

Memory Usage Targets: | Component | Target | Max | |-----------|--------|-----| | PostgreSQL | 4GB | 8GB | | FalkorDB | 2GB | 4GB | | Ollama | 8GB | 16GB | | Docker Containers | 10GB | 20GB | | Filesystem Cache | 20GB | 40GB | | Available for Growth | 66GB | 22GB |

Monitoring:

# Check container memory
free -h

# Check Docker container memory
docker stats --no-stream

# Check PostgreSQL memory
psql -U agent -d aegis -c "SHOW shared_buffers;"

# Check Ollama memory
curl http://localhost:11434/api/tags | jq '.models[].size'

Enforcement: If memory usage >90GB, trigger cleanup: 1. Clear Docker image cache: docker image prune -a 2. Clear Ollama unused models: ollama rm <model> 3. Clear PostgreSQL old sessions: DELETE FROM claude_sessions WHERE created_at < NOW() - INTERVAL '90 days' 4. Clear filesystem cache: rm -rf /tmp/* ~/.cache/*

Disk Space Limits¶

Container Disk: 500GB (LXC allocation)

Disk Usage Targets: | Path | Target | Max | |------|--------|-----| | /home/agent/memory/ | 50GB | 100GB | | /home/agent/projects/ | 20GB | 50GB | | Docker volumes | 30GB | 100GB | | /tmp/ | 10GB | 50GB | | Available for Growth | 390GB | 200GB |

Monitoring:

# Check disk usage
df -h /home/agent

# Check memory directory size
du -sh /home/agent/memory

# Check Docker volumes
docker system df

Enforcement: If disk usage >400GB, trigger cleanup (same as memory)

API Rate Limits¶

Service	Rate Limit	Daily Cap
Z.ai (GLM-4.7)	~8 req/min	Unlimited (fair use)
Perplexity	10 req/min	300 req/day
Stripe	100 req/sec	Unlimited
Discord	50 req/sec	Unlimited (rate limited)
Telegram	30 req/sec	Unlimited
GitHub	5,000 req/hour	Unlimited

Enforcement: Implement exponential backoff on rate limit errors.

Monitoring: Log API usage to ~/memory/tool-usage.jsonl

Prohibited Actions¶

Filesystem Operations¶

Blocked by bash-validator.py hook:

# PROHIBITED
rm -rf /                    # Recursive delete of root
rm -rf ~                    # Recursive delete of home
rm -rf *                    # Recursive delete with wildcard
sudo rm -rf                 # Sudo recursive delete
chmod 777 ~/.ssh/id_ed25519 # Overly permissive SSH key
mkfs.ext4 /dev/sda          # Format filesystem
dd if=/dev/zero of=/dev/sda # Overwrite disk
> /etc/passwd               # Redirect to system file

Blocked by block-sensitive-files.py hook:

# PROHIBITED
edit ~/.ssh/id_ed25519      # Modify SSH private key
edit ~/.ssh/id_ed25519_github
write /home/agent/.secure/new-credential.pem  # Write new private key

Git Operations¶

Blocked by bash-validator.py hook:

# PROHIBITED
git push --force origin main       # Force push to main branch
git push --force origin master     # Force push to master branch
git reset --hard origin/main       # Hard reset to origin

Allowed (with caution):

git push --force origin feature-branch  # Force push to feature branch (OK)
git commit --amend                      # Amend commits (OK)
git rebase -i HEAD~5                    # Interactive rebase (OK)

Network Operations¶

Prohibited: - Port scanning external networks - DDoS attacks - Unauthorized access to external systems - Bypass of Traefik routing (direct container access from external)

Enforcement: Not implemented (relies on ethical operation)

Recommended: Add outbound firewall rules to block suspicious traffic

Spending Operations¶

Prohibited without approval: - Transactions >$10 in Phase 3 - Multiple small transactions totaling >$50/month - Subscriptions without explicit approval - Purchasing physical goods

Enforcement: Privacy.com card limits + manual ledger review

Data Exfiltration¶

Prohibited: - Uploading .secure/ contents to external services - Posting credentials to Discord/Telegram/WhatsApp - Committing secrets to GitHub - Sharing API keys in logs

Enforcement: - block-sensitive-files.py prevents credential modification - mcp-security-audit.py logs MCP operations - Manual code review before commits

Three-Strike Debug Protocol¶

Purpose¶

Prevent infinite loops and wasted resources on unsolvable problems.

Protocol¶

Strike 1: Retry with Modified Approach¶

Actions: 1. Search for similar past errors: mcp__aegis__error_search(query="<error_type>") 2. Record the error: mcp__aegis__error_record(error_type, context, strike_count=1) 3. Try a different approach (e.g., different library, different algorithm)

Example:

# Strike 1: API request failed
try:
    result = requests.get("https://api.example.com")
except Exception as e:
    mcp__aegis__error_record(
        error_type="api_request_failed",
        context={"url": "https://api.example.com", "error": str(e)},
        strike_count=1
    )
    # Retry with exponential backoff
    time.sleep(2)
    result = requests.get("https://api.example.com")

Strike 2: Switch to Local Reasoning, Analyze from First Principles¶

Actions: 1. Record escalation: mcp__aegis__error_record(error_type, context, strike_count=2) 2. Check if pattern exists in past resolutions: mcp__aegis__error_search(query="<error_type>") 3. Use local model (Ollama) for offline reasoning 4. Analyze problem from first principles (not relying on external docs)

Example:

# Strike 2: API request failed again
mcp__aegis__error_record(
    error_type="api_request_failed",
    context={"url": "https://api.example.com", "error": str(e)},
    strike_count=2
)

# Search past errors
past_errors = mcp__aegis__error_search(query="api_request_failed")

# Switch to local reasoning
from aegis.llm import query_local
analysis = await query_local("Analyze this API error: " + str(e))

Strike 3: STOP, Document, Escalate¶

Actions: 1. Record critical error: mcp__aegis__error_record(error_type, context, strike_count=3, severity="critical") 2. Document in journal: ~/memory/journal/YYYY-MM-DD.md 3. Post to Discord #alerts: "3-strike escalation: " 4. Wait for human input (do not retry automatically)

Example:

# Strike 3: API request failed third time
mcp__aegis__error_record(
    error_type="api_request_failed",
    context={"url": "https://api.example.com", "error": str(e)},
    strike_count=3,
    severity="critical"
)

# Document in journal
journal_entry = f"""
## Three-Strike Escalation

**Error**: api_request_failed
**Context**: API endpoint https://api.example.com consistently returns 500 errors
**Attempts**: 3
**Last Error**: {str(e)}
**Escalation**: Awaiting human investigation
"""
append_to_journal(journal_entry)

# Post to Discord
mcp__discord__send_message(
    channel_id="1455049130614329508",  # #alerts
    content="🚨 Three-strike escalation: API request failed after 3 attempts. Manual intervention required."
)

# STOP - do not retry
return None

Resolution Tracking¶

Once resolved (by human or agent):

mcp__aegis__error_resolution(
    error_id="<id_from_error_record>",
    resolution="Updated API endpoint URL from .env file",
    worked=True,
    lessons_learned="Always verify environment variables are current before debugging"
)

Error MCP Tools¶

Tool	Purpose
`mcp__aegis__error_record`	Log errors with context and strike count
`mcp__aegis__error_search`	Find similar past errors and resolutions
`mcp__aegis__error_recent`	Get recent errors for pattern detection
`mcp__aegis__error_resolution`	Record how an error was fixed (for learning)

Storage: ~/memory/episodic/errors.jsonl

When to Use¶

Apply three-strike protocol for: - API request failures (network errors, timeouts) - File not found errors (repeated failures to locate expected files) - Database connection errors - Docker container failures (repeated restart failures) - LLM inference errors (consistent failures from a model)

Do NOT use for: - User errors (invalid input, typos) - Expected errors (file already exists, resource already allocated) - Transient errors (single network blip that resolves on retry)

Autonomous Operation Limits¶

Autonomous Mode State¶

Location: ~/.claude/autonomous_mode

States: - enabled: Autonomous mode active (auto-continue on Stop) - disabled: Manual mode (stop on completion)

Control:

# Enable autonomous mode
echo "enabled" > ~/.claude/autonomous_mode

# Disable autonomous mode
echo "disabled" > ~/.claude/autonomous_mode

Auto-Continue Behavior¶

Hook: autonomous-continue.sh (Stop event)

Logic:

if [ "$(cat ~/.claude/autonomous_mode)" = "enabled" ]; then
    # Check if tasks remain
    if ~/.local/bin/bd ready --json | jq 'length' | grep -v '^0$'; then
        # Auto-continue with next task
        claude-code continue
    fi
fi

Limits: - Max 10 auto-continues per day (prevents runaway loops) - Stops if same error occurs 3 times (three-strike protocol) - Stops if budget limit reached ($50/month) - Stops if disk usage >90% (400GB/500GB)

Manual Override¶

Force stop autonomous mode:

echo "disabled" > ~/.claude/autonomous_mode
pkill -f "claude-code"

Check autonomous state:

cat ~/.claude/autonomous_mode  # enabled or disabled

Prohibited Integrations¶

GREEN-API (WhatsApp)¶

Status: Prohibited

Reason: Requires a real phone number with WhatsApp installed. Vonage VOIP numbers don't work. Instance 7105451204 is unusable without a physical SIM.

Alternative: Use Vonage WhatsApp Business API (already integrated)

Documentation: Added to CLAUDE.md under "Prohibited Actions"

Other Prohibited Services¶

Service	Reason	Alternative
Twilio SMS	Cost (international SMS expensive)	Telegram
Cloudflare Workers (paid)	Budget ($50/month cap)	Self-hosted
OpenAI API	Cost (prefer cheaper alternatives)	Z.ai (GLM-4.7)
AWS services	Budget + complexity	Self-hosted on Aegis LXC

Compliance Boundaries¶

Data Residency¶

Current State: All data stored in Hetzner datacenter (Germany)

GDPR Compliance: - User data (WhatsApp numbers, sessions) stored in PostgreSQL - Right to access: Implement export endpoint - Right to deletion: Implement deletion endpoint - Data retention: 90 days (configurable)

US Data Transfer: Not implemented (all services EU-based)

Data Retention¶

Data Type	Retention Period	Reason
Claude sessions (WhatsApp)	90 days	User convenience
MCP audit logs	1 year	Security auditing
Error logs	1 year	Debugging
Journal entries	Indefinite	Historical record
Episodic memory	Indefinite	Knowledge accumulation

Enforcement: Cron job runs monthly to delete old data

Content Restrictions¶

Prohibited Content: - Illegal content (CSAM, malware, hate speech) - Personally identifiable information (PII) without consent - Copyrighted material without license

Enforcement: Manual review (no automated content filtering)

Escalation Procedures¶

Boundary Violation Detection¶

Violation Type	Detection Method	Response
Filesystem breach	Security hooks block operation	Log to Discord #alerts
Budget exceeded	Privacy.com declines transaction	Log to Discord #alerts, pause spending
Memory exceeded	`free -h` shows >90% usage	Trigger cleanup, log to Discord
Three-strike limit	Error tracking MCP	Stop, document, escalate to Discord
Prohibited action	Security hooks block operation	Log to audit, Discord notification

Escalation Matrix¶

Severity	Response Time	Actions
Low	Next business day	Log to journal
Medium	Within 24 hours	Post to Discord #general
High	Within 1 hour	Post to Discord #alerts + Telegram
Critical	Immediate	Discord #alerts + Telegram + WhatsApp

Critical Escalations: - Budget exceeded by >20% - Security breach (credential exposure) - Data loss (unrecoverable filesystem corruption) - Three-strike protocol triggered on critical operation

Audit and Monitoring¶

Boundary Monitoring¶

Daily Checks (automated via /morning skill): - Memory usage: free -h - Disk usage: df -h /home/agent - Budget status: Check ~/memory/ledger.json - Recent errors: tail -20 ~/memory/episodic/errors.jsonl - MCP audit logs: jq 'select(.flagged == true)' ~/memory/security/mcp-audit.jsonl | tail -10

Weekly Checks (manual): - Review three-strike escalations - Review MCP audit logs for anomalies - Verify autonomous mode limits not exceeded - Check for unauthorized spending

Monthly Checks (manual): - Full security audit (credentials, hooks, network) - Budget reconciliation (Privacy.com statement) - Data retention cleanup (delete old sessions) - Boundary configuration review (update limits if needed)

Audit Reports¶

Location: ~/memory/security/boundary-audit-YYYY-MM.md

Template:

# Boundary Audit Report - January 2026

## Summary
- Filesystem boundary violations: 0
- Budget exceeded: No
- Three-strike escalations: 2 (resolved)
- Autonomous mode auto-continues: 45
- MCP flagged operations: 12

## Violations
None

## Recommendations
- Increase disk space limit to 600GB (currently 500GB)
- Add rate limiting to Discord MCP (50 req/sec too high)

## Action Items
- [ ] Update disk space limit in LXC config
- [ ] Implement Discord rate limiting

Future Enhancements¶

Planned (v2.0)¶

Implement wallet MCP server for real-time budget verification
Add memory usage alerts (Discord notification at 80%)
Implement automated data retention cleanup (cron job)
Add boundary violation dashboard (real-time monitoring)
Implement spending approval workflow (human-in-the-loop for >$10)
Add content filtering for prohibited content

Under Consideration¶

Multi-tier spending authority (admin vs agent)
Dynamic budget allocation (adjust monthly based on revenue)
Automated boundary testing (penetration testing framework)
Blockchain-based audit trail (immutable logs)
Zero-knowledge proof for credential verification (no plaintext storage)