Foundry

<div align="center">

</div>

The persistent control plane for autonomous agentic software development — Kubernetes for AI coding agents

<br>

[!WARNING] Public Beta Notice

Foundry is currently in Active Beta. While the core control loop and state persistence are stable, internal APIs and task schemas may evolve.

Bring Your Own Keys (BYOK): Foundry requires your own agentic subscriptions (API keys for Gemini, Copilot, Cursor, etc.). You are responsible for managing your subscription credentials and associated costs.

Use with caution in production environments. We recommend monitoring execution via the audit.log or verbose logs.

---

⚡ One-Minute Quickstart

Get Foundry running with zero manual configuration. The setup wizard handles infrastructure (Docker), authentication, and launches the dashboard.

# 1. Clone and Install
git clone https://github.com/auto-layer/supervisor.git
cd supervisor
npm install

# 2. Run the Magic Button
# Handles Infra, Auth, State, and Launches the UI Dashboard
npm run setup

Visit: http://localhost:5173 to manage your software factory.

For manual installation, infrastructure setup, or headless environments, see the Manual Setup Guide.

---

What This Is (High level)

Foundry is the Orchestration Layer for AI Software Engineering.

Just as Kubernetes orchestrates containers, Foundry orchestrates Agentic Capabilities. It treats advanced AI tools (Cursor, Copilot, Gemini) not as assistants, but as managed resources.

The Orchestration Lifecycle:

1. Provision: Foundry spins up a clean, isolated context (Sandbox) for a specific task.
2. Dispatch: It routes the task to the most suitable "Worker Node" (e.g., Gemini for reasoning, Cursor for editing).
3. Monitor: It watches the execution in real-time, enforcing constraints (time, scope, file access).
4. Validate & Persist: It runs deterministic checks (tests, AST) and commits the state only when criteria are met.

This moves AI coding from "Chatting with a Bot" to "Managing a Factory."

Foundry operates as a persistent control plane. It runs continuously to:

• Persist state: Save progress after every atomic step to DragonflyDB.
• Retain context: Prevent agent drift by managing the context window explicitly.
• Ensure reliability: Its crash-resilient design allows you to resume exactly where a network/provider halt occurred. No more manual babysitting.

<small>We will incorporate other providers that are model-only approaches, shortly.</small>

Built for multi-day agentic coding workflows. Built for determinism. Built for autonomous workflows for lower costs.

Why Foundry Exists (The Why)

The Challenge with Long Agentic Coding Chains:

• Context degradation: After multiple task repetitions and iterations, agent drift occurs → Links between contexts break → Tasks can't reference prior work reliably
• Manual recovery burden: If execution halts, resuming requires human intervention and feedback → Wasted setup time
• Cost spiral: Without validation, agents make redundant calls → Token costs accumulate
• No audit trail: Can't review what happened or why it failed

The Solution: Foundry acts as a deterministic supervisor for agentic chains. It orchestrates tasks, validates outputs relentlessly, maintains context across repetitions, and keeps costs bounded.

Why Foundry is Different (USPs)

Most agent frameworks (CrewAI, AutoGen) focus on "conversational teams" or "autonomous planning." Foundry focuses on infrastructure-grade execution.

1. The "Headless Worker" Abstraction (BYOK, BYO-CLI)

Instead of rebuilding RAG pipelines from scratch, Foundry wraps standard CLIs & APIs (Cursor, GitHub Copilot, Gemini, Ollama) and drives them as autonomous worker nodes.

• Benefit: Leverage the $20/month proprietary context engines of your providers for free. Foundry manages the session, you get the intelligence.

2. The Anti-Planner (Strict Determinism)

The Execution Engine (Strict Determinism) Foundry is a Task Runner, not a Planner. It decouples intent (the plan) from execution (the agent). By removing the "planning" responsibility from the worker agent, Foundry eliminates recursive scope creep and ensures the agent focuses solely on executing the explicit goals/behaviours defined by the Operator.

• Benefit: Zero scope creep. The Operator defines a list of tasks; Foundry enforces the execution - much like a backlog queue. It never invents new tasks or hallucinates goals, eventhough it might validate and reason a completed task.

3. Local-First "Hybrid" Validation

Foundry uses a cost-optimized validation pipeline that runs free, local deterministic checks (AST analysis, Regex, file capacity) before ever asking an LLM to verify.

• Benefit: Drastically lower token costs. The LLM is treated as a "Judge of Last Resort," not a first-line debugger.

4. Crash-Proof Infrastructure

Modeled after distributed systems, Foundry persists state to DragonflyDB (Redis) after every atomic step.

• Benefit: You can kill the process, upgrade the Supervisor code, restart the server, and resume exactly where it left off—even days later.

How It Works: The Three Pillars (The How)

1. You Control the Scope (Operator Authority)

• Define a goal (what the project achieves)
• Enqueue tasks with acceptance criteria (what each task delivers)
• Provide boilerplate code or existing codebase (starting point)

Foundry never invents scope, expands goals, or makes autonomous decisions. You're in control. It's just execution.

2. Foundry Executes Reliably (Deterministic Validation)

• Tasks run sequentially in an isolated sandbox
• Each output is validated against acceptance criteria
• State persists after every step (DragonflyDB)
• On failure: Auto-retry with feedback, or block and wait for your input

Reduces hallucinations via validation. Maintains context across iterations. Predictable behavior via deterministic checks.

3. Cost-Optimized by Design (Hybrid Control Plane)

Agentic APIs are expensive. Foundry uses a local-first strategy:

• Routine validation runs locally (regex checks, file validation, code structure analysis without API calls) = no API token cost
• Session reuse for agent tasks = token reduction across iterations
• AI agents only handle true reasoning = every API call earns its cost

Result: Multi-day agentic chains with bounded token consumption compared to naive approaches.

Overview

Foundry is a control mechanism that:

• Holds externally injected goals
• Maintains persistent state
• Executes a fixed control loop
• Delegates tasks to provider/agent CLIs
• Validates results
• Retries on validation failures and ambiguity (up to max retries)
• Halts only on critical failures (execution errors, blocked status)

It does not:

• Invent goals
• Act independently
• Replace the operator
• Make autonomous decisions

---

Usage - CLI Based Usage

While the UI Dashboard is the recommended way to operate Foundry, the CLI remains fully functional for automation and power users.

Software Factory Workflow

The typical workflow follows this pattern:

1. Prepare Code Boilerplates (optional but recommended)
2. Initialize Foundry State
3. Set Goal
4. Enqueue Tasks
5. Start Foundry (autonomous execution)

0. Prepare Code Boilerplates (Optional)

Before starting Foundry, you can prepare initial code in the sandbox directory:

# Create project directory
mkdir -p sandbox/my-project

# Copy boilerplate/starter code
cp -r my-boilerplate/* sandbox/my-project/

What to include in boilerplates:

• Project structure (directories, config files)
• Initial dependencies (package.json, requirements.txt, etc.)
• Starter templates (React components, API routes, etc.)

Foundry will work with and build upon this existing code. Tasks can reference existing files, extend functionality, or create new features.

1. Initialize Foundry State - CLI Based Usage

Before using Foundry, initialize the state key:

npm run cli -- init-state --execution-mode AUTO --goal "Build a simple REST API"

2. Set or Update Goal - CLI Based Usage

Define or update the goal Foundry will work towards:

npm run cli -- set-goal \
  --description "A simplified, senior-friendly classifieds super app..." \
  --project-id easeclassifieds

Important: The --project-id should match the directory name in sandbox/ where your boilerplates are located.

3. Create Task File(s)

Create task JSON file(s) following the task schema.

Example: Array of tasks file tasks.json

[
  {
    "task_id": "frontend-001",
    "intent": "Extend existing React component",
    "tool": "gemini",
    "instructions": "Extend the existing App.tsx component to add user authentication.",
    "acceptance_criteria": [
      "App.tsx includes authentication logic",
      "Uses existing React Router setup"
    ],
    "retry_policy": {
      "max_retries": 2
    },
    "status": "pending"
  }
]

4. Enqueue Tasks - CLI Based Usage

Add tasks to the queue:

npm run cli -- enqueue \
  --redis-host localhost \
  --redis-port 6499 \
  --state-key supervisor:state \
  --queue-name tasks \
  --queue-db 2 \
  --task-file tasks/tasks.json

5. Start Foundry Control Loop - CLI