Architecture¶

This section explains how Pynchy works under the hood. Understanding these concepts helps you troubleshoot issues, reason about security boundaries, and extend the system through plugins.

System Overview¶

graph TB
    subgraph plugins ["Plugins"]
        CH["Channels"] ~~~ AC["Agent Cores"] ~~~ INT["Integrations"] ~~~ OBS["Observers"]
        MEM["Memory"] ~~~ TUN["Tunnels"] ~~~ RT["Runtimes"]
    end

    subgraph host ["Host"]
        Registry["Plugin Registry"] ~~~ Messaging
        Orchestrator ~~~ ContainerMgr["Container Manager"]
        MCP["MCP Manager"] ~~~ Security["Security Gate + Cop"]
        Gateway["LLM Gateway"]
    end

    Agent["Agent Containers"]
    MCPCont["MCP Containers"]

    plugins -. "hooks" .-> Registry
    Registry --> Orchestrator
    Registry --> MCP
    Messaging <--> Orchestrator
    Orchestrator <--> ContainerMgr
    ContainerMgr <--> Security
    MCP --> MCPCont
    Security <--> Agent
    Security <--> MCPCont
    Gateway <--> Agent

Core Systems¶

Topic	What it covers
Container isolation	Mounts, runtime plugins, environment variables
IPC	File-based communication between containers and host
Message routing	Routing behavior, transparent token stream
Message types	Type system, storage, SDK integration
Git sync	Coordinated worktree sync, host-mediated merges
Security	Trust model, security boundaries, credential handling
MCP management	McpManager internals, instance deduplication, LiteLLM integration

Pluggable Subsystems¶

These subsystems have dedicated architecture pages explaining their internal design. Each is backed by a pluggy hook and can be extended or replaced via plugins.

Topic	Hook	What it covers
Memory and sessions	`pynchy_memory`	Memory backend contract, session management
Observers	`pynchy_observer`	Event bus, event types, persistence
Tunnels	`pynchy_tunnel`	Connectivity detection, startup checks
Workspaces	`pynchy_workspace_spec`	Managed workspace definitions, config merging
MCP service tools	`pynchy_service_handler`	Host-side tool handlers, security policy

For user-facing documentation on pluggable subsystems (channels, memory, agent cores), see Usage. For the full list of plugin hooks, see Hook Reference.