← Back to home

Architecture

Agent Orchestration

A self-hosted workspace where people and AI agents work together, with hard limits on what an agent can see, spend and do.

1. The problem

You want AI agents to do real work: spend money on model calls, run code, take actions. Three things go wrong, and none of them is the model answering badly.

The API key leaks, because it ended up in the environment of a service that never needed it. The budget overruns, because nobody knows what a call costs until it finishes. And the agent takes an irreversible action nobody authorised, because the text the person read before approving was written by the model itself.

The engineering problem is not making the agent work. It is making sure it cannot do those three things, even when the model is steered by injected text and even when one of the services is compromised.

2. The numbers

Counted in the repository. The attack suite and the tests run in CI on every push.

20,152
lines of Rust across 6 crates: gateway 6,950, server 6,448, engine 3,711, bench 1,558, sandbox 1,197, protocol 288
135
Rust tests
7
named attacks, each with a test that has to pass
18
audit triggers written in the database
13
migrations
3
PostgreSQL roles, one per service. The sandbox has none
3
spending limit levels: workspace per month, agent per month, and task
127.0.0.1
address every service listens on

3. The design

The design is about trust boundaries: where the key lives, who never receives it, and what the model is not allowed to write.

127.0.0.1 — everything localWebNext.jsServeraccounts, sessions, rolesEngineruns, tools, approvalsSandboxno network · no databaserun_pythonrequest, no keyGatewayvault: the key lives only herePostgreSQL3 roles, one per service · 18 audit triggerswith the keyProvidersAnthropic · OpenAI · Gemini

The provider key crosses the external boundary at exactly one point, leaving the gateway. The engine, the sandbox and the web server never receive it, and refuse to start if they find one in their own environment. The sandbox is the least privileged service in the system: no network and no database role.

The seven attacks, and what stops each one

THREAT_MODEL.md describes the model. ATTACKS.md names each attack, and every named attack has a test that must pass before a merge.

Attack 01

Read the provider key

What stops it

The key lives encrypted in the gateway's vault. The engine, the sandbox and the web server never receive any key, and refuse to start if they find one in their environment.

Attack 02

Spend more than allowed

What stops it

Every call reserves its maximum cost before it begins. With no reserved balance, the call does not happen.

Attack 03

Leave the allowed folder

What stops it

The sandbox runs in a read-only container with no capabilities and limits on memory, CPU, processes and time.

Attack 04

Reach addresses that are not allowed

What stops it

The sandbox has no network.

Attack 05

Act without permission, or be steered by injected text

What stops it

A tool marked irreversible stops the task and waits for a person. The text explaining what will happen is written by the developer in the tool definition, never by the model.

Attack 06

Impersonate someone or steal a session

What stops it

__Host- cookies with Secure, HttpOnly and SameSite Strict, checked by the Rust server on every request, under a strict CSP with a per-request nonce.

Attack 07

Tamper with records

What stops it

An append-only, hash-chained log written by database triggers. Editing or deleting breaks the chain.

4. The decisions

Every decision has a price. Below is what I chose, what I rejected, why, and what it costs.

01. Reserve the maximum cost before the call

Chose
Every model call reserves the highest possible cost before it starts. A task with nothing left to reserve stops and waits for an administrator.
Over
Metering spend after the response comes back.
Because
A call's cost is only known once it finishes, and by then the money is gone. Metering afterwards detects an overrun, it does not prevent one. Reserving the maximum up front makes passing the limit structurally impossible rather than a matter of vigilance.
Price I pay
The budget is under-used. A task can be stopped with real balance left, because the reservation assumed the worst case and the actual response cost less.

02. The approval text is written by the developer, never by the model

Chose
What will happen lives in the tool definition, written by hand by whoever implemented it. The person approves by reading that text.
Over
Letting the model explain what it is about to do.
Because
If the model writes the explanation, a model steered by injected text writes a reassuring one. The person approves a lie and carries the blame. Taking that pen away from the model is what makes human approval worth anything.
Price I pay
Every new tool needs its text written by hand, and the agent cannot create tools on its own. The flexibility is removed on purpose.

03. Audit through database triggers, not application code

Chose
18 triggers write every change to the log, regardless of who performed the write.
Over
Logging the event from the service code.
Because
Application-level logging can be bypassed: a bug, a direct database connection, a future service that forgets to call it. A trigger fires anyway. The guarantee stops depending on discipline.
Price I pay
Logic lives in SQL, which is harder to test and to change, and migrations get heavier. Every new table needs its trigger alongside it, or the gap is silent.

04. Append-only, hash-chained log

Chose
Each record carries the hash of the previous one. Nothing is updated and nothing is deleted.
Over
A normal table with timestamps.
Because
A plain table can be edited by anyone with write access, and afterwards you cannot prove it was not. Chaining makes any edit or deletion break the chain and become detectable.
Price I pay
Nothing can be deleted, including what went in by mistake. A personal-data erasure request stops being a query and becomes a design problem.

05. A service refuses to start if it finds a provider key in its environment

Chose
The engine, the sandbox and the web server check their own environment at boot and fail if they find a key.
Over
Simply not reading the variable.
Because
The dangerous case is not code that reads the key. It is a deploy that passes the key to everything by accident. Failing closed turns a silent misconfiguration into a loud startup failure.
Price I pay
A legitimate shared environment breaks, and local development needs care to avoid killing your own service without understanding why.

06. One PostgreSQL role per service, with only the grants its code uses

Chose
ao_gateway, ao_server and ao_engine, each with its own grants, checked by tests. The sandbox has no role at all.
Over
One connection string for every service.
Because
If the sandbox is compromised, it must not be able to read the accounts table. Since it has no connection at all, that class of attack disappears rather than being mitigated.
Price I pay
Migrations have to maintain the grants. A new query fails in tests until the grant is added, which is exactly the point, and it slows the work down.

07. A mock provider and a throwaway database for end-to-end tests

Chose
A mock provider and a separate database, so the whole stack can be brought up and exercised at no cost and without touching the development database.
Over
Running end-to-end tests against the real provider.
Because
End-to-end against a real provider costs money on every run and is not deterministic, so nobody runs it as often as they should. A test nobody runs protects nothing.
Price I pay
The mock does not understand text. The test proves plumbing, permissions and the approval flow, and proves nothing about model behaviour.

5. What breaks

Including what is unresolved today. The README itself says the system is not ready for production.

The reservation is a worst-case estimate

It depends on a maximum-cost table per model. If a provider changes pricing, or a model with different token economics is added, the reservation is wrong in both directions: either it holds too much budget and stops tasks for no reason, or it holds too little and the guarantee stops being true. Nothing currently checks whether that table still matches reality.

A task stopped by budget waits forever

It waits for an administrator. If nobody is watching, it simply sits there. There is no deadline, no escalation and no default behaviour after a period of time.

Approvals have the same problem, and worse

An irreversible action waiting for a decision holds the whole run, and a held run keeps its budget reserved. The longer nobody decides, the more balance is locked up with nothing happening.

The hash chain proves tampering, but nobody checks it

Chaining makes any edit detectable. Detectable is not detected: nothing verifies the chain continuously. A break only surfaces when someone decides to look, which is usually too late.

A sandbox with no network closes the escape and closes the use case

Having no network removes the main escape route, and also blocks any legitimate task that needs the internet. That tension is unresolved: today the choice is full safety with reduced capability.

Everything on 127.0.0.1

It is the right decision for self-hosted use on one machine, and it leaves open how a team on different machines would use this. The deployment story for more than one person has not been designed.

6. What I would change at 100x

Scenario: 100 agents running at once, thousands of tasks a day, and several workspaces in the same installation.

What survives unchanged

The trust boundaries. The key still leaves only through the gateway, the per-service roles still hold, and the sandbox still has no network and no database, whatever the volume. Security designed as a boundary does not degrade with scale.

What breaks first

The single engine worker, which processes requests in sequence. With 100 agents the queue grows faster than it drains, and everything ends up waiting on one process.

In the order I would change them

  1. 1

    Several workers claiming tasks with SELECT FOR UPDATE SKIP LOCKED. The Postgres-as-a-queue design already allows it, so this is a change in the worker loop rather than in the data model.

  2. 2

    Fix the contention on budget reservation. Every call in the same workspace locks the same row, and with 100 agents that becomes the next bottleneck. Per-agent reservation rows with periodic rollup take the contention out of the hot path.

  3. 3

    Partition the audit log. Eighteen triggers on every write amplify writes, and at volume the log becomes the heaviest table in the database. Partition by month, move old partitions out, keep the chain hash.

  4. 4

    Give approvals a policy: a deadline, escalation and a default on expiry. Without that, every forgotten irreversible action is a held run sitting on a budget reservation, and at scale that locks the system up without a single error appearing.

This page describes the system as it stands today, including what is still unresolved. Phases 1 to 4 are complete and the project is not ready for production use.