[{"content":"Carpenter is a pure-Python AI agent platform where every action is reviewable code. These pages cover how the system works, from the high-level event loop to the trust boundaries that make autonomous operation safe.\nStart with the overview for the big picture, or jump to a topic:\n","externalUrl":null,"permalink":"/docs/","section":"Documentation","summary":"Carpenter is a pure-Python AI agent platform where every action is reviewable code. These pages cover how the system works, from the high-level event loop to the trust boundaries that make autonomous operation safe.\n","title":"Documentation","type":"docs"},{"content":" The Core Loop # Carpenter agents follow a simple cycle: observe → generate code → review → execute → persist.\nAn event arrives — a chat message, a webhook, a cron fire, or a child arc completing. The agent reads whatever it needs: files, state, arc trees, conversation history, skills. All read access is free and unrestricted. When the agent wants to do something — write a file, call an API, modify state — it generates Python code and calls submit_code. The review pipeline inspects the code: syntax check, injection scan, sanitization, then a separate AI reviewer that sees only the sanitized structure. Approved code executes in a sandboxed environment with no direct network access. Results are persisted — every code file, every execution log, every state change is written to disk and tracked in the database. This is the \u0026ldquo;measure twice, cut once\u0026rdquo; principle: the agent thinks freely but every action is inspected before it happens. For high-stakes operations, the pipeline extends to multiple independent reviewers, a judge, and separation-of-powers verification — \u0026ldquo;measure N times, cut once.\u0026rdquo;\nObserve Freely, Act Carefully # The agent has two modes of interaction:\nMode Mechanism Examples Observe (free) Tool-use read calls Read files, list arcs, search knowledge base, load skills Act (gated) submit_code Write files, mutate state, make web requests, run git, create arcs This split is the fundamental design decision. Read-only observation can\u0026rsquo;t cause harm, so it\u0026rsquo;s unrestricted — giving the agent full situational awareness. Every side effect is funneled through code review, making the boundary between intent and action explicit and auditable.\nEvents and the Main Loop # Everything that happens enters as an event in an append-only log. The main loop combines two rhythms:\nWake signal — instant processing for chat messages 5-second heartbeat — periodic work: cron evaluation, timeout checks, event matcher evaluation Each cycle: claim work queue items, match events to waiting arcs, check expirations, fire cron entries, run heartbeat hooks.\nPersistence # Every piece of agent-generated Python is saved to a date-partitioned directory:\ndata/code/2026/03/16/000001_agent_step.py data/logs/2026/03/16/000001_agent_step.log The database (SQLite in WAL mode) tracks code files, execution records, review status, arc state, conversation history, and a trust audit log. Nothing is ephemeral — the full history of every agent action is recoverable.\n","externalUrl":null,"permalink":"/docs/overview/","section":"Documentation","summary":"The Core Loop # Carpenter agents follow a simple cycle: observe → generate code → review → execute → persist.\n","title":"How Carpenter Works","type":"docs"},{"content":" What Is an Arc? # An arc is a unit of work with a lifecycle. It is the only work abstraction in Carpenter — tasks, projects, cron jobs, and sub-steps are all arcs at different depths in a recursive tree.\nThis unification eliminates the friction of mapping between \u0026ldquo;tasks,\u0026rdquo; \u0026ldquo;workflows,\u0026rdquo; \u0026ldquo;jobs,\u0026rdquo; and \u0026ldquo;history.\u0026rdquo; An arc is all of them at once.\nState Machine # Every arc follows this lifecycle:\npending → active → waiting / completed / failed / cancelled completed, failed, and cancelled are frozen — the arc record becomes immutable. History entries can still be appended for audit purposes.\nCancellation cascades to all descendants. Children execute in step_order.\nTree Structure # Each arc has a parent_id (root arcs have none) and a step_order for sibling sequencing. This creates an arbitrarily deep tree:\nA root arc might represent \u0026ldquo;deploy new feature\u0026rdquo; Its children are the steps: plan, implement, test, review, merge Each child can have its own children — the implementation step might spawn coding-change sub-workflows Agent Types # Each arc declares an agent type that determines its capabilities:\nType Role Can Do PLANNER Coordination Create arcs, send messages. No data access. EXECUTOR Implementation Full tool access within its taint level. REVIEWER Evaluation Read tools + submit verdict. JUDGE Authority Same as reviewer. Verdict is authoritative. CHAT Conversation Standard chat agent tools. Escalation Policies # When a child arc fails, the parent is notified. The response is governed by the arc\u0026rsquo;s escalation policy:\nPolicy Behavior replan (default) Re-invoke the parent planner to decide next steps fail Let the failure stand human Notify the user escalate Retry with a stronger model Iterative Planning (Ralph Loop) # Complex work often needs iteration. Rather than special loop machinery, Carpenter uses a pattern called the Ralph Loop: a planner creates pairs of sibling arcs — an implementation arc and a monitor arc. Each monitor evaluates the result and, if it decides to continue, creates two more siblings. When a monitor decides \u0026ldquo;done,\u0026rdquo; all children complete and the parent regains agency.\nPlatform-managed performance counters give monitors trustworthy resource data. Each arc maintains descendant_tokens, descendant_executions, and descendant_arc_count, updated by the platform (not executor code) so they can\u0026rsquo;t be tampered with.\nWorkflow Templates # YAML templates constrain arc subtrees for common patterns:\nTemplate Steps Purpose coding-change 3 Write code in isolated workspace, review, merge writing-repo-change 6 Git branch → changes → PR → review → approval → merge platform-modification 8 Most rigorous — for changes to Carpenter itself dark-factory 4 Autonomous spec-driven development with iterative validation Template-created arcs are completely immutable — they can\u0026rsquo;t be deleted, reordered, or have children added. This ensures the workflow structure remains exactly as designed.\n","externalUrl":null,"permalink":"/docs/arcs/","section":"Documentation","summary":"What Is an Arc? # An arc is a unit of work with a lifecycle. It is the only work abstraction in Carpenter — tasks, projects, cron jobs, and sub-steps are all arcs at different depths in a recursive tree.\n","title":"Arcs: The Work Tree","type":"docs"},{"content":" Threat Model # Carpenter\u0026rsquo;s threat model is prompt injection, not adversarial users. The danger is untrusted data — web content, webhooks, API responses — manipulating the AI into generating harmful code.\nThis reframing produces a distinctive architecture: code is sanitized before the reviewer sees it, credentials never leave the platform process, and every state change is persisted as a file on disk.\nThe Review Pipeline # When an agent calls submit_code, the code passes through six stages before execution:\nStage What Happens 1. Hash check SHA-256 against approval cache. Previously approved identical code skips review. 2. Import check import * is unconditionally rejected — no retry. 3. AST parse Reject syntax errors before spending API tokens. 4. Injection scan Regex detection of suspicious patterns. Advisory flags for the reviewer. 5. Histogram analysis A cheap model examines per-source word frequency histograms (comments, strings, docstrings separately) for injection patterns. Advisory, non-blocking. 6. Sanitize + Review The distinctive step (see below). Sanitization: The Core Defense # Before the reviewer AI sees the code, it is sanitized:\nString and bytes literals → placeholders (S1, S2, \u0026hellip;) F-strings → single placeholders User-defined variables → sequential identifiers (a, b, c, \u0026hellip;) Comments and docstrings → stripped Imported names and builtins → preserved The reviewer sees structure and intent without payload content. An attacker can embed instructions in string literals, but the reviewer never sees them — it judges the code\u0026rsquo;s shape, not its data.\nReview Outcomes # Verdict Meaning APPROVE Execute the code REWORK Fixable issues — agent retries (up to 3 times) MAJOR Security concern — requires human decision REJECTED Policy violation — no retry Adversarial Review Mode # An optional mode where the reviewer must find issues. Zero findings means insufficient review, not clean code. Three-pass escalation: standard review → escalated scrutiny → model escalation or human handoff.\nNetwork Egress Control # Executors run with default-deny network egress. Only the platform callback endpoint is reachable. All web access goes through act/web.py via the callback — the platform process makes the actual outbound request; the executor never touches the external network directly.\nThis is enforced at the network level (Docker isolation, network namespaces, or iptables rules), not just by convention.\nCredential Isolation # Credentials never enter the executor environment. The tool system is an RPC client — when executor code calls a tool that needs credentials, the request goes to the platform process, which holds all secrets, rate limits, and audit logs.\nTool tier Mechanism Credential exposure Callback HTTP POST to platform None Direct Pure Python in executor None needed Environment Credential injection Explicitly configured per-tool Execution Sessions # Every code execution gets a platform-generated UUID session, created before the subprocess launches. The executor sends this session ID in callback requests; the platform validates that the session exists, is reviewed, and hasn\u0026rsquo;t expired. A compromised executor cannot spoof review status — session IDs are opaque tokens whose meaning is determined by the platform\u0026rsquo;s database.\n","externalUrl":null,"permalink":"/docs/security/","section":"Documentation","summary":"Threat Model # Carpenter’s threat model is prompt injection, not adversarial users. The danger is untrusted data — web content, webhooks, API responses — manipulating the AI into generating harmful code.\n","title":"Security Model","type":"docs"},{"content":"Carpenter\u0026rsquo;s security model draws on several lines of research in agentic AI security. This page summarizes the key ideas and how they informed the design.\nThe Dual LLM Pattern # Simon Willison, 2023 — The Dual LLM pattern for building AI assistants that can resist prompt injection\nWillison proposed splitting an AI assistant into two separate models: a privileged LLM that handles user instructions and has access to tools, and a quarantined LLM that processes untrusted data (emails, web content) without any tool access. Crucially, raw content handled by the quarantined model is never exposed to the privileged model — instead, it populates opaque references like $email-summary-1 that the privileged model can display without seeing the underlying tokens.\nThis architectural separation prevents untrusted data from hijacking the planning loop. The insight is fundamental: if the model that makes decisions never sees attacker-controlled content, prompt injection has no attack surface.\nIn Carpenter: The review arc system implements this pattern. When an arc processes untrusted data (taint_level=tainted), a separate REVIEWER agent evaluates the output in isolation. The primary agent receives only structured metadata — status, byte count, exit code — never the raw tainted content. This is the dual-LLM pattern applied at the arc level, with the addition of a JUDGE for authoritative verdicts.\nCaMeL: Defeating Prompt Injections by Design # Debenedetti, Shumailov, Fan, Hayes, Carlini, Fabian, Kern, Shi, Terzis, Tramèr (Google DeepMind, 2025) — arXiv:2503.18813\nCaMeL (CApability-Mediated Language) creates a protective system layer around the LLM. It explicitly extracts control flow and data flow from the trusted user query, then enforces that untrusted data retrieved during execution can never impact program flow. A capability system prevents data exfiltration by enforcing security policies at tool-call boundaries.\nThe key advance over the dual-LLM pattern: CaMeL tracks data provenance through the entire execution, tagging every value with its trust origin. This makes it possible to enforce policies like \u0026ldquo;untrusted data may be displayed but never used as a tool argument\u0026rdquo; — a guarantee that doesn\u0026rsquo;t depend on the model\u0026rsquo;s cooperation.\nIn Carpenter: The taint tracking system assigns trust levels to arcs and enforces access control at tool boundaries — clean arcs get HTTP 403 on untrusted data tools, and tainted arc output is never returned to the chat agent\u0026rsquo;s context.\nFIDES: Securing AI Agents with Information-Flow Control # Costa, Köpf, Kolluri, Paverd, Russinovich, Salem, Tople, Wutschitz, Zanella-Béguelin (Microsoft Research, 2025) — arXiv:2505.23643\nFIDES applies classical information-flow control (IFC) to agent security. Every piece of data carries confidentiality and integrity labels that propagate through computation via lattice joins. The system deterministically enforces two policies: trusted actions require high-integrity inputs (P-T), and data flows must respect label constraints (P-F). A novel \u0026ldquo;variable hiding\u0026rdquo; primitive selectively removes low-integrity data from the agent\u0026rsquo;s context when integrity matters.\nWhere CaMeL focuses on preventing untrusted data from influencing control flow, FIDES provides a more general formal framework — it can also enforce confidentiality (preventing data exfiltration) and offers mathematical guarantees (noninterference for integrity, explicit secrecy for confidentiality).\nIn Carpenter: The verification system (carpenter/verify/) implements FIDES-style analysis directly on Python code generated by agents. A three-level integrity lattice (TRUSTED ⊑ CONSTRAINED ⊑ UNTRUSTED) mirrors FIDES\u0026rsquo;s label system, and static taint propagation walks the AST to assign integrity labels to every expression. At the arc level, the taint system provides a coarser-grained layer — arcs carry clean, tainted, or review labels. The tool partitioning (read/ vs act/) mirrors FIDES\u0026rsquo;s policy enforcement at tool boundaries.\nWhere Carpenter Goes Further # The research above provides the theoretical foundation. Carpenter builds on it in several directions.\nCode as the Action Representation # CaMeL mediates between the LLM and tool execution using a custom intermediate language (CaMeL programs). FIDES operates at the level of abstract data labels. Carpenter takes a different approach: the agent writes real Python code, and that code is the action representation.\nThis has a key advantage: the code is both machine-analyzable and human-readable. Standard static analysis — AST parsing, taint propagation, whitelist checking — applies directly. A human auditor can read the same code the review pipeline inspects. There is no translation layer between what the agent intended and what gets executed.\nExhaustive Path Exploration # FIDES enforces safety through static analysis and variable hiding — if low-integrity data appears in a condition, the system conservatively removes it from context. This is sound but rejects some safe workflows.\nCarpenter\u0026rsquo;s verification system (carpenter/verify/) adds a dynamic alternative. When code contains CONSTRAINED data in branch conditions, the system:\nEnumerates representative test values for each constrained input (based on policy types like EmailPolicy, Domain, Url) Computes the cross-product of all input combinations Executes the code with tracked value wrappers for every combination If the total execution tree is bounded (≤150 paths by default), every reachable path is exercised Code that passes all paths is auto-approved without AI review. This proves safety dynamically rather than assuming danger statically — allowing Carpenter to verify workflows that FIDES would conservatively reject.\nA whitelist restricts agent code to a verifiable Python subset (no while loops, no function definitions, no exec) to guarantee the path space remains bounded.\nSanitization as a First-Class Defense # Neither CaMeL nor FIDES addresses prompt injection through generated code. An agent influenced by attacker-controlled data might embed malicious payloads in string literals within its generated code — and a reviewer LLM examining that code would itself be exposed to the injection.\nCarpenter\u0026rsquo;s sanitization step strips all string literal content before the AI reviewer sees the code. The reviewer evaluates structure and intent — function calls, control flow, variable assignments — without ever seeing the actual data values. This closes a prompt injection vector that the prior work doesn\u0026rsquo;t address.\nMeasure N Times, Cut Once # The dual-LLM pattern uses two models. CaMeL and FIDES use a single system layer. Carpenter scales the review process to match the stakes:\nRoutine actions: single-stage automated review Sensitive actions: independent AI reviewer + judge High-stakes actions: multiple independent reviewers, a judge, and separation-of-powers verification — the agent that wrote the code cannot be the agent that judges it This graduated approach means low-risk operations stay fast while high-risk ones get proportionally more scrutiny.\nThe Common Thread # All three approaches share a conviction: you cannot solve prompt injection by hoping the model will be careful. Security must be architectural — enforced by the system layer, not requested of the model. The specific mechanisms differ (model separation, capability tracking, information-flow labels), but the principle is the same: deterministic enforcement at boundaries, not probabilistic cooperation from the AI.\nCarpenter\u0026rsquo;s \u0026ldquo;measure twice, cut once\u0026rdquo; approach sits in this tradition. The review pipeline is a concrete implementation of the principle: every agent action passes through a deterministic inspection chain where code is sanitized, parsed, and structurally reviewed before it can execute. For high-stakes operations, the chain extends — multiple reviewers, a judge, separation-of-powers verification — \u0026ldquo;measure N times, cut once.\u0026rdquo;\n","externalUrl":null,"permalink":"/docs/research/","section":"Documentation","summary":"Carpenter’s security model draws on several lines of research in agentic AI security. This page summarizes the key ideas and how they informed the design.\nThe Dual LLM Pattern # Simon Willison, 2023 — The Dual LLM pattern for building AI assistants that can resist prompt injection\n","title":"Research Foundations","type":"docs"},{"content":" The Problem # An autonomous agent that fetches web content, processes webhooks, or calls external APIs will inevitably encounter attacker-controlled data. The question isn\u0026rsquo;t whether — it\u0026rsquo;s how that data flows through the system without contaminating trusted operations.\nTaint Levels # Every arc carries a taint_level:\nLevel Meaning Restrictions clean Default. No exposure to untrusted data. Cannot access untrusted data tools. tainted Has been exposed to untrusted data. Restricted from modifying trusted state. review Bridge zone for evaluating tainted output. Read tools + submit verdict only. Taint does not propagate upward: a clean parent can orchestrate tainted children without becoming tainted itself. Clean arcs that attempt to use untrusted data tools receive HTTP 403.\nTaint Isolation at Submit # When submit_code executes code that imports untrusted tools (e.g., act/web), the raw output — which may contain attacker-controlled content — is never returned to the chat agent\u0026rsquo;s context. Instead, the agent receives structured metadata: status, output_key, output_bytes, and exit_code. The actual output is stored in arc state for retrieval by review arcs only.\nThis is enforced fail-closed: if the taint check itself fails, output is withheld. The invariant is absolute — no AI sees tainted data unless it is in a designated review arc.\nThe Two-LLM Firewall # When tainted output needs to be trusted, the system creates a review arc (taint_level=review, agent_type=REVIEWER) as a sibling. Individual reviewer verdicts are advisory. A separate JUDGE arc renders the authoritative verdict.\nOn judge approval, the target arc\u0026rsquo;s taint_level is promoted to clean. The judge\u0026rsquo;s authority is scoped to the target arc only — parent arcs are not automatically promoted.\nReview arcs are enforced at creation time: every tainted arc must have at least one reviewer and a judge.\nSeparation of Powers # After a coding-change arc completes, the platform auto-creates verification sibling arcs:\nA correctness check — does it work? A quality check — is it well-structured? (for platform/tool code) A judge — synthesizes results into an authoritative verdict A documentation arc — updates docs if needed Each verification arc carries arc_role=\u0026quot;verifier\u0026quot; and a verification_target_id pointing to the implementation arc. Self-verification is blocked at creation time: the agent that wrote the code cannot be the agent that judges it.\nThis is \u0026ldquo;measure N times, cut once\u0026rdquo; applied to the full development cycle — not just code review, but correctness and quality verification by independent agents.\nEncryption at Rest # Untrusted output can be Fernet-encrypted at rest. Keys are generated per reviewer-target pair and stored in review_keys. Only designated reviewers (or anyone after trust promotion) can decrypt.\nTrust Audit Log # A dedicated append-only table records all boundary decisions: taint assignments, access denials, review verdicts, trust promotions, decryption grants. Separate from arc history to ensure the trust record is always complete and tamper-evident.\n","externalUrl":null,"permalink":"/docs/trust/","section":"Documentation","summary":"The Problem # An autonomous agent that fetches web content, processes webhooks, or calls external APIs will inevitably encounter attacker-controlled data. The question isn’t whether — it’s how that data flows through the system without contaminating trusted operations.\n","title":"Trust \u0026 Taint","type":"docs"},{"content":" Skills # Skills are knowledge-only markdown packages. They implement three-stage progressive disclosure to minimize context window consumption:\nStage What the agent sees Token cost 1. Advertise Compact index in system prompt: name + description ~100 tokens per skill 2. Load Full SKILL.md via load_skill Varies 3. Read Specific resource files via load_skill_resource On demand Skills live at skills_dir/{name}/SKILL.md with optional resources/ directories. Metadata is synced to a skills table in the database.\nSkill Creation and Modification # Agents can create or modify skills via submit_skill, which goes through a skill-specific review pipeline: taint check, hash check, structure validation, injection scan, and AI reviewer.\nTainted conversations cannot modify skills without human review. This prevents a poisoning chain: web content → agent → skill modification → persistent knowledge base corruption.\nThe platform ships with built-in skills (e.g., failure-patterns for common failure modes, iterative-planning for the Ralph Loop pattern). Built-in skills are synced at startup without overwriting user modifications, so they serve as defaults that evolve through experience.\nMemory Architecture # Conversation Boundaries # In single-stream messaging (Signal, Telegram), a 6-hour silence gap triggers a new conversation. At the boundary, a background thread generates a structured summary covering:\nTopics discussed Key decisions made User preferences noted Pending items New conversations receive the prior summary rather than raw message history, preserving continuity without consuming context on stale details.\nCross-Conversation Recall # The knowledge base provides full-text search (FTS5 with BM25 ranking and Porter stemming) across:\nconversations/ — past conversation summaries reflections/ — self-reflection outputs Recent conversation hints (last 3 titles and dates) are appended to the system prompt automatically.\nReflective Self-Improvement # Cadenced self-reflection runs via cron, forming a compression chain:\nCadence Input Output Daily Raw activity data: conversations, arcs, tools, errors Daily notes Weekly Daily reflections + 7-day statistics Weekly patterns Monthly Weekly reflections + 30-day stats + skill catalog Monthly insights Each reflection creates a dedicated conversation, invokes the full chat agent with tool access, saves to the reflections table, and archives the conversation. An activity threshold skips API calls on quiet days.\nReflection Auto-Action # Reflections produce proposed_actions, but observations alone don\u0026rsquo;t close the loop. After a reflection completes, an auto-action process examines proposed actions and submits workable changes through the existing review pipelines.\nThe review level is configurable: AI review, human review, or no review. If the reflection touched tainted data, a separate tainted_review_mode applies (default: human). Rate limits prevent runaway self-modification.\n","externalUrl":null,"permalink":"/docs/skills-and-memory/","section":"Documentation","summary":"Skills # Skills are knowledge-only markdown packages. They implement three-stage progressive disclosure to minimize context window consumption:\nStage What the agent sees Token cost 1. Advertise Compact index in system prompt: name + description ~100 tokens per skill 2. Load Full SKILL.md via load_skill Varies 3. Read Specific resource files via load_skill_resource On demand Skills live at skills_dir/{name}/SKILL.md with optional resources/ directories. Metadata is synced to a skills table in the database.\n","title":"Skills \u0026 Memory","type":"docs"},{"content":" Core vs Platform # Carpenter separates platform-agnostic logic from platform-specific implementations:\nCore (carpenter-ai) — Arc management, review pipeline, trust system, agent loop, model selection, skills, memory Platform packages (carpenter-linux, carpenter-android, etc.) — Executors, sandbox backends, network egress enforcement, platform-specific tools Platform packages are thin. They register their implementations at startup, then hand off to the core:\nfrom carpenter import ( set_platform, register_executor, set_sandbox_provider, add_tool_dir ) set_platform(LinuxPlatform()) register_executor(\u0026#34;subprocess\u0026#34;, SubprocessExecutor()) set_sandbox_provider(LinuxSandboxProvider()) add_tool_dir(\u0026#34;/path/to/platform/tools\u0026#34;) This means the core never imports platform-specific code. New platforms (Android, Windows, macOS) are independent packages that plug into the same core.\nExecutor Backends # Code execution is handled by pluggable executor backends:\nType Isolation level Subprocess (basic) Same-user, env isolation, close_fds, RLIMIT_AS Subprocess (standard) Different-UID, RLIMIT_AS, optional Landlock Docker (single) Platform + executor in one container Docker (orchestrator) Separate containers The platform detects available sandbox methods and falls back gracefully. All subprocess executors enforce a configurable virtual memory limit (default 300MB) via RLIMIT_AS.\nTool System # Tools are partitioned by safety:\ncarpenter_tools/ read/ — safe, direct agentic access act/ — requires reviewed code The @tool() decorator declares safety properties: local, readonly, side_effects, trusted_output. A validation function enforces that read/ tools are all safe and act/ tools have at least one unsafe property.\nThe trusted_output=False declaration (currently only on the web tool) feeds into the taint tracking system — output from untrusted tools is never returned directly to the chat agent.\nModel Selection # A YAML models manifest declares available models with metadata:\nprovider — Anthropic, Ollama model_id — full model identifier cost_tier — low / medium / high context_window — token limit roles — which task types the model suits Arc creation accepts a short name (e.g., \u0026quot;opus\u0026quot;) that resolves to the full provider:model_id. Templates can specify model_min_tier per step — security review steps require high tier, preventing cost optimization from undermining review quality.\nPresets # Four built-in presets route requests to appropriate models:\nPreset Use case fast-chat Quick conversational responses careful-coding Thorough code generation and review background-batch Cost-optimized batch processing caretaker System monitoring and maintenance Resilience # Both AI clients use exponential backoff with jitter for transient failures and a per-provider circuit breaker that fast-fails after consecutive errors. The circuit breaker transitions through CLOSED → OPEN → HALF_OPEN states. HTTP 429 responses are handled by the rate limiter (natural cooldown via sliding window) rather than the circuit breaker.\nConfiguration # All settings via config.yaml or environment variables. Three-layer precedence:\nenv vars \u0026gt; credential files \u0026gt; YAML \u0026gt; built-in defaults No hardcoded credentials in the package. The platform process holds all secrets and exposes them to executors only through the callback RPC layer.\n","externalUrl":null,"permalink":"/docs/platform/","section":"Documentation","summary":"Core vs Platform # Carpenter separates platform-agnostic logic from platform-specific implementations:\nCore (carpenter-ai) — Arc management, review pipeline, trust system, agent loop, model selection, skills, memory Platform packages (carpenter-linux, carpenter-android, etc.) — Executors, sandbox backends, network egress enforcement, platform-specific tools Platform packages are thin. They register their implementations at startup, then hand off to the core:\n","title":"Platform Architecture","type":"docs"},{"content":" A pure-Python AI agent platform where every action is reviewable code. Agents observe freely, but can only act through audited Python — inspected before it runs, not after. Read the Docs Source Code Measure Twice, Cut Once # AI agents are unreliable. Models make mistakes and prompt injections can hijack their behavior — so you can never fully trust what an autonomous agent will do. Most mitigations are probabilistic. Carpenter\u0026rsquo;s are structural.\nEvery action is reviewable Python code, inspected before it runs. A sanitization step strips data from the code before the AI reviewer sees it. When the execution space is bounded, Carpenter proves safety by exploring every path. For high-stakes actions, the pipeline scales to multiple independent reviewers, a judge, and separation of powers.\nThe result is a hard, auditable boundary between intent and action. Read more about our research foundations →\nThree Pillars # Observe Freely # Agents have unrestricted read access — files, state, arc trees, knowledge base, skills. No action is needed to look around. This gives the agent full situational awareness without any security risk. Learn more →\nAct Carefully # Every side effect — file writes, API calls, git operations, state mutations — goes through submit_code. The code is hashed, parsed, sanitized, and reviewed by a separate AI before execution. Learn more →\nLearn Continuously # A compression chain turns raw activity into durable knowledge: daily notes, weekly patterns, monthly insights. Skills crystallize learned patterns. Conversation summaries bridge context across sessions. Learn more →\nCapabilities # Arcs: The Work Tree — One abstraction for tasks, projects, cron jobs, and sub-steps. A recursive tree with a state machine, escalation policies, and iterative planning.\nSecurity Model — Six-stage code review pipeline with sanitization that strips string literals before the reviewer sees them. Network egress denied by default. Credentials never leave the platform process.\nTrust \u0026amp; Taint — Arc-level taint zones, a two-LLM firewall for untrusted data, separation-of-powers verification, and encryption at rest for tainted output.\nSkills \u0026amp; Memory — Three-stage progressive disclosure for skills. Reflective self-improvement via cadenced cron. Full-text search across conversation history.\nMulti-Provider AI — YAML model registry with cost tiers, role-based routing, per-step minimum tier enforcement, circuit breakers, and model escalation.\nPlatform Extensibility — Core logic separated from platform-specific code via dependency injection. Linux, Android, Windows, macOS — each a thin package that registers executors, sandboxes, and tools.\n","externalUrl":null,"permalink":"/","section":"Carpenter","summary":" A pure-Python AI agent platform where every action is reviewable code. Agents observe freely, but can only act through audited Python — inspected before it runs, not after. Read the Docs Source Code ","title":"Carpenter","type":"page"},{"content":"","externalUrl":null,"permalink":"/tags/","section":"Tags","summary":"","title":"Tags","type":"tags"}]