blog index

Control Plane

How the web UI, iPhone app, proxyd, chat backend, the Skills Engine, and the vendor fallback fit.

snapshot 2026-05-05 source src/agentropy/server/proxyd.py, src/skg/generate.py, src/skg/integrations/agent_proxy.py, lib/chat_backend.py, lib/agent_router.py local worktree guide

Control Plane Flow

LLM model-involved step
1User SurfaceWeb UI or iPhone sends chat, decide, roadmap, calls, or dashboard request.
what it is
Web UI or iPhone sends chat, decide, roadmap, calls, or dashboard request.
triggered by
the operator sends a request from the browser or iPhone.
hands off to
proxyd
2proxydAuthenticates, routes, and writes request metadata on the Mac.
what it is
Authenticates, routes, and writes request metadata on the Mac.
triggered by
A valid HTTP route reaches proxyd with the expected token or session.
hands off to
chat_backend
3chat_backendBuilds context from rule files, briefs, reviews, and session history.
what it is
Builds context from rule files, briefs, reviews, and session history.
triggered by
proxyd routes a chat request to the Skills Engine.
hands off to
Skills Engine
4Skills EngineComposes the reply from learned skills on the host, with no vendor call. On a hit it serves the answer (vendor_used=skg-chain).
what it is
Composes the reply from learned skills on the host, with no vendor call. On a hit it serves the answer (vendor_used=skg-chain).
triggered by
chat_backend hands the request to the Skills Engine to compose.
hands off to
Vendor Fallback
5Vendor FallbackLLMOnly on a miss, agent_router calls a vendor; the reply is then captured as a new skill.
what it is
Only on a miss, agent_router calls a vendor; the reply is then captured as a new skill.
triggered by
The Skills Engine has no skill for the request yet.
hands off to
Local State
6Local StateTranscript, attempts, status, and new skills are persisted under ~/.agentropy/proxy and ~/.skg.
what it is
Transcript, attempts, status, and new skills are persisted under ~/.agentropy/proxy and ~/.skg.
triggered by
The request completes, fails, or a vendor reply is learned.
hands off to
The next local run, dashboard view, or review loop.
The Skills Engine composes the reply locally with no vendor call. A vendor is the fallback, isolated behind the router and marked in green, and its reply is learned as a new skill.

Entry Points

Where The User Enters

The browser surface is a single unified shell at /. Per-tab anchors: /#chat, /#decide, /#roadmap, /#calls, /#dashboard, /#skg-log, /#nodes, /#devices. Standalone deep links live at /blog, /plan?session=<id>, /decide?id=<rid>, and /proposals/<name>.

The iPhone app uses /mobile/v1/* routes for pairing, inbox, chat, roadmap, dashboard projections, and growth-governor state.

The web pages are thin control surfaces. The Mac process owns the work, state, vendor routing, and local tools.

Flow

Chat Request Path

  1. User sends a message from /chat or the iPhone app.
  2. proxyd authenticates the request and passes it to chat_backend.
  3. chat_backend builds system context from local rule files, brief files, reviews, and session history.
  4. Skills Engine The Skills Engine (skg.generate) tries to compose the reply from learned skills, running host primitives (clock, files, network reads, gated actions) with no vendor call. On a confident hit it serves the composed answer and returns it (vendor_used = skg-chain).
  5. vendor fallback Only on a miss does agent_router select a vendor (Claude, Codex, OpenAI, or the configured fallback) to answer the turn.
  6. learn The decomposer captures the vendor reply as a new skill in the Skills Engine, so the next equivalent request composes locally with no vendor call.
  7. The final turn is filtered, persisted under ~/.agentropy/proxy/chat/sessions/, and returned to the UI.

Routing

Vendor Routing

The router does not trust a version check as proof of availability. It records success and failure from real calls in vendor-health.json, then reorders future attempts.

Some prompts can carry a vendor pin. A vendor pin narrows the allowed chain when data policy requires it, for example when company-confidential work must stay on the approved vendor.

Skills Engine

Where The Skills Engine Composes And Where Vendors Enter

Skills Engine Chat replies are composed by the Skills Engine first, with no vendor call. A learned skill runs host primitives and renders the answer locally; repeat and parameterized requests (for example the same question about a different city) compose from one learned skill.

vendor A vendor is called only when the Skills Engine has no skill for the request, and for the generative back-office paths: research summaries, weekly review, rule-draft learning, design review, bias checking, and publish review. Those paths enter through agent_router or a vendor-specific tool loop, and the chat reply a vendor produces is captured back into the Skills Engine as a new skill.

Dashboard rendering, device enrollment, status collection, token checks, file projection, and most collector writes are deterministic. They may feed context into a later model call, but they do not call a model themselves.

Vendor calls record metadata in telemetry. Prompt and reply payloads are excluded from call telemetry by design.

State

Shared State

The control plane does not invent a second database for the UI. It projects existing local files into web and mobile views.

Chat sessions, roadmap events, inbox items, approval actions, dashboard status, and growth packets all remain inspectable on disk.