Architecture¶

How Pynchy works under the hood. Read this to 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¶

Each subsystem below 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.