diff --git a/docs/execution_backends.md b/docs/execution_backends.md new file mode 100644 index 0000000..bf3806a --- /dev/null +++ b/docs/execution_backends.md @@ -0,0 +1,116 @@ +# Execution Backends in ThreeGate + +ThreeGate deliberately separates *reasoning* from *execution* and further subdivides execution +into **two distinct backends** with different risk profiles. + +This document explains when and why each backend exists, and how escalation decisions should be made. + +--- + +## Overview + +| Backend | Purpose | Risk Level | Default | +|-------|---------|------------|---------| +| Monty (TOOL-EXEC-Lite) | Pure compute, data transforms | Low | ✅ Yes | +| ERA (TOOL-EXEC-Heavy) | General execution in microVM | Higher | ❌ No | + +--- + +## Monty (TOOL-EXEC-Lite) + +### What Monty Is +Monty is a restricted Python-subset interpreter designed for agentic toolchains. +It provides *programmability without host access*. + +### Capabilities +- Arithmetic and control flow +- Lists, dicts, loops +- Deterministic transformations over provided inputs +- Captured stdout / return value + +### Explicitly Not Allowed +- Filesystem access +- Network access +- Environment variables +- Subprocesses +- Dynamic imports +- External functions (unless explicitly added by policy) + +### Intended Use Cases +- Ranking or scoring items +- JSON or CSV-like data transformations +- Parsing and normalization +- Small algorithms that would otherwise require custom code + +### Why Monty Is the Default +- Minimal blast radius +- No persistence +- No I/O side effects +- Fast startup +- Designed specifically to avoid “agent escape hatches” + +### Security Note +Monty is *not* a sandbox replacement for arbitrary Python. +It is a **capability-limited interpreter**. +Any addition of external functions is a security boundary change. + +--- + +## ERA (TOOL-EXEC-Heavy) + +### What ERA Is +ERA executes tasks inside a microVM with strong isolation guarantees. + +### Capabilities +- Full Python or binary execution +- File I/O via explicit mounts +- Larger memory and runtime allowances +- Future support for specialized tools + +### When ERA Is Justified +Use ERA **only** when: +- The task cannot be expressed in Monty’s subset +- File-based artifacts are required +- External binaries are unavoidable +- The operator explicitly approves escalation + +### Why ERA Is Not the Default +- Larger attack surface +- More complex lifecycle +- Higher operational cost +- More difficult to audit than pure compute + +ERA exists as an *escape hatch*, not a baseline. + +--- + +## Escalation Rules (Non-Negotiable) + +1. **Attempt Monty first** +2. If Monty cannot express the task, document why +3. Require explicit human approval for ERA +4. Treat ERA outputs as untrusted data on return +5. Never allow ERA to initiate further execution or retrieval + +--- + +## Anti-Patterns + +🚫 Automatically choosing ERA +🚫 Allowing Monty to access files or network +🚫 Re-running execution results as instructions +🚫 Chaining execution backends without human approval + +--- + +## Summary + +ThreeGate’s execution model is deliberately asymmetric: + +- Monty provides *safe programmability* +- ERA provides *controlled power* +- CORE never executes +- FETCH never executes +- No backend is autonomous + +This separation is foundational to ThreeGate’s security model. diff --git a/docs/quickstart.md b/docs/quickstart.md index 14f6a98..1e45629 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -10,11 +10,24 @@ This is a *non-destructive* smoke test: --- +⚠️ Important: Execution Backends + +ThreeGate supports two execution backends: + +- `monty` (default): pure compute, safest +- `ERA`: microVM, higher risk, explicit approval required + +If you are unsure, use Monty. + +--- + ## Prerequisites - Docker + Docker Compose v2 - Python 3 (stdlib only; no pip deps) -- (Optional for tool-exec example) ERA `agent` CLI installed and available in PATH +- (Optional for tool-exec example 'hello') ERA `agent` CLI installed and available in PATH +- (Optional for tool-exec example 'json sum') Monty 'agent' CLI installed and available in PATH +- Either a local LLM hosted via an OpenAI-compatible endpoint or OpenAI API key ---