Linchpin / Architecture

Architecture

Three services plus Postgres, all under one docker-compose.yml. Per-session Docker containers as the sandbox. Append-only event log streamable over SSE. Apache-2.0.

Fig. 01 · Runtime Schematic
Linchpin / 2026
Client SDK · curl Console HTTP/SSE LINCHPIN-API Orchestrator Policy · Vaults · Events SSE · LISTEN/NOTIFY Sandbox Manager › Built-in Tools postgres:16 POST /tools/invoke Connector MCP stdio HTTP tools docker-py Session 1 ubuntu:22.04 Session 2 ubuntu:22.04
Scale 1:1 · DWG 01
Sheet A — Architecture
§ 01 / Orchestrator

One async task per session

Builds context from the event log, calls the model provider, emits agent.message / agent.tool_use events. On tool use it evaluates policy: always_allow runs immediately; always_ask blocks on LISTEN/NOTIFY until confirmation arrives.

§ 02 / Sandbox

Per-session Docker containers

Each session is a fresh container the API spawns via docker-py. Two networks pre-created at startup: linchpin-none (no egress) and linchpin-open (full egress). The environment's networking.type chooses which.

§ 03 / Event log

Append-only, cursor-paginated

Each event has a monotonic sequence and an opaque cursor. SSE replays everything after the client's cursor before switching to live. Crash recovery replays the log to put non-terminal sessions back in the right state.

§ 04 / Vault

Fernet-encrypted credentials

Per-vault encrypted secret store. Sessions bind to one or more vault IDs; credentials are decrypted in-process and passed as api_key to the provider or as env vars to MCP subprocesses. Nothing on disk in plaintext.