# aindy-runtime

> A self-hostable AI agent execution runtime for building and operating AI-powered systems.
> Created by Shawn Knight — [Masterplan Infinite Weave](https://www.the-master-plan.com/)

aindy-runtime is the execution substrate of the A.I.N.D.Y. platform. It provides a
syscall-based execution contract, a DAG flow engine with WAIT/RESUME semantics, persistent
vector memory, structured agent runs with capability tokens, and an extensible plugin
registry for mounting domain-specific app layers. Ships as `aindy-runtime` on PyPI.
Deploy in minutes via Docker Compose. Extend via a Python plugin registry.

## Core Documentation

- [README.md](README.md): Quickstart, install, CLI, deployment profiles, building apps on aindy-runtime
- [docs/runtime/ARCHITECTURE.md](docs/runtime/ARCHITECTURE.md): Layer model, execution pipeline, kernel internals, flow engine, agent runtime, memory system
- [docs/runtime/SYSCALL_SYSTEM.md](docs/runtime/SYSCALL_SYSTEM.md): SyscallDispatcher contract, registry, capability enforcement, idempotency gate, envelope format
- [docs/runtime/EXECUTION_CONTRACT.md](docs/runtime/EXECUTION_CONTRACT.md): Execution guarantees, state machine, resource limits, failure model
- [docs/runtime/EXECUTION_INVARIANTS.md](docs/runtime/EXECUTION_INVARIANTS.md): Documented runtime invariants — flow engine, scheduler, memory, agent, syscall
- [docs/runtime/AGENT_RUNTIME.md](docs/runtime/AGENT_RUNTIME.md): Agent run lifecycle — create, plan, approve, execute, capability tokens, trigger evaluation
- [docs/runtime/IDEMPOTENCY_CONTRACT.md](docs/runtime/IDEMPOTENCY_CONTRACT.md): EXACTLY_ONCE handlers, EffectRecord gate, per-syscall idempotency guarantees
- [docs/runtime/RUNTIME_STABILITY_INDEX.md](docs/runtime/RUNTIME_STABILITY_INDEX.md): Per-surface stability tiers (Stable / Experimental) for HTTP, syscall, extension, and memory surfaces
- [docs/runtime/PUBLIC_RUNTIME_SURFACES.md](docs/runtime/PUBLIC_RUNTIME_SURFACES.md): Complete inventory of stable public HTTP and syscall surfaces
- [llms-full.txt](llms-full.txt): Full content summaries for AI indexers

## Architecture

- [docs/runtime/RUNTIME_MODULE_MAP.md](docs/runtime/RUNTIME_MODULE_MAP.md): Tagged inventory of every module — layer, owner, stability, blast radius
- [docs/runtime/RUNTIME_BOUNDARY.md](docs/runtime/RUNTIME_BOUNDARY.md): What aindy-runtime owns vs. what belongs in aindy-apps-monolith
- [docs/runtime/FOUNDATIONAL_PATTERN.md](docs/runtime/FOUNDATIONAL_PATTERN.md): Design patterns — ExecutionPipeline, SyscallDispatcher, plugin registry, capability model
- [docs/runtime/MEMORY_ADDRESS_SPACE.md](docs/runtime/MEMORY_ADDRESS_SPACE.md): MemoryNode storage, MAS path structure, hybrid retrieval, embedding pipeline
- [docs/runtime/SCHEMA_LIFECYCLE.md](docs/runtime/SCHEMA_LIFECYCLE.md): Schema contract versioning, blank-bootstrap, reconcile, enforce-schema flow
- [docs/runtime/RETRY_POLICY.md](docs/runtime/RETRY_POLICY.md): RetryPolicy model, backoff strategies, syscall-level retry contract
- [docs/runtime/DEGRADED_RUNTIME_MODES.md](docs/runtime/DEGRADED_RUNTIME_MODES.md): What degrades when Redis, Mongo, or the scheduler is unavailable

## Extension and Plugin System

- [docs/runtime/EXTENSION_ABI.md](docs/runtime/EXTENSION_ABI.md): Plugin ABI — register_router, register_flow, register_job, register_syscall, boot-order hooks
- [docs/runtime/EXTENSION_TRUST_MODEL.md](docs/runtime/EXTENSION_TRUST_MODEL.md): Trust levels (trusted-internal vs. untrusted), sandbox policy, capability grant model
- [docs/runtime/EXTENSION_CAPABILITIES.md](docs/runtime/EXTENSION_CAPABILITIES.md): Per-extension capability definitions and enforcement
- [docs/runtime/EXTENSION_PROVENANCE.md](docs/runtime/EXTENSION_PROVENANCE.md): Extension identity, origin tracking, inventory at runtime

## SDK and Integrations

- [docs/runtime/SDK_CONTRACT.md](docs/runtime/SDK_CONTRACT.md): Stable surfaces the aindy-sdk depends on — auth, version, memory, platform keys
- [docs/runtime/UI_CONTRACT.md](docs/runtime/UI_CONTRACT.md): Platform SPA contracts — auth flow, boot identity, route gating, API base URL
- [docs/runtime/CONDITION_CODES.md](docs/runtime/CONDITION_CODES.md): Stable operator-facing condition codes — RuntimeConditionCode, ReadinessBlockerCode, FlowRunStatus, AgentRunStatus, and all status enums

## Deployment and Operations

- [docs/runtime/DEPLOYMENT_PROFILES.md](docs/runtime/DEPLOYMENT_PROFILES.md): All deployment profiles — single-instance, distributed-api, distributed-worker, hostile-third-party
- [docs/runtime/RUNTIME_ONLY_DEPLOYMENT.md](docs/runtime/RUNTIME_ONLY_DEPLOYMENT.md): Runtime-only (no app plugins) deployment guide
- [docs/runtime/OPERATOR_RUNBOOK.md](docs/runtime/OPERATOR_RUNBOOK.md): Production runbook — health checks, schema reconcile, Redis failover, stuck-run recovery
- [docs/runtime/PROFILE_SUPPORT_MATRIX.md](docs/runtime/PROFILE_SUPPORT_MATRIX.md): Feature support matrix across all deployment profiles
- [docs/runtime/DEGRADED_MODE_MATRIX.md](docs/runtime/DEGRADED_MODE_MATRIX.md): Service degradation matrix — which features fail, which degrade, which are unaffected

## Security

- [docs/runtime/SECURITY_POSTURE.md](docs/runtime/SECURITY_POSTURE.md): Security boundaries, enforcement paths, capability model, auth surface
- [docs/runtime/SECURITY_MATRIX.md](docs/runtime/SECURITY_MATRIX.md): Threat-model matrix — attack surfaces, mitigations, residual risks
- [docs/runtime/SANDBOX_ESCAPE_AUDIT.md](docs/runtime/SANDBOX_ESCAPE_AUDIT.md): Container sandbox escape audit, test posture, macOS/Linux/WSL2 results
- [docs/runtime/EXTENSION_TRUST_MODEL.md](docs/runtime/EXTENSION_TRUST_MODEL.md): In-process extension trust enforcement

## Governance and Release

- [docs/runtime/RELEASE_CHECKLIST.md](docs/runtime/RELEASE_CHECKLIST.md): Full release verification checklist — 16 gates including sandbox certification
- [docs/runtime/RELEASE_GATES.md](docs/runtime/RELEASE_GATES.md): Release gate definitions and pass/fail criteria
- [docs/runtime/CROSS_REPO_COMPATIBILITY.md](docs/runtime/CROSS_REPO_COMPATIBILITY.md): Compatibility policy between aindy-runtime, aindy-sdk, and aindy-apps-monolith
- [TECH_DEBT.md](TECH_DEBT.md): Open known issues with status and fix directions

## Wiki

The aindy-runtime wiki is the user-facing reference for operators, app builders, and integrators.

- [aindy-runtime Wiki](https://github.com/Masterplanner25/aindy-runtime/wiki) — 15 pages covering deployment, syscalls, flows, agents, memory, plugins, and operations
  - [Getting Started](https://github.com/Masterplanner25/aindy-runtime/wiki/Getting-Started)
  - [Architecture](https://github.com/Masterplanner25/aindy-runtime/wiki/Architecture)
  - [Configuration](https://github.com/Masterplanner25/aindy-runtime/wiki/Configuration)
  - [Deployment Profiles](https://github.com/Masterplanner25/aindy-runtime/wiki/Deployment-Profiles)
  - [Syscall System](https://github.com/Masterplanner25/aindy-runtime/wiki/Syscall-System)
  - [Flow Engine](https://github.com/Masterplanner25/aindy-runtime/wiki/Flow-Engine)
  - [Agent Runtime](https://github.com/Masterplanner25/aindy-runtime/wiki/Agent-Runtime)
  - [Memory System](https://github.com/Masterplanner25/aindy-runtime/wiki/Memory-System)
  - [Plugin Registry](https://github.com/Masterplanner25/aindy-runtime/wiki/Plugin-Registry)
  - [REST API](https://github.com/Masterplanner25/aindy-runtime/wiki/REST-API)
  - [Operator Guide](https://github.com/Masterplanner25/aindy-runtime/wiki/Operator-Guide)
  - [Condition Codes](https://github.com/Masterplanner25/aindy-runtime/wiki/Condition-Codes)
  - [Security](https://github.com/Masterplanner25/aindy-runtime/wiki/Security)
  - [Changelog](https://github.com/Masterplanner25/aindy-runtime/wiki/Changelog)

## Ecosystem

aindy-runtime is the execution substrate of the A.I.N.D.Y. platform and part of the
Masterplan Infinite Weave ecosystem.

- [Masterplan Infinite Weave](https://www.the-master-plan.com/) — the broader ecosystem
- [github.com/Masterplanner25](https://github.com/Masterplanner25) — all repos
- [aindy-apps-monolith](https://github.com/Masterplanner25/aindy-apps-monolith) — 16 domain apps built on the plugin registry; reference implementation
- [aindy-sdk](https://github.com/Masterplanner25/aindy-sdk) — Python SDK for external HTTP integration
- [nodus-lang](https://github.com/Masterplanner25/Nodus) — orchestration DSL that powers aindy-runtime's flow and agent execution layer

## Creator

Shawn Knight — creator of A.I.N.D.Y. and architect of the Masterplan Infinite Weave.

- Web: [the-master-plan.com](https://www.the-master-plan.com/)
- GitHub: [Masterplanner25](https://github.com/Masterplanner25)

## Key Concepts

- **aindy-runtime** — the execution substrate of the A.I.N.D.Y. platform; a self-hostable FastAPI + Python package that runs agent workflows, DAG flows, and vector memory
- **A.I.N.D.Y.** — Artificially Intelligent Networked Dynamic You; the AI platform aindy-runtime powers
- **Masterplan Infinite Weave** — the AI-native ecosystem aindy-runtime is the execution layer of; built on the Infinity Algorithm model
- **Infinity Algorithm** — the I→T→C→R→O→Feedback execution model implemented by aindy-runtime's agent and flow systems
- **SyscallDispatcher** — the single entry point for all capability calls; validates, enforces capabilities, gates idempotency, and returns a uniform envelope
- **syscall** — a named capability call in the format `sys.v1.domain.action`; validated, schema-checked, capability-enforced
- **ExecutionUnit** — the abstract DB row that tracks any in-flight execution (flow, agent, job) with status and timestamps
- **FlowRun** — a single execution instance of a DAG flow; states: `running`, `waiting`, `completed`, `failed`
- **WAIT/RESUME** — the flow suspension model: `sys.v1.event.wait` suspends a flow; `sys.v1.event.emit` resumes it; crash-safe via rehydration
- **AgentRun** — a structured agent execution; states: `pending_approval`, `approved`, `executing`, `delegated`, `completed`, `failed`
- **approval gate** — every agent run must be approved before execution begins; enforced atomically via CAS on the DB row
- **capability token** — a scoped credential minted at agent approval time; limits which syscalls the agent may call during execution
- **MemoryNode** — the persistent memory unit; stored in PostgreSQL with a 1536-dim pgvector embedding, namespace, type, tags, and MAS path
- **MAS (Memory Address Space)** — path-based addressing for memory: `/memory/{tenant}/{namespace}/{type}/{id}`
- **hybrid retrieval** — memory search combining vector similarity, tag filter, and MAS path query; ranked by impact score × usage count × causal depth
- **EffectRecord** — the idempotency gate for `EXACTLY_ONCE` syscall handlers; prevents double-execution on retried requests
- **PluginRegistry** — the extension mechanism; plugins register routers, flows, jobs, syscalls, capabilities, tools, event handlers, and startup hooks
- **deployment profile** — controls infrastructure requirements and scheduler leadership; values: `single-instance`, `distributed-api`, `distributed-worker`, `hostile-third-party`
- **RuntimeConditionCode** — a stable string code emitted when the runtime enters a degraded state; appears in `/ready` and `/health` responses
- **condition classification** — severity of a runtime condition: `safe_degraded` (advisory), `unsafe_degraded` (blocks /ready), `startup_fatal` (blocks startup in production)
- **nodus-lang** — the orchestration DSL that powers aindy-runtime's flow and agent execution layer; `.nd` scripts execute via `sys.v1.nodus.execute`
- **platform-only boot** — `AINDY_BOOT_MODE=runtime-only`; starts the runtime without loading any app plugins; all core syscalls, flows, memory, and platform UI remain available
- **trusted-internal** — the maximum security claim for v1.0; all connected plugins and operators are assumed to be under operator control; hostile third-party workloads require the `hostile-third-party` profile

## Package

- PyPI: `aindy-runtime` (v1.0.0 — current)
- Install: `pip install aindy-runtime`
- Module: `AINDY` (uppercase — it is an acronym)
- Console script: `aindy-runtime serve` (API), `aindy-runtime worker` (background worker)
- Python >= 3.11
- PostgreSQL with pgvector extension required
- Redis optional (required for distributed profiles)
