# luckypipewrench/pipelock architecture

> Architecture diagram of the GitHub repository luckypipewrench/pipelock, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/luckypipewrench/pipelock
- Repository: https://github.com/luckypipewrench/pipelock

## Overview

Pipelock is an AI-agent egress firewall: an operator routes an agent’s network activity through Pipelock, which mediates and scans traffic, applies policy, and records signed evidence for later review. Its runtime also supports MCP mediation, containment, and deferred decisions; users can inspect or verify evidence offline. The repository includes a separate public-playground system and enterprise fleet/dashboard services. Relationships below are limited to README statements and sampled-source references; unsampled subsystem wiring is not asserted.

Main entry points: [`internal/cli/runtime/server.go`](https://github.com/luckypipewrench/pipelock/blob/main/internal/cli/runtime/server.go) (Proxy runtime), [`internal/mcp/pipeline_gates.go`](https://github.com/luckypipewrench/pipelock/blob/main/internal/mcp/pipeline_gates.go) (MCP gates), [`cmd/pipelock/main.go`](https://github.com/luckypipewrench/pipelock/blob/main/cmd/pipelock/main.go) (Pipelock CLI), [`internal/recorder`](https://github.com/luckypipewrench/pipelock/tree/main/internal/recorder) (Flight recorder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Mediation runtime"]
  node_cli["Pipelock CLI<br/>[main.go]"]
  node_config["Runtime config"]
  node_runtime_server["Proxy runtime<br/>[server.go]"]
  node_proxy["HTTP proxy"]
  node_mcp["MCP gates<br/>[pipeline_gates.go]"]
  node_scanner["Content scanner"]
  node_scan_api["Scan API<br/>[handler.go]"]
  node_deferred["Deferred actions<br/>[manager.go]"]
end

subgraph group_evidence["Evidence and review"]
  node_receipts["Signed receipts"]
  node_recorder[("Flight recorder")]
  node_evidence_view["Evidence viewer"]
  node_verifier["Receipt verifier"]
end

subgraph group_controls["Agent controls"]
  node_containment["Host containment"]
  node_sandbox["Process sandbox"]
end

subgraph group_playground["Public playground"]
  node_playground_broker["Playground broker<br/>[server.go]"]
  node_playground_live["Live chat<br/>[server.go]"]
  node_playground_agent["Model agent<br/>[main.go]"]
end

subgraph group_enterprise["Enterprise services"]
  node_dashboard["Fleet dashboard<br/>[handler.go]"]
  node_fleet_sink[("Fleet audit store<br/>[storage.go]")]
end

node_operator(("Operator"))
node_agent(("AI agent"))

node_operator -->|"configures and runs"| node_cli
node_agent -->|"routes traffic through"| node_runtime_server
node_cli -->|"starts"| node_runtime_server
node_runtime_server -->|"loads policy"| node_config
node_runtime_server -->|"constructs"| node_proxy
node_runtime_server -->|"integrates"| node_mcp
node_runtime_server -->|"constructs"| node_scanner
node_mcp -->|"scans content"| node_scanner
node_mcp -->|"reads policy"| node_config
node_runtime_server -->|"uses"| node_deferred
node_runtime_server -.->|"records decisions"| node_recorder
node_runtime_server -->|"emits decisions"| node_receipts
node_runtime_server -.->|"supports deployment"| node_containment
node_runtime_server -.->|"supports deployment"| node_sandbox
node_operator -->|"reviews session"| node_evidence_view
node_recorder -->|"reads session"| node_evidence_view
node_operator -->|"verifies receipt"| node_verifier
node_operator -->|"visits playground"| node_playground_broker
node_playground_broker -->|"proxies sessions"| node_playground_live
node_playground_live -.->|"runs agent"| node_playground_agent
node_dashboard -.->|"queries audit data"| node_fleet_sink

click node_cli "https://github.com/luckypipewrench/pipelock/blob/main/cmd/pipelock/main.go"
click node_config "https://github.com/luckypipewrench/pipelock/tree/main/internal/config"
click node_runtime_server "https://github.com/luckypipewrench/pipelock/blob/main/internal/cli/runtime/server.go"
click node_proxy "https://github.com/luckypipewrench/pipelock/tree/main/internal/proxy"
click node_mcp "https://github.com/luckypipewrench/pipelock/blob/main/internal/mcp/pipeline_gates.go"
click node_scanner "https://github.com/luckypipewrench/pipelock/tree/main/internal/scanner"
click node_scan_api "https://github.com/luckypipewrench/pipelock/blob/main/internal/scanapi/handler.go"
click node_deferred "https://github.com/luckypipewrench/pipelock/blob/main/internal/deferred/manager.go"
click node_containment "https://github.com/luckypipewrench/pipelock/tree/main/internal/cli/contain"
click node_sandbox "https://github.com/luckypipewrench/pipelock/tree/main/internal/sandbox"
click node_receipts "https://github.com/luckypipewrench/pipelock/tree/main/internal/contract/receipt"
click node_recorder "https://github.com/luckypipewrench/pipelock/tree/main/internal/recorder"
click node_evidence_view "https://github.com/luckypipewrench/pipelock/tree/main/internal/cli/evidence"
click node_verifier "https://github.com/luckypipewrench/pipelock/tree/main/cmd/pipelock-verifier"
click node_playground_broker "https://github.com/luckypipewrench/pipelock/blob/main/internal/playground/broker/server.go"
click node_playground_live "https://github.com/luckypipewrench/pipelock/blob/main/internal/playground/livechat/server.go"
click node_playground_agent "https://github.com/luckypipewrench/pipelock/blob/main/cmd/pipelock-playground-llm-agent/main.go"
click node_dashboard "https://github.com/luckypipewrench/pipelock/blob/main/enterprise/dashboard/handler.go"
click node_fleet_sink "https://github.com/luckypipewrench/pipelock/blob/main/enterprise/fleet/sink/storage.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_config,node_runtime_server,node_proxy,node_mcp,node_scanner,node_scan_api,node_deferred toneBlue
class node_receipts,node_recorder,node_evidence_view,node_verifier toneAmber
class node_containment,node_sandbox toneMint
class node_playground_broker,node_playground_live,node_playground_agent toneRose
class node_dashboard,node_fleet_sink,node_operator,node_agent toneIndigo
```

## Components

### Mediation runtime

- [Pipelock CLI](https://github.com/luckypipewrench/pipelock/blob/main/cmd/pipelock/main.go): `cmd/pipelock/main.go`
- [Runtime config](https://github.com/luckypipewrench/pipelock/tree/main/internal/config): `internal/config`
- [Proxy runtime](https://github.com/luckypipewrench/pipelock/blob/main/internal/cli/runtime/server.go): `internal/cli/runtime/server.go`
- [HTTP proxy](https://github.com/luckypipewrench/pipelock/tree/main/internal/proxy): `internal/proxy`
- [MCP gates](https://github.com/luckypipewrench/pipelock/blob/main/internal/mcp/pipeline_gates.go): `internal/mcp/pipeline_gates.go`
- [Content scanner](https://github.com/luckypipewrench/pipelock/tree/main/internal/scanner): `internal/scanner`
- [Scan API](https://github.com/luckypipewrench/pipelock/blob/main/internal/scanapi/handler.go): `internal/scanapi/handler.go`
- [Deferred actions](https://github.com/luckypipewrench/pipelock/blob/main/internal/deferred/manager.go): `internal/deferred/manager.go`

### Evidence and review

- [Signed receipts](https://github.com/luckypipewrench/pipelock/tree/main/internal/contract/receipt): `internal/contract/receipt`
- [Flight recorder](https://github.com/luckypipewrench/pipelock/tree/main/internal/recorder): `internal/recorder`
- [Evidence viewer](https://github.com/luckypipewrench/pipelock/tree/main/internal/cli/evidence): `internal/cli/evidence`
- [Receipt verifier](https://github.com/luckypipewrench/pipelock/tree/main/cmd/pipelock-verifier): `cmd/pipelock-verifier`

### Agent controls

- [Host containment](https://github.com/luckypipewrench/pipelock/tree/main/internal/cli/contain): `internal/cli/contain`
- [Process sandbox](https://github.com/luckypipewrench/pipelock/tree/main/internal/sandbox): `internal/sandbox`

### Public playground

- [Playground broker](https://github.com/luckypipewrench/pipelock/blob/main/internal/playground/broker/server.go): `internal/playground/broker/server.go`
- [Live chat](https://github.com/luckypipewrench/pipelock/blob/main/internal/playground/livechat/server.go): `internal/playground/livechat/server.go`
- [Model agent](https://github.com/luckypipewrench/pipelock/blob/main/cmd/pipelock-playground-llm-agent/main.go): `cmd/pipelock-playground-llm-agent/main.go`

### Enterprise services

- [Fleet dashboard](https://github.com/luckypipewrench/pipelock/blob/main/enterprise/dashboard/handler.go): `enterprise/dashboard/handler.go`
- [Fleet audit store](https://github.com/luckypipewrench/pipelock/blob/main/enterprise/fleet/sink/storage.go): `enterprise/fleet/sink/storage.go`

### Other components

- **Operator**
- **AI agent**

## Connections

- Operator → Pipelock CLI: configures and runs
- AI agent → Proxy runtime: routes traffic through
- Pipelock CLI → Proxy runtime: starts (evidence: `internal/cli/runtime/server.go`)
- Proxy runtime → Runtime config: loads policy (evidence: `internal/cli/runtime/server.go`)
- Proxy runtime → HTTP proxy: constructs (evidence: `internal/cli/runtime/server.go`)
- Proxy runtime → MCP gates: integrates (evidence: `internal/cli/runtime/server.go`)
- Proxy runtime → Content scanner: constructs (evidence: `internal/cli/runtime/server.go`)
- MCP gates → Content scanner: scans content (evidence: `internal/mcp/pipeline_gates.go`)
- MCP gates → Runtime config: reads policy (evidence: `internal/mcp/pipeline_gates.go`)
- Proxy runtime → Deferred actions: uses (evidence: `internal/cli/runtime/server.go`)
- Proxy runtime → Flight recorder: records decisions (evidence: `internal/cli/runtime/server.go`)
- Proxy runtime → Signed receipts: emits decisions
- Proxy runtime → Host containment: supports deployment
- Proxy runtime → Process sandbox: supports deployment
- Operator → Evidence viewer: reviews session
- Flight recorder → Evidence viewer: reads session
- Operator → Receipt verifier: verifies receipt
- Operator → Playground broker: visits playground
- Playground broker → Live chat: proxies sessions (evidence: `internal/playground/broker/server.go`)
- Live chat → Model agent: runs agent
- Fleet dashboard → Fleet audit store: queries audit data
