Sinapsi
A case study in platform engineering for AI agents

Run AI agents like a platform, not like a chat.

Sinapsi is how I manage AI agents the way an organisation manages infrastructure: one door, one source of truth, and rules that say honestly how they are enforced. I built it, and I run it, on my own servers. This page explains why the same shape can work in an enterprise.

By Stefano Ursino · personal research, no employer or client material

The architecture

Seven parts, one drawing

Every agent action crosses the same corridor. The Canon governs everything. The Factory knows how to operate the platform and how to build on it.

InterfacesPhone cockpit, Claude apps, chat lanesSinapsi FactoryOperates and buildsApplicationsServices for peopleThe corridorIdentity, effect, approvalOne gateway, every call auditedtool calls onlyPlatform servicesGit forgeIdentityEvent busSecretsCertificatesDeploysAuditMonitoringTool serversSites and degraded modeTwo sites, same playbooks, a repair pathThe CanonGovernance as code

Interfaces

Claude apps, Claude Code, chat lanes and a phone cockpit. A new interface is a new party, so it has to be granted access before it can act.

In an enterprise
Approved clients, onboarded through an access decision rather than a configuration change.
Still to prove
How many client types an organisation can allow before the access model gets muddy.
Essay: Missions, Not Chats

Sinapsi Factory

The part that knows the platform's rules and procedures. It splits work into missions, starts specialised sessions and checks what comes back. The session that builds a change never merges it.

In an enterprise
The internal agent platform team, with change management for work done by agents.
Still to prove
Reviewer capacity, and what independent review costs per change.
Essay: Missions, Not Chats

Applications

Services built for people on top of the platform. Agents reach them only through tools, and an application may not bypass a platform service.

In an enterprise
Product teams' services that consume platform building blocks.
Still to prove
How much it costs a team to onboard an application to the corridor.
Essay: The Tool Plane

The corridor

One gateway for every call. It checks who is calling, classifies the call as read, write or secret, and writes the decision to an audit stream before anything reaches a system. There are no side doors.

In an enterprise
A central policy enforcement point, so teams add tools without adding credentials.
Still to prove
Throughput, tenant isolation, and who owns the policy.
Essay: The Trust Plane

Platform services

The building blocks that make the platform work: git forge, identity, event bus, secrets and certificates, deploys, audit, monitoring and the tool servers. Every state-changing action emits an event.

In an enterprise
The platform engineering foundations an organisation already runs.
Still to prove
Operating cost, and keeping the audit trail complete across many teams.
Essay: Identity and Secrets Without a Human in the Loop

Sites and degraded mode

Two sites run the same playbooks, and a repair path exists for the day the platform itself is down.

In an enterprise
Multi-region operation, break-glass access and recovery for the agent plane.
Still to prove
Failover drills at real scale.
Essay: One Stack, Reproduced

The Canon

Governance as code: a map of what exists, the rules that regulate it and the sanctioned procedures, kept as typed records in git and shown as a graph. Every rule says whether it is mechanised, reviewed or on the honour system.

In an enterprise
A control library that reports real enforcement status, like control effectiveness in an audit.
Still to prove
Label drift across hundreds of rules.
Essay: Documentation That Cannot Lie
The manifest

Six commitments the platform is built on

  • A bounded door, never raw access.An agent gets a small, audited surface to a system, not its credentials.
  • One source, two consumers.People and agents read the same service, and a check proves they get the same answer.
  • Control from reversibility, review and scope.Gating every command does not scale. Making work easy to undo, reviewed and narrow does.
  • Say how each rule is enforced.A rule labelled as enforced when it is not does more harm than no rule.
  • Authority is earned.Autonomy is granted per class of change, decays if unproven and can be revoked in one move.
  • Work is a mission, not a chat.Bounded scope, an owner, a full context bundle and an independent check on the way back.
From a home server to an enterprise

Why the same shape should scale

Each pattern below runs today across two sites of my own infrastructure. The right-hand column says what I have not proven yet, because that is where the real work for an organisation sits.

PatternIn my labIn an enterpriseStill to prove
One bounded doorAll agent actions cross one gateway. Tools are scoped to an identity and every decision is audited.A central policy enforcement point, so teams add tools without adding credentials.Throughput, tenant isolation and who owns the policy.
One source, two consumersThe cockpit and the agents read one relationship service. A same-answer check compares both.A service catalog and system map that people and agents query the same way.Keeping it fresh across many teams' data.
Governance as code, honestly labelledRules are typed records in git. Each says mechanised, reviewed or honour system.A control library that reports real enforcement, like control-effectiveness in an audit.Label drift across hundreds of rules.
Graduated autonomyActions are sorted by blast radius: green proceeds, yellow asks, red is never autonomous. Authorization layers run in shadow before they enforce.Risk-tiered approval for agent actions, tuned with evidence.Thresholds against real incident cost.
Missions with separation of dutiesThe session that builds a change never merges it. An independent review comes first.Change management for work done by agents.Reviewer capacity and its cost.
Degraded modeTwo sites, the same playbooks and a documented repair path.Break-glass access and recovery for the agent plane itself.Failover drills at real scale.

What this does not show

  • It is one operator on a home-scale lab across two sites. There is no multi-tenant load, no cost model and no organisational change to manage.
  • Some authorization layers still run in shadow mode on purpose. I observe before I enforce.
  • The claim is the shape of the platform and the discipline around it. It is not a claim of enterprise readiness.
Field notes

What running it taught me

Measure the default

A fleet default can be set upstream

Running Claude Code across many hosts, I found that the starting permission mode of sessions started from the app was assigned by the service, not by host configuration. I tried the launch flag, user settings and the managed settings tier. None changed it, and public bug reports described the same behaviour. I kept the control in the gateway and the always-on hooks, where I own it. It later changed upstream with no change on my side.

Delete with evidence

Rarely used is not dead

An audit of my own repository refuted about two thirds of the "this is dead" claims. A yearly certificate rotation and a recovery path are both rare and both load-bearing. Deletion now needs positive evidence, and disabling comes first.

Prove the claim

A green pipeline proves a job exited zero

Success is verified on the host or on the event bus. A same-answer check does this for the control room, and the decision trail does it for every authorization.

Register what runs

A register proves shape, not completeness

A census of the fleet found third-party software that nobody was updating. A check can show that the register is well formed. It cannot show that it is complete, so the platform reports the gap the morning after.

Case study

The control room

The human face of the platform: one cockpit for the person, one door for the agents, and one source of truth behind both.

The problem

A fleet of agents is only useful if I can see what it is doing and answer yes or no from wherever I am. Chat threads do not give me that. Decisions get lost, and each tool describes the lab a little differently.

What I built

  • A decision inbox called Now. Anything an agent cannot decide alone lands as a card with the evidence and two buttons. The answer is recorded once and applied once.
  • A mission ledger. Work is split into bounded missions, each with an owner, a status and a link to the change that did it. I approve goals. An orchestrator session starts the work and checks what comes back.
  • A relationship map. One read-only service knows how the parts of the platform connect. The cockpit and the agents read it through the same door.

Agents enter through the same door. Same question, same answer.

Now 2 waiting

Yellow Approve rule set v3 for the staging door?

Reviewed by an independent session. Changes who may call two tools.

ApproveNot yet
Green Restart the stateless indexer job

Proceeded on its own and was logged. Done 2 min ago.

Demo data, invented for this page

Work 3 missions

Draft access policyIn review
M-101 · policy persona
Rotate the demo certificateDone
M-102 · ops persona
Index the new essayRunning
M-103 · docs persona

Demo data, invented for this page

How it was built

  • Journey first. I modelled who uses it and which decision they face before drawing any screen.
  • Phone first. A screen counts as done only after I have looked at a real rendering on a phone.
  • Separation of duties. The session that builds a change does not merge it.
  • Proof over claims. A same-answer check compares what the cockpit shows with what an agent receives and reports whether they match.
  • Always current. The map follows a merge by itself, in under a minute and without a restart.
Essays

The thinking behind it

Fourteen first-person essays on building and operating software with AI agents. They hold the reasoning, not the tooling. Every example is invented and no real system details appear. A fifteenth, on honest enforcement labels, is in draft.

  1. The manifesto

    Control comes from reversibility, review and scope, not from gating every command.

  2. Documentation That Cannot Lie

    Make the running system the source of truth and flag any claim that no evidence backs.

  3. Grounding the Agent

    Memory inside a session is a cache with no invalidation. Ground every session in a live source.

  4. The Trust Plane

    Never hand an agent raw credentials. Route every action through a policy-enforcing, audited plane.

  5. Proving You Didn't Break It

    For migrations, run old and new side by side on real input and diff the behaviour.

  6. Journey-First Design

    Model the user, the job and the decision points before any pixel.

  7. Deterministic UI

    Every surface traces to an authored spec and a shared design canon.

  8. The Council

    One model is a single point of failure for judgement. Consult several and weigh, do not vote.

  9. One Stack, Reproduced

    One canonical stack, with conventions shared as versioned packages.

  10. Missions, Not Chats

    Structure work as governed missions with a complete context bundle.

  11. The Tool Plane

    An agent is only as safe as its tools, so treat the tool surface as infrastructure.

  12. Identity and Secrets Without a Human in the Loop

    Scoped identity per actor and secrets delivered at runtime, never pasted.

  13. The Decision Trail

    Emit every decision as a typed, correlated event so "why was this allowed?" is one query.

  14. Continuous Trust

    Authority to proceed alone is earned, decays if unproven and can be revoked in one move.

Code

The doors, as running code

  • Sshgw.Mcp

    An agent's SSH access as a bounded door: a per-server command whitelist, each command classified by effect, every decision sent to an audit stream.

  • Sinapsi.SentinelConsole

    One live screen of the authorization decisions across the layers.

  • StepCa.Mcp

    Issue and inspect certificates from an internal CA through a six-tool surface.

  • Zitadel.Mcp

    Machine users, OIDC apps and grants on an identity server, with the bearer held server-side.

  • Infisical.Mcp

    Runtime secret delivery behind four tools, so no one pastes a credential.

  • Sinapsi.Indexer

    Searchable memory over source-of-truth git repos, kept fresh by push events.

Thirteen MCP servers and four shared libraries in total, written for .NET 8. It is a curated, read-only snapshot of exploratory code, and it changes when I learn something. Browse it on GitHub.