replay means four different things in our codebase. Here they are up front:

All four rest on one thing: the ledger that hits the database first is the authority.

Not the logs. Not the event stream. Not the SSE feed scrolling in your console. The rows in the tables. That sounds unremarkable until you notice it is what lets three of those four survive a process restart.

1. Why the word needs splitting

In a demo, these three sentences look like one feature:

• "Here's every step of that run."
• "Lost your connection? Refresh — the missing steps come back."
• "Bad answer? Hit replay."

Engineering-wise they are nothing alike. The first is a read. The second is a read plus a subscription. The third is a write — it calls the model again, sends the HTTP request again, spends the money again.

The cost of collapsing them into one word is a user who assumes "replay" is safe and sends two emails.

So the order below goes from cheapest to most expensive.

2. The tables, and one number that shows up three times

Five tables, all in one file (server/app/kernel/runtime/db/models/runs.py, 396 lines):

runs                    one execution                        Run           :25
run_steps               one step inside it                   RunStep       :120
run_step_tool_calls     execution control for one tool call                :180
run_artifacts           files this execution produced        RunArtifact   :242
run_cost_entries        usage and cost for one metered call                :284

Three more cover long-running work (models/tasks.py, 98 lines): tasks, task_checkpoints, task_events. Section 7 uses them.

Now the detail worth stopping on: 8192 appears three times in this ledger, and it means something different each time.

Twice on the run and the step, where summaries are truncated:

input_summary=input_summary[:8192] if input_summary else None,

Once on a tool call result, where anything larger is offloaded to object storage and the ledger keeps a pointer, a byte count and a sha256:

if len(encoded_result) > 8192:
    ...
    artifact = self.trace_writer.create_artifact(
        run_id=record.run_id,
        step_id=record.run_step_id,
        artifact_type="json",
        storage_key=storage_key,
        mime="application/json",
        size_bytes=len(encoded_result),
        sha256=hashlib.sha256(encoded_result).hexdigest(),
        meta={"kind": "tool_result", "tool_call_id": record.tool_call_id},
    )

The asymmetry is deliberate. Summaries are for humans; losing the tail is fine. Tool results get reconciled and replayed; losing a byte is not fine.

Section 12 covers a consequence of that asymmetry we have not handled well yet.

3. Replay #1: reassembling the evidence

The cheap one. A GET:

GET /api/v1/observe/runs/{run_id}/replay

One sentence of behaviour: query the five record types by run id, add approvals and feedback, return the bundle. The implementation (server/app/modules/observe/application/service.py:212) returns seven keys:

return {
    "run": run,
    "steps": steps,
    "artifacts": artifacts,
    "costs": costs,
    "approvals": approvals,
    "feedback": feedback,
    "trace_spec": to_runtrace_spec(run, steps, artifacts, costs),
}

Six raw record sets, plus trace_spec — the same data flattened into something you can hand to a tracing backend (kernel/runtime/runs/exporter.py:88). That spec carries two rollups alongside the timeline: usage_summary (prompt tokens, completion tokens, embeddings, reranks, milliseconds, storage bytes, requests, vectors) and charge_summary (amounts grouped by currency).

Nothing here executes. No model call, no tool call, no cost. It is a database read, so you can call it at any point after the run ended, and the ten-thousandth call costs what the first one did.

Every query carries tenant_id and workspace_id in its where clause — reading another workspace's ledger is closed off at the SQL level, not at a middleware you can misconfigure.

4. Replay #2: catching up after the connection drops

The second-cheapest, for the "tab is open, wifi died" case:

GET /api/v1/runs/{run_id}/stream?last_event_id=st_xxxx

Handled at server/app/api/v1/workflow/streaming.py:401. The part that matters:

if last_event_id:
    step_query = select(RunStep).where(
        and_(
            RunStep.id == last_event_id,
            RunStep.run_id == run_id,
            ...
        )
    )
    last_step = db.exec(step_query).first()
    if last_step:
        last_step_time = last_step.created_at
        known_step_ids.add(last_step.id)

steps_query = select(RunStep).where(
    and_(
        RunStep.run_id == run_id,
        ...
        RunStep.created_at > last_step_time if last_step_time else True,
    )
).order_by(RunStep.created_at)

Look at where it reads from: select(RunStep). The database. Not an in-memory ring buffer, not a broker offset.

That choice buys a specific property: you can reconnect an hour after the run finished, hand over your last_event_id, and still get the steps you missed. An in-memory buffer cannot do that — a restart empties it. A broker can, but then you need a broker.

The SSE id: field is the step's primary key (streaming.py:432), so the Last-Event-ID that browsers resend automatically is already a row id in the ledger. No second cursor scheme to keep in sync.

One more detail worth borrowing: that query sets populate_existing=True, with a comment explaining why — the execution side writes from its own session, so this tailer has to bypass anything its own session cached earlier. That is the kind of line nobody can reconstruct three months later without the comment.

5. Replay #3: the same idempotency key, twice

This one happens below the surface, inside the tool gateway.

Every tool call gets a run_step_tool_calls row. The table carries three unique constraints (models/runs.py:182):

UniqueConstraint("tenant_id", "workspace_id", "run_step_id", ...)
UniqueConstraint("tenant_id", "workspace_id", "run_id", "tool_call_id", ...)
UniqueConstraint("tenant_id", "workspace_id", "idempotency_key", ...)

The third is the interesting one. When the same key arrives again and the row is already terminal:

if existing.status in {"succeeded", "failed"}:
    payload = existing.result_json or {}
    ...
    return ToolExecutionClaim(
        record=existing,
        run_step=step,
        replayed=True,
        cached_response=ToolResponse(
            result=payload.get("result"),
            success=existing.status == "succeeded",
            error=existing.error_message,
            metadata={..., "idempotent_replay": True},
        ),
    )

Last time's result comes back; nothing leaves the process. The metadata carries idempotent_replay: True so callers can tell this apart from a fresh execution.

If the earlier result was large enough to live in object storage, load_cached_response (tool_calls.py:636) fetches the artifact — after checking tenant, workspace, run and step all match, and raising Tool result artifact scope mismatch if any of them does not.

The point of this layer: replay #4 is only safe to offer because this one exists. When you re-run, the tool calls whose idempotency keys did not change are not actually executed a second time.

6. A status that admits we don't know

This is the design I would point at first if someone asked what is unusual about this ledger.

Claiming a tool call takes a lease (60 seconds by default, widened by the gateway to the tool's timeout). An expired lease means the executor may be dead. Retry or not?

The code answers by asking whether the request actually left (tool_calls.py:309):

lease_expired = (
    existing.lease_expires_at is not None
    and _aware_utc(existing.lease_expires_at) <= now
)
if lease_expired and existing.outbound_started_at is not None:
    existing.status = "in_doubt"
    ...
    raise ConflictError("Tool call outcome is in doubt")
if lease_expired and existing.outbound_started_at is None:
    existing.status = "claimed"
    existing.attempt_count += 1
    ...

Two branches, split on one field, outbound_started_at:

• Died before going out — safe. Re-claim, bump the attempt count.
• Died after going out — mark it in_doubt, do not retry, park the step at paused, raise a conflict.

The second branch is the honest one. On the other end is a real system: an order endpoint, an email, a transfer. The request left and no response came back. We don't know whether it happened, so we don't guess. The ledger records "in doubt" and a human decides.

Auto-retrying here is wrong in the specific way that only surfaces when someone gets two copies of the same email.

7. Replay #4: actually running it again

The expensive one. Three separate paths, three different mechanisms.

(a) Workflows: replay and retry

POST /api/v1/workflows/{workflow_id}/runs/{run_id}/retry
POST /api/v1/workflows/{workflow_id}/runs/{run_id}/replay

The two implementations differ by one check (modules/workflow/application/service.py:804 and :821): retry requires the source run to be failed or canceled; replay does not. Both load the original inputs, execute again, and put source_run_id and control_action in the response.

(b) Agent tasks: replaying a persisted snapshot

More interesting (server/app/wiring/task_drivers.py:82). Rather than "take the inputs and run", it loads the previous ResponseInteraction snapshot and deliberately strips the identifiers that belonged to the failed attempt before queueing a new one:

execution_json["assistant_message_id"] = generate_thread_message_id()
payload = dict(execution_json.get("payload") or {})
if payload:
    # Drop identifiers that belong to the attempt being replaced so the
    # replay creates its own response, run and task.
    payload.pop("task_id", None)
    payload.pop("run_id", None)

The old task is then moved to CANCELED with a forward pointer, retried_as_interaction_id, in its progress payload. The comment is blunt about why: leaving it queued would report work this task will never perform.

If there is no snapshot, it does not improvise — it fails explicitly with a dedicated error code, SNAPSHOT_MISSING_ERROR_CODE. No evidence, no replay. I like that one.

(c) Knowledge ingestion: lineage that actually lands in the ledger

The only one of the three that writes the lineage into runs (modules/knowledge/application/runtime_service.py:848):

run = self.trace_writer.create_run(
    ...
    source_run_id=previous_run.id,
    attempt_no=max(previous_run.attempt_no + 1, task.retry_count + 1),
    request_id=f"knowledge-ingest:{task.id}:{task.retry_count + 1}",
)

runs has both source_run_id and attempt_no, plus a dedicated index, ix_runs_scope_source_created. This path uses them.

The other two do not. That is item ① in section 12.

8. Why the ledger is trustworthy

Three reasons, all in the code.

Status changes are conditional UPDATEs, not read-modify-write. The where clause at writer.py:375 carries the old value:

result = self.db.execute(
    update(Run)
    .where(
        Run.id == run_id,
        Run.tenant_id == self.ctx.tenant_id,
        Run.workspace_id == self.ctx.workspace_id,
        Run.status == old_status,
    )
    .values(**values)
    ...
)
if result.rowcount != 1:
    ...
    raise RuntimeTransitionError(f"Concurrent run transition rejected: {old_status} -> {target_status}")

Two executors racing to change the same run: one wins, the other sees rowcount != 1 and is rejected. Not last-write-wins — someone jumped the queue, so error out.

Success is an irreversible terminal state. From the transition table in kernel/runtime/status.py:

ExecutionStatus.SUCCEEDED: frozenset(),
ExecutionStatus.FAILED: frozenset({ExecutionStatus.RETRYING}),
ExecutionStatus.CANCELED: frozenset({ExecutionStatus.RETRYING}),
ExecutionStatus.EXPIRED: frozenset({ExecutionStatus.RETRYING}),

SUCCEEDED reaches nothing. A success written into the ledger cannot be walked back, not even to failed. Failures can move to retrying; successes go nowhere.

Outbound notification goes through a transactional outbox, not a live broadcast. Creating a run and every status change write an outbox row (writer.py:282 and four other sites) inside the same database transaction as the business data.

The live event bus, by contrast, is best-effort — the last line of _emit_event is:

except Exception:
    return

Swallowed. That is the right call: a failed notification must never block the ledger write. It also means one thing for anyone verifying behaviour — reconcile against the ledger, not against what you saw on the event stream.

9. The ledger belongs to the ports, not to the loop

The previous piece argued that governance is a property of the port rather than of the agent loop. This one adds a parallel claim.

Count who writes to TraceWriter:

Five kernel ports, five policy gateways, one ledger.

Which means: you do not instrument the agent loop, and you do not instrument the workflow engine. If an operation left through a port, it left a row. The agent loop calling tool_port.invoke leaves one; a DAG workflow's tool node calling the same tool_port.invoke leaves one — in the same table, with the same schema.

The converse holds too, and it is the real boundary of this design: a call that bypasses the ports leaves nothing in the ledger. That is not a bug, it is what layering means. The ledger records governed operations, not everything the process happened to do.

10. The boolean the platform computes for you

Mechanism aside, the question a user actually has is simpler: is there enough evidence for this run?

GET /api/v1/runs/{run_id} returns thirteen governance evidence items (kernel/runtime/runs/service.py:530 onward):

actor_scope        subject_version     capability_binding   permission_scope
secret_boundary    egress_policy       audit_record         cost_attribution
trace_timeline     tool_call           knowledge_citation   child_workflow
replay_ready

The last one is the boolean. Its criteria are at service.py:516:

replay_missing: list[str] = []
if not steps:
    replay_missing.append("steps")
if response_timeline_applicable and not response_events:
    replay_missing.append("response_events")
if cost_attribution_applicable and not cost_entries:
    replay_missing.append("costs")
if knowledge_citation_applicable and not citations:
    replay_missing.append("citations")
if tool_governance_applicable and not tool_calls:
    replay_missing.append("tool_calls")
if tool_governance_applicable and not audits:
    replay_missing.append("audits")

Note the _applicable guards: it judges against what this run actually did. A pure chat run has no tool calls and is not marked deficient for lacking them. A run that did call a tool, but has no matching audit rows, comes back fail — and names the missing category in missing.

I find that more useful than a docs page promising "full replay". It is a field you can query, not an adjective. And it can fail — a check that always returns pass is not a check.

11. Fingerprints in the ledger, not payloads

A ledger you keep for a long time is at risk of becoming a disclosure surface.

The handling starts at tool_calls.py:59. Arguments are redacted before they are persisted; a key matching one of sixteen sensitive names becomes [REDACTED]:

api_key       apikey          access_token   authorization
client_secret cookie          credential     password
private_key   refresh_token   secret         secret_access_key
session_token token           x_api_key

Keys are normalized before comparison — camel case split, non-alphanumerics folded to underscores — so apiKey, API-KEY and api_key are treated alike.

One exception is worth knowing: if the value is a dict carrying a secret_id, it is not redacted. It is already a reference rather than a plaintext, and blanking it would destroy the one thing you want later: which secret this call used.

Then size. Arguments over 8192 bytes are not stored; three things are kept instead:

return {
    "truncated": True,
    "size_bytes": summary["size_bytes"],
    "request_hash": summary["payload_hash"],
    "argument_names": sorted(str(key) for key in value),
}

request_hash is computed over the pre-redaction original — canonical_request_hash does a sorted, compact JSON dump and sha256s it.

The effect: the ledger holds no payload, but idempotency still works. The same key arriving twice is compared on request_hash; a mismatch raises Tool call identity was reused with different input.

Reconcilable, but not leaky. Second-nicest thing in this ledger, after in_doubt.

12. Seven things that don't line up yet

This section is entirely about our own problems, ordered by impact.

① Workflow replay/retry never writes lineage into the ledger.

runs has source_run_id and attempt_no, plus an index built for them. Across the whole repo there are 19 create_run( call sites and exactly one passes source_run_id — the knowledge ingestion path from section 7.

Workflow replay goes through execute_workflow into engine.execute, and the engine creates the run like this (modules/workflow/runtime/engine.py:145):

run = self.trace_writer.create_run(
    mode=plan.mode,
    subject_kind=plan.subject_kind,
    subject_id=plan.subject_id,
    subject_version_id=plan.subject_version_id,
    input_summary=input_summary,
    run_id=plan.run_id,
)

No source_run_id. No attempt_no.

Impact: source_run_id exists only in the HTTP response body. If the caller does not store it, the "B is a replay of A" relationship is gone — unqueryable in the ledger, and ix_runs_scope_source_created indexes nothing useful.

Workaround today: have the caller keep the source_run_id it got back. Intended fix: thread source_run_id and attempt_no through those two paths into create_run. I intend to open an issue for this; I had not filed it when this was written, so there is no link here.

② Re-execution reads a truncated copy of the inputs.

Section 2 noted that input_summary is cut at 8192 bytes. Workflow replay loads inputs like this (modules/workflow/application/service.py:151):

def _load_run_inputs(self, run: Run) -> dict[str, Any] | None:
    if not run.input_summary:
        return None
    import json
    try:
        parsed = json.loads(run.input_summary)
        ...

It json.loads the summary.

So a run whose inputs exceeded 8KB will fail to parse on replay (truncated JSON generally is not valid) and return Replay requires inputs or a parseable run input_summary.

Workaround today: pass inputs explicitly instead of letting it read from the ledger — both endpoints accept an override. Intended fix: send large inputs to an artifact and keep a pointer, exactly like tool results in section 2. Same status: issue intended, not yet filed.

③ generate_ulid() does not generate a ULID.

The source says so itself (kernel/commons/ids.py:9):

def generate_ulid() -> str:
    """Generate a ULID-like sortable ID.

    For now, we use UUID4 with prefix. In production, consider using
    python-ulid or similar library for true ULID generation.
    """
    return f"id_{uuid.uuid4().hex}"

UUID4 is random. Not sortable at all — neither the name nor the "sortable" in the docstring holds.

Bounded but real impact: everything that needs chronological order has to use created_at rather than the id. The catch-up in section 4 does exactly that. Arguably forced into the correct implementation.

④ Catch-up uses a strict greater-than.

Following from ③: created_at comes from Python's datetime.now(UTC), and the filter is RunStep.created_at > last_step_time.

Theoretical consequence: if two steps land on an identical timestamp and the client's last received event was one of them, the other is skipped by the strict comparison.

I did not reproduce this. datetime.now() resolves to microseconds on modern Linux, and two steps in one run colliding on the same microsecond takes unusual conditions. It is listed as a design fragility, not an observed bug — please don't repeat it as one. The fix is easy once ③ is done: order by (created_at, id).

⑤ Ids in the ledger come in three shapes.

Because generate_ulid() already returns an id_-prefixed string, anything that adds its own prefix ends up double-prefixed:

All three work. The third just gives no hint which table the row belongs to. Cosmetic, no functional impact — but you notice it the moment you start reading rows.

⑥ The Run.status docstring lists 6 statuses; there are 11.

On the model (models/runs.py:79):

"""Status: queued, running, paused, succeeded, failed, canceled."""

ExecutionStatus has eleven: those six plus preparing, waiting_input, waiting_approval, retrying, expired. Steps add skipped on top.

Impact: anyone writing a client from that comment misses five states. Documentation drift; a one-line fix.

⑦ The soit runs replay line in the console is display copy — that CLI does not exist.

From the run detail adapter (web/app/console/adapters/run-detail.ts:227):

ledger_code: {
  command: `soit runs replay ${run.id} --dry-run`,
  output: `replaying ${detail.steps.length} steps · verdict on record: ${run.status}`,
},

It renders as a code sample explaining what that panel shows. But there is no soit CLI in the open-source repo — server/pyproject.toml has no [project.scripts], and server/scripts/ has no matching entry point.

The thing that does work is the HTTP endpoint from section 3. There is a replay script in the repo, but it is for the outbox (server/scripts/replay_outbox_event.py, 41 lines — it returns one terminally failed domain event to the pending queue), which is a different thing entirely.

I went back and forth on including this. Including it says we haven't kept our own console copy honest. Leaving it out means a reader types the command from a screenshot and gets nothing. Included, in the end — the gap between demo copy and real capability is exactly the kind of thing a reader is entitled to know.

Coming clean

• No fresh live run behind this piece. Every conclusion comes from reading soit/ at commit fb46f20, plus the tests already in the repo. I did not stand up an environment, execute a run and then call the replay endpoint. Every claim carries a file and a line number; go check them.
• Item ④ in section 12 is an inference, not an observation. I did not construct the colliding-timestamp case. It is listed because a design should not depend on timestamp uniqueness, not because we have seen it break.
• Replay does not promise identical output. Replay #4 genuinely runs again — models have temperature, tools talk to real systems, external data moves. What is promised is the same inputs, the same governance policy and complete evidence. There is no record-and-stub harness for tools in the repo.
• This is all the community edition. Every path above is in github.com/soit-ai/soit and readable right now.
• Disclosure: I maintain SOIT.

One-line version

"Replayable" here is not an adjective. It is a field the platform computes, that you can query, and that can come back fail — backed by five database tables, four replay paths with very different costs, and one status willing to admit we don't know whether the other side did the thing.

Try it, and come argue

The repo is github.com/soit-ai/soit. To check the claims above:

1. Start it, send any message, take the run_id.
2. GET /api/v1/runs/{run_id} and look at replay_ready among the thirteen evidence items — if it is fail, missing names what is absent.
3. GET /api/v1/observe/runs/{run_id}/replay and see what the seven keys hold.

If any of the seven items in section 12 is wrong, open an issue and say so. I would rather learn where this doesn't line up than be told the design is nice.

Someone asked again — roughly the tenth time since we open-sourced — whether SOIT is "just another LangChain". I have answered that with architecture diagrams before and it never lands, because a diagram is something I drew. So this time I answered it with wc -l.

Our agent loop — plan, act, verify — is 239 lines. The policy gateway sitting on the single port that loop reaches out through is 475 lines. One file, guarding one seam, is roughly twice the size of the thing everyone assumes is the product. That ratio is the entire argument of this post, and it is the one claim here I did not have to construct.

What follows is a read-the-code account of where the framework layer ends and the runtime layer begins, using our own repository as the specimen, with a file and a line number attached to every claim.

The short version

The last two rows are what this post argues, and they are not a diagram I drew. They are wc -l.

Why this needs a whole post

"Agent platform" currently swallows at least three separate things: the library you write an agent with, the engine that runs it, and the control plane that governs it. Once those three share a word, every discussion becomes two people answering different questions — one is saying "I built an agent in three lines", the other is saying "I need to know who approved that call at 3pm yesterday". Both are right. Neither is talking to the other.

I am not going to characterize anyone else's internals. That would require me to have read their code closely enough to be accountable for the claim, and every claim in this post has to come with a line number. So the post does two things:

1. describes what the framework layer generally owns — consensus, no assertions about anyone;
2. uses our own repo as the specimen to locate what the runtime layer owns.

The specimen is github.com/soit-ai/soit, Apache 2.0. Every line number below refers to commit 3a57ae1.

1. Counting our own agent loop: 239 lines

An agent loop is three things: decide the next step, do it, check whether it is done. In our repo those are three files:

server/app/modules/agent/runtime/planner.py    98 lines
server/app/modules/agent/runtime/executor.py   42 lines
server/app/modules/agent/runtime/verifier.py   99 lines

The executor is 42 lines and nearly all of it fits here:

class AgentExecutor:
    """Execute tool actions for agent."""

    def __init__(self, tool_port: ToolPort):
        self.tool_port = tool_port

    async def execute_tool(
        self, tool_ref, parameters, ctx, run_id, tool_call_id,
        idempotency_key, run_step_id=None, resume_approval=False, lease_owner=None,
    ) -> ToolResponse:
        """Execute tool call."""
        return await self.tool_port.invoke(
            tool_ref=tool_ref, parameters=parameters, run_id=run_id,
            tool_call_id=tool_call_id, idempotency_key=idempotency_key,
            run_step_id=run_step_id, resume_approval=resume_approval,
            lease_owner=lease_owner, ctx=ctx, strict_registry=True,
        )

This class has no logic. It hands the call to a port. That is not laziness; it is the thesis of this post: the rules of execution are not written in the loop, they are written on the port.

The planner is equally plain. It hands messages to the model using native function calling and gets back either tool calls or text — there is no third case:

response = await self.llm_port.chat(
    messages=planning_messages, model=model, temperature=temperature,
    tools=tool_definitions if tool_definitions else None,
    tool_choice="auto" if tool_definitions else None,
    run_id=run_id, reasoning_effort=reasoning_effort,
)
if response.tool_calls:
    return PlanResult(action="tool", tool_calls=response.tool_calls, ...)
return PlanResult(action="respond", response=response.text or "", ...)

No prompt template DSL. No chain or graph authoring language. No regex pulling Action: out of model output. The verifier is the same shape: one structured-output tool definition (verify_response, fields ok and reason) asking the model whether the answer is adequate.

This layer is the framework's home turf, and we deliberately built almost nothing here. Thin is neither a virtue nor a flaw. It just means we are not competing on expressiveness.

2. So what are the 1,617 lines wrapped around it doing?

server/app/modules/agent/application/service.py is 1,617 lines. Its import block answers the question on its own:

from app.kernel.identity.guard import workspace_guard
from app.kernel.ports.approvals import ApprovalLedgerPort, ApprovalRecord
from app.kernel.ports.common.rate_limiter import RateLimiter
from app.kernel.runtime.runs.tool_calls import RuntimeToolExecutionService, ToolExecutionCommand
from app.kernel.runtime.runs.writer import TraceWriter
from app.kernel.runtime.tools.approval import tool_approval_rule
from app.kernel.runtime.tools.resolver import ToolResolver

Workspace guard, approval ledger, rate limiter, tool-execution ledger (with leases and idempotency), trace writer, approval rules, tool resolver. Plus a dedicated control signal for human approval:

class _AgentApprovalInterrupt(Exception):
    """Internal control signal for a durable human approval checkpoint."""

The loop itself is one while (service.py:653):

while pending_tool_calls or iterations < data.max_iterations:

One line of loop, sixteen hundred lines around it. Almost none of those lines are about how the agent thinks. They are about whether this call is allowed, whether it is written down, who it is billed to, and how to resume when a human interrupts it.

If nine tenths of a codebase answers the second set of questions, calling it "another agent framework" describes the least important tenth of it.

3. Where the line actually is: ten gates on one tool call

server/app/kernel/ports/tools/interface.py is 54 lines: an abstract ToolPort with a single abstract invoke(). That is the seam.

The thing that does the work is ToolPolicyGateway in server/app/kernel/ports/tools/policy.py, 475 lines, implementing that same ToolPort. Which means calling a tool raw and calling a tool through governance look identical to the caller — the only difference is which implementation got injected.

ToolPolicyGateway.invoke() starts at policy.py:231. One tool call passes, in order:

Watch how gate 1 and gate 10 cooperate: real values only ever reach the call; the redacted copy is the only thing that reaches the record. The code carries resolved_parameters and redacted_parameters side by side precisely so that audit and metrics can never accidentally take the wrong one. That is not a discipline you can maintain by being careful in application code. It only works if it sits on the path everything must take.

Gate 9's comment is the tell:

# Durable Agent calls are at-most-once at this boundary.
# Not every downstream adapter can honor an idempotency key.

That is a runtime-layer concern in one sentence. It does not care whether your agent logic is elegant. It cares whether a retry files the same ticket twice.

4. The fact that proves governance does not live in the loop

At this point you could reasonably say: you just pushed the governance code downstream of your agent loop, that proves nothing.

So look at a second execution model. Besides the agent loop, the repo has a workflow engine — modules/workflow/, 6,269 lines, including a 969-line engine.py and an 855-line executor.py. It is a DAG. It has nothing structurally in common with an agent loop.

How does it call a tool?

# server/app/modules/workflow/runtime/executors/tool.py:428
response = await context.tool_port.invoke(...)

# server/app/modules/workflow/runtime/executors/llm.py:105
response: ChatResponse = await context.llm_port.chat(...)

The same tool_port.invoke. The same llm_port.chat.

Two unrelated execution models, one set of gates. That is the operational definition of a layer: governance is a property of the port, not of any particular loop. Swap the execution model above and not one of the ten gates below goes away.

Which is also the technical reason the two layers do not conflict: anything that calls through these ports gets governed — our loop, a DAG engine, or something else entirely. The layer underneath cannot tell the difference and does not need to.

5. The dependency list is the most honest positioning statement a project has

What a project says it is, you read in the README. What it actually is, you read in its dependencies.

In server/pyproject.toml, exactly three core dependencies relate to agents at all:

"mcp>=1.28.1,<2",          # tool protocol
"ag-ui-protocol==0.1.19",  # front-end interaction event protocol
"litellm==1.91.1",         # model invocation

All three are protocols or call layers. There is no agent framework in the core dependencies. That is not a manifesto, it is pyproject.toml lines 68 to 71.

And LangChain? It is there. Here:

[project.optional-dependencies]
local-embedding = [
    "sentence-transformers>=4.1.0",
    "langchain-huggingface>=0.0.6",
    ...
]

pyproject.toml:75–83 — an optional extra named local-embedding, for running embedding models locally. Nothing to do with agent orchestration.

While I am here, a correction about us. Our README's tech-stack table lists the LLM row as OpenAI · Anthropic · DeepSeek · Qwen · LangChain (adapter layer) (README.md:240). That does not match the dependencies. LangChain is not an LLM adapter layer here; it is an optional local embedding dependency. That is our documentation misleading readers, and I intend to open an issue to fix it — I had not filed it when this was written, so there is no link to give you.

6. The seams are other people's protocols, not shapes we invented

A layer boundary is only real if the seam is public. Three seams:

Requests in. POST /api/v1/responses accepts AG-UI's RunAgentInput directly:

# server/app/api/v1/responses/router.py:222
async def create_response(payload: RunAgentInput | ResponseCreateRequest, ...):

A front end does not have to learn a SOIT-specific message shape.

Tools in. Tool references are namespaced strings; adapters/tools/router.py shows three prefixes — tool:http:*, tool:function:*, and mcp_tool:*. Any MCP server resolves into the tool registry without a code change.

Events out. The run is persisted and streamed to the front end as AG-UI interaction events (adapters/agui/agent.py and responses.py, 909 lines together).

Three protocols, no dialect of our own. That is the precondition for two layers being able to snap together at all.

7. We did not write a framework at the model layer either

adapters/llm/ is 2,619 lines, of which router.py is 534. Those 534 lines do routing, credential resolution and egress guarding — not prompt composition:

# server/app/adapters/llm/router.py:192 (inside _authorize_provider_target)
await self.egress_guard.authorize(ctx, f"model-provider:{provider_slug}", url)

Both provider-resolution paths (router.py:368 and router.py:422) go through it first. In other words, calling a model is itself subject to egress policy. If the target host is not in policy, the call does not leave the box.

One more that is easy to miss: in production, a provider with no configured credential is rejected outright (router.py:316–324, MODEL_PROVIDER_CREDENTIAL_REQUIRED). "Production mode refuses to let you cut corners" is a runtime-layer job description. It does nothing for your developer experience. It exists to stop development-time convenience from reaching production.

8. The boundary is welded shut by CI, not asserted in a doc

Layering usually dies by being true in the documentation and false in the code. So we handed this one to a tool. The first contract in server/importlinter.ini:

[importlinter:contract:kernel_isolation]
name = Kernel is isolated
type = forbidden
source_modules =
    app.kernel
forbidden_modules =
    app.api
    app.modules
    app.adapters
    app.infra
    app.wiring

The kernel may not import anything above it. The moment the governance kernel depends backwards on a product module, "swap the execution model and every gate survives" stops being true. That is not something to leave to good intentions; let CI hit the wall instead.

server/app/kernel/README.md states the rule in prose, and one line of it is worth quoting:

Kernel extension points that need product or infrastructure data must use provider interfaces registered from wiring/.

When the kernel needs outside data it does not reach for it; it takes a provider interface registered in wiring/. That is the standing cost of keeping a layer boundary alive.

9. The honest part: those 6,269 workflow lines do overlap

So far I have made us sound very tidy: we only do runtime, not framework.

That is not quite true.

modules/workflow/ is 6,269 lines, with a compiler (compiler.py, 259), variable resolution (variable_resolver.py, 212), node executors (the tool node alone is 610), resume and reaper paths. It is an orchestration engine, and it overlaps in function with orchestration frameworks people already use.

I am not going to argue that ours is somehow a different species. It overlaps. The only distinction is the one from section 4: it calls tools through the same tool_port.invoke.

So the accurate statement is not "we don't build framework things". It is: we built the minimum of it we needed, and we made it obey the same rules as everybody else.

10. What "not competitors" concretely means — including what you cannot do today

Three things you can do, and one you cannot.

You can:

1. Bring framework-side tools in over MCP and have them governed. Any MCP server resolves into the tool registry, and from then on every call it makes goes through the ten gates.
2. Bring framework-side services in as HTTP plugins. adapters/plugins/http_runtime.py and skill_runtime.py are the two plugin runtime implementations (129 and 85 lines).
3. Keep your front end. Interaction is an AG-UI event stream, and the request shape coming in is AG-UI's RunAgentInput.

You cannot (and this matters more than the three above):

There is no entry point today for handing us a framework-written agent to host wholesale. Your loop still runs in your process. What SOIT governs is the hand it reaches out with — tool calls, model calls, egress — not the reasoning inside it.

That is the real boundary right now. Do not size it up as a universal container. If what you want is "host my existing agent code as-is and get the whole governance stack for free", this repo does not do that today. What it does is make every hand that code reaches out with sign its name.

Confession

• This is a read-the-code and read-the-config piece with no new end-to-end run. Every claim can be opened and checked at commit 3a57ae1; whether it behaves this way at runtime is outside what this post verified.
• All line counts are wc -l, including blanks, comments and docstrings. Fine for orders of magnitude, wrong for estimating effort.
• The README inaccuracy in section 5 is real. Our own documentation misled readers about this. I intend to file an issue; it was not filed when this was written.
• I made no claims about any specific framework's internals. "What the framework layer owns" here is the industry-consensus description. Everything with a line number is our own repo.
• SandboxToolPort is not a security sandbox. The 61 lines in kernel/ports/tools/sandbox.py are a dry run for pre-release rehearsal: the run exercises the full decision path while the side effect is stopped at the boundary, so rehearsing a release does not actually file a pile of tickets. It stops side effects, not hostile code.
• The section 4 argument has a precondition. "Swap the execution model and every gate survives" holds only for execution models that call through the ports. Code that opens its own socket is not governed by any of this — the import contract in section 8 keeps the kernel clean; it does not stop application code from going around.

One sentence

A framework decides how the agent thinks. A runtime decides whether the hand it reaches out with counts.

These do not compete, because they do not even operate on the same timescale — one acts on the few days you spend writing code, the other on every execution afterwards.

If they compete for anything, it is attention. Somewhere on the path from demo to production, a team's attention has to move from the first to the second, and it usually moves too late — as in, after the first incident.

Try it, or take it apart

Code at github.com/soit-ai/soit, Apache 2.0. Every line number in this post refers to commit 3a57ae1.

If you want the tour of the layer underneath — what the other eleven containers in this stack actually do — that is the previous post.

Three files are worth opening, because they carry the entire argument:

• server/app/modules/agent/runtime/executor.py — 42 lines, see how empty it is
• server/app/kernel/ports/tools/policy.py — 475 lines, the ten gates
• server/importlinter.ini — how the boundary is welded shut

If you think the section 4 argument has a hole in it, or you have seen a better way to draw this line in another project, say so in an issue. The failure mode for a post like this is talking to myself.

Disclosure: I maintain SOIT.

The follow-up question was not "how did you cut it." It was the inverse:

So what are the rest of them actually for?

That deserves a straight answer rather than a defence. When a quickstart starts a dozen containers, the default reading is either "the architecture never converged" or "someone is cosplaying enterprise" — and plenty of projects earn both. So this post does exactly one thing: it walks a single agent run from arrival to completion, and every time the run touches a service, says what that service did at that moment and which guarantee disappears without it. Here is the least intuitive part up front: of the twelve containers, exactly one runs a model. Everything else buys the same thing — turning "run an agent" into "run an agent such that afterwards you can audit it, reconcile it, and replay it, and a crashed process does not leave half a state behind."

The short answer

1. First, a correction: it is not 12, it is 14

The quickstart command names twelve services:

docker compose --env-file .env -f docker/docker-compose.yml up -d \
  postgres redis minio etcd milvus vault migrate bootstrap api web \
  knowledge-ingest-worker outbox-dispatcher

docker/docker-compose.yml defines fourteen. The two extras behave very differently:

• minio-init is not in the command, but api declares depends_on: minio-init: service_completed_successfully, so Compose starts it anyway, it creates the bucket and runs mc anonymous set none, and exits. Thirteen containers actually start.
• scheduler is not in the command and nothing depends on it — it never starts in the quickstart topology at all. That one gets its own section.

The discrepancy itself is trivial. What matters is that "how many services are defined" and "how many you actually run" are two different numbers, and arguments about whether a stack is heavy tend to conflate them.

2. Before the run: the two containers that exit

migrate and bootstrap are one-shot jobs — restart: "no", and a healthy result is Exited (0).

migrate runs sh scripts/migrate.sh once postgres is healthy. bootstrap runs scripts/bootstrap_admin.py once migrate has exited successfully, creating the first admin and tenant (admin@example.com / changeme123 / tenant default by default).

Note the dependency condition: service_completed_successfully, not service_healthy. "Finished, and succeeded" is a different claim from "came up," and getting it wrong gives you a stack where every container is present and the schema is half-applied. api waits on both of these completing before it boots.

If docker compose ps shows those two as Exited, that is the correct state, not a failure.

3. Authz: Postgres is the authority, Redis is a cache

The first thing a request hits is authorization. Redis appears here, but strictly as a cache — the authority is always Postgres.

From server/app/kernel/identity/permissions.py:

class PermissionCache:
    """Permission cache using Redis."""

    def __init__(self, redis_client: redis_async.Redis | None = None):
        self._redis: redis_async.Redis | None = redis_client
        self._redis_pool: redis_async.ConnectionPool | None = None
        self._cache_ttl = 300  # 5 minutes

Three things worth knowing:

1. The TTL is hard-coded at 300 seconds, not configurable. A permission change can therefore take up to five minutes to propagate everywhere unless something calls invalidate explicitly (it exists — pattern-matched scan_iter + delete).
2. Losing Redis degrades rather than fails. _get_redis() returns None when settings.redis_url is empty or contains "None"; the caller treats that as a cache miss and falls through to the database. No Redis means slower, not broken.
3. The same Redis backs the rate limiter (server/app/kernel/ports/common/rate_limiter.py), implemented as a Lua script: ZREMRANGEBYSCORE to drop the expired window, ZCARD to count, then ZADD + EXPIRE if under the limit. Sliding-window counting in a single eval, so there is no read-modify-write race.

So "can I drop Redis?" resolves to: in a demo yes, in production no — and the reason is not the cache, it is the event bus in section 8.

4. The run gets written down: five ledger tables

Authorization passes, the run starts. This is the bulk of what Postgres carries, and it is the heaviest single piece of design in the stack.

One execution writes to five tables:

A few columns explain why this is not just two lines in a log file:

• parent_run_id / source_run_id / attempt_no (server/app/kernel/runtime/db/models/runs.py). The first is parent-child; the other two are a retry and replay lineage — which run this one was derived from, and which attempt it is. That is what makes "replayable" a mechanism rather than a slogan: a replay is a new run pointing back at its source, not a re-read of a log.
• sandbox. Marks a run as a rehearsal rather than real work. The field's own comment is blunt about why: pre-release regression executes real agents, and without the flag their cost and evidence inflate real activity.
• input_summary / output_summary capped at 8KB, with metrics_json as a JSON column. The ledger stores summaries; the full payload lives in object storage behind run_artifacts. That split is deliberate — the relational store holds queryable structure, object storage holds bulk.

5. Why tool calls get their own table

run_step_tool_calls is the most heavily constrained of the five. It carries three unique constraints:

UniqueConstraint("tenant_id", "workspace_id", "run_step_id", ...)
UniqueConstraint("tenant_id", "workspace_id", "run_id", "tool_call_id", ...)
UniqueConstraint("tenant_id", "workspace_id", "idempotency_key", ...)

plus an index on ("status", "lease_expires_at"). Together they say one thing: tool calls have side effects, so they have to be at-most-once. One step maps to one tool call; a tool_call_id cannot land twice within a run; the idempotency key is globally unique — that key is the tool:{run_id}:{tool_call_id} from the earlier governed-MCP post.

The lease_owner / lease_expires_at pair is crash recovery: a worker that dies stops renewing, and the row becomes claimable again once the lease expires. This semantic is factored into a shared module (server/app/kernel/runtime/common/lease.py) whose docstring is explicit that every runtime domain executing work outside a request must use the same claim / renew / orphan-recovery primitives. Two constants and one implementation detail are worth remembering: MIN_LEASE_SECONDS = 30 (a smaller configured value is clamped up), LEASE_RENEWALS_PER_LEASE = 3 (the heartbeat interval is a third of the lease), and claims use SKIP LOCKED so concurrent workers do not contend — the comment openly notes SQLite ignores the clause, which is fine for single-worker tests.

This section is the whole article in miniature: these containers exist not because AI is complicated, but because "side-effecting operations must happen exactly once" is expensive in a distributed system, and always has been.

6. Retrieval: what Milvus does, and why etcd tags along

If the run includes a retrieval step, api queries Milvus. The adapter is server/app/adapters/vector/milvus.py, and the index parameters are fixed:

index_params={"index_type": "IVF_FLAT", "metric_type": metric_type, "params": {"nlist": 1024}}

etcd deserves an explicit correction, because it is the container most often misread as padding:

milvus:
  environment:
    ETCD_ENDPOINTS: etcd:2379
    MINIO_ADDRESS: minio:9000
  depends_on:
    etcd: { condition: service_healthy }
    minio: { condition: service_healthy }

etcd is not the platform's dependency; it is Milvus's. Milvus standalone keeps its metadata in etcd and its data files in MinIO. No application code in the repo talks to etcd at all. The honest way to read the topology is therefore: "vector retrieval" is one capability that costs two and a half containers (etcd + Milvus, sharing MinIO). Whether a demo should pay that is a clear trade-off, not a mystery.

One fact carried over from the previous post, because it matters here: the vector store does not gate readiness. In server/app/api/v1/health/router.py, the database and object storage raise 503 when probing fails; the vector store is probed and reported only:

try:
    await vector.check_ready()
    vector_status = "connected"
except Exception:
    vector_status = "unavailable"

The docstring gives the reasoning: non-vector endpoints keep serving during a vector outage, so pulling the instance out of rotation would be an overreaction.

7. Where the big objects go: MinIO

run_artifacts stores storage_key, sha256, size_bytes, mime — not the content. The content is in MinIO.

The one-shot minio-init container does two things: mc mb -p local/soit-artifacts to create the bucket, then mc anonymous set none to close anonymous access. The second is a small correct default: the artifact bucket is not anonymously readable out of the box.

Object storage is a hard readiness gate (probe fails → 503). This is exactly where the previous post's live run broke: on paper you can swap in the local-filesystem adapter, and in practice it does not work inside the official image because the root path is strip("/")-ed into a relative path (filed as issue #43). So the practical verdict stands: MinIO cannot be dropped.

8. The part that starts after the response is sent

By now the run is finished and the response has gone back to the caller. One container is only now getting to work.

api writes domain events into the event_outbox table inside the same transaction as the business data (server/app/kernel/runtime/db/models/events.py). That is the transactional outbox: if the business change committed, the event exists; if it rolled back, the event does not. There is no window where the database changed but the message never went out.

outbox-dispatcher then polls that table as its own process. The row's columns are effectively its state machine: status, available_at, locked_at, lock_owner, lock_expires_at, attempt_count, last_error, processed_at.

The module docstring of server/app/kernel/events/dispatcher.py states the whole flow in one line:

claim rows, run registered handlers with checkpoint idempotency

"Checkpoint idempotency" is a second table, event_consumer_checkpoint, unique on (consumer_name, event_id). Before dispatching, the service asks checkpoints.is_processed(consumer_name, event_id); on success it calls try_record_success. So idempotency is per consumer per event, not per event — if the second of three handlers fails and the row is retried, the first is not re-executed.

That container also exposes its own Prometheus endpoint (expose: 9201, started via start_http_server), and its healthcheck is a scrape of /metrics.

9. Four of these containers are the same code as api

This is the part most easily mistaken for microservice sprawl, and it is the opposite. migrate, bootstrap, api, outbox-dispatcher and scheduler all share one build context (build: context: ../server). The released-image path makes it starker: docker/docker-compose.images.yml points migrate, bootstrap, api and outbox-dispatcher at the same image, ghcr.io/soit-ai/soit/server. Only knowledge-worker and web are separate. Three images cover twelve containers.

The difference is the entrypoint, plus which background loops are switched on. The lifespan in server/app/main.py has six flags, each folding one loop into the API process:

Which means "how many containers" is largely a deployment decision, not an architectural one. The same code can run as one process or five. Compose splits them, and server/scripts/schedule_worker.py states the reason more plainly than I could:

Separate from the API for the same reason the outbox dispatcher is: a scheduler that shares a process with request handling competes with it, and an API restart should not be a gap in when jobs fire.

10. Production mode refuses to let you cut corners

Those flags look like a matter of taste. Half of them are not, once ENVIRONMENT=production. validate_runtime_requirements() in server/app/settings/settings.py fails closed on each of:

• the database URL must carry host, database name, username and password;
• the event bus must be redis (the code default is actually memory; compose supplies redis);
• outbox_dispatcher_enabled being true is an error — production forbids folding the dispatcher into the API process, it has to be its own;
• inline chat-interaction execution is forbidden, and the durable interaction worker is required;
• plugin signature verification is required, and at least one public key must be configured — the comment explains why that is checked separately: requiring signatures with no trusted key rejects every package, which reads as a gate but is really a total block.

This is the part I'd most want a skeptical reader to notice. Which services are optional is not an opinion in this repo; it is code that refuses to boot. You may drop Redis and fold the dispatcher into the API for a demo. You cannot do that and also claim to be running production.

One gap I found while writing this

One thing I turned up is not a trade-off, it is a hole:

• docker-compose.yml defines a scheduler service that sets SCHEDULE_WORKER_ENABLED: "true" and runs scripts/schedule_worker.py;
• the quickstart command does not include it, and nothing depends_on it;
• the api container does not set SCHEDULE_WORKER_ENABLED, and the code default is False;
• .env.example does not mention the variable;
• docs/ never mentions scheduler at all — across the whole repo only the two compose files do.

Net effect: in a stack started per the quickstart, schedules never fire on their own. POST /schedules creates one, the preview endpoint tells you when it would next run, and POST /schedules/{id}/run triggers it by hand — but nothing is polling to claim it when its time comes.

docker-compose.production.yml does include a scheduler, so this is a quickstart coverage gap rather than a missing feature. There is a second-order problem too: the released-image overlay covers six services and scheduler is not one of them, so adding a scheduler to the images-based path silently falls back to a local build.

I plan to file an issue for both halves of this: add scheduler to the quickstart command, and cover it in the released-image overlay. It was not filed yet when I wrote this, so there is no link here — if you want to confirm it yourself, walking the four bullets above in order is enough.

What this post is not

• There is no new end-to-end run behind it. The minimal-topology post was executed end to end; this one is a static read of the code and compose files. So the scheduler finding above rests on a code-and-config chain of evidence (service never started + flag defaults to False + no documentation) — I did not stand up the quickstart, create a schedule, and watch it fail to fire. Falsifying it is easy if you want to: start the quickstart stack, create a schedule one minute out, and see whether it runs.
• No resource numbers. This is about responsibilities, not footprint. The image-size figures are in the previous post.
• Nothing about wiring it into your existing observability. OTEL_ENABLED (default false) and an OTLP endpoint are in compose, and the production file ships an otel-collector, but that is its own article.
• The Redis conclusion is conditional. "Fine to drop in a demo" holds because a demo runs a single api replica. Add replicas and the in-process bus stops crossing processes. That is what the production check is protecting.

So where is the weight?

Regroup the twelve by what they guarantee:

• 2 are the thing being demoed: api, web.
• 3 are one-shot jobs: migrate, bootstrap, minio-init — they exit.
• 2 are where the ledger and the artifacts physically live: postgres, minio — also the only two hard readiness gates.
• 2½ are one capability, vector retrieval: milvus + etcd (etcd being Milvus's dependency, not ours).
• 1 is secret isolation: vault.
• 1 is cross-replica broadcast and caching: redis.
• 2 are background processes split out of the same codebase: outbox-dispatcher, knowledge-ingest-worker.

Exactly one of them runs a model. The rest of the weight buys one thing: the execution leaves evidence behind, and a crash mid-run does not leave half a state.

Whether that is worth it depends entirely on what you are doing. If you just want to see whether an agent runs at all, this stack is too heavy for you — the previous post shows how to get it to four containers. If you need to put an agent inside a process someone will later have to reconcile, these containers are the things you would end up writing yourself.

Try it

• Repo: github.com/soit-ai/soit
• Full topology: docker/docker-compose.yml
• The four-container version: Reading the code told me which services I could drop. Running it told me the truth.
• If you think any one of these trade-offs is wrong, open an issue and say so.

Disclosure: I maintain SOIT.

That is the real subject of this post. The nominal subject is our twelve-service Compose stack, which starts like this:

docker compose --env-file .env -f docker/docker-compose.yml up -d \
  postgres redis minio etcd milvus vault migrate bootstrap api web \
  knowledge-ingest-worker outbox-dispatcher

Issue #25 asked the obvious question about it: I just want to look at it — do I really need all of them?

No — four containers are enough to log in and click around. Below is which services go, which leave as a group, which one you fold into the API process instead of deleting, and what stops working with each cut. I left both wrong conclusions in place rather than quietly correcting them, because they are the ones that would have cost you an afternoon: follow the paper version and you get a stack that starts and then refuses to show you a UI.

The short answer

Twelve becomes seven, and since minio-init, migrate and bootstrap exit when they finish, four containers stay running: postgres, minio, api, web.

What you save is Milvus (a 2.6GB image), etcd, Vault, Redis, the ingestion worker and the outbox container.

1. The readiness endpoint tells you which dependencies are real

The fastest way to find out whether a dependency is hard is not the deployment guide — it is the health check. A deployment guide documents intent; a health check documents behaviour.

In server/app/api/v1/health/router.py, three backends are treated differently:

try:
    db.execute(text("SELECT 1"))
    db_status = "connected"
except Exception:
    raise HTTPException(status_code=503, detail="Database is unavailable")

try:
    await storage.ensure_ready()
    storage_status = "connected"
except Exception:
    raise HTTPException(status_code=503, detail="Object storage is unavailable")

try:
    await vector.check_ready()
    vector_status = "connected"
except Exception:
    vector_status = "unavailable"

Database or object storage down means 503. Vector store down means the field reads unavailable and the endpoint still returns 200. The docstring gives the reason: the platform degrades gracefully when the vector store is down, so a vector outage should be surfaced rather than pull the instance out of rotation.

That leaves two hard requirements: a reachable Postgres, and a writable storage root.

The second one says storage root, not MinIO — and I assumed that distinction meant MinIO could go. That is wrong conclusion number one.

2. Wrong conclusion #1: local filesystem storage does not work inside the image

The storage adapter is built on fsspec (server/app/adapters/storage/fsspec.py), and the base URL resolves in this order:

self.base_url = base_url or settings.storage_url or self._default_local_base_url()

_default_local_base_url() returns a file:// URI under the repository root. So point STORAGE_URL at a local directory (or leave it unset) and storage should land on disk with no object store at all.

I configured exactly that, and the API came up returning 503:

{"success":false,"code":"SERVICE_UNAVAILABLE","message":"Object storage is unavailable"}

Constructing the adapter directly inside the container gave the real error:

PermissionError: [Errno 13] Permission denied: '/app/home'

/app/home is a strange path, given that I passed /home/appuser/soit-storage. The cause is this function:

@staticmethod
def _normalize_root_path(root_path: str) -> str:
    return root_path.replace("\\", "/").strip("/")

strip("/") removes the leading slash too, so the absolute path /home/appuser/soit-storage becomes the relative path home/appuser/soit-storage, which fsspec's LocalFileSystem then resolves against the process working directory. The image sets WORKDIR /app/, so it lands in /app/home/....

And /app is not writable: server/Dockerfile does COPY ./ /app/ without --chown, leaving it owned by root, while the final instruction is USER appuser (uid 10001).

So inside the published image the local-filesystem path is effectively dead: whatever you pass ends up under /app, where a non-root process cannot create directories. Mounting a volume does not rescue it either — Docker creates the mount point owned by root as well. Making it work would mean running the API as root or pre-chowning a mount, and neither belongs in a guide aimed at people trying the project for the first time.

So MinIO stays. It is cheap, at least: one long-running container plus a minio-init that exits, on a couple hundred megabytes — an order of magnitude smaller than the Milvus group.

(For the record, MinIO wears two hats in the full topology: the platform's artifact store, and Milvus's object backend. It was never separable from Milvus anyway.)

3. The vector group leaves as a unit — and it is not a graceful degradation

milvus depends on etcd (metadata) and minio (data). Does the API still start without milvus and etcd? Yes, and the reason is in the adapter's constructor docstring (server/app/adapters/vector/milvus.py): the connection is established lazily on first use, so building the port during dependency injection does not fail when the vector store is unavailable.

But do not expect it to degrade into empty results, because the vector port has no environment-level fallback. From server/app/wiring/container.py:

def _create_vector_port(self) -> VectorPort:
    import os
    if os.getenv("PYTEST_CURRENT_TEST") or os.getenv("SOIT_TESTING") == "1":
        from app.adapters.vector.memory import InMemoryVectorPort
        return InMemoryVectorPort()
    from app.adapters.vector.milvus import MilvusVectorPort
    return MilvusVectorPort()

The in-memory implementation is reserved for test runs; unlike the secrets port, it never consults ENVIRONMENT. The real effect: the platform boots, non-vector features work, readiness honestly reports vector: "unavailable", and knowledge retrieval raises the moment you use it.

The readiness response from the actual run says exactly that:

{"status":"ready","database":"connected","storage":"connected","vector":"unavailable"}

That conclusion held. But the same run surfaced something the code does not show you, which is the next section.

4. Wrong conclusion #2: without Milvus, the web container never starts

That readiness response took 34 seconds to come back.

The reason is not hard to guess: vector.check_ready() has to resolve the milvus hostname and open a connection, and the container is not there, so every request waits out DNS and connect timeouts. The vector probe is fail-soft, but it is not fail-fast — nothing bounds how long it may take.

Which runs straight into Compose's own health check:

{"Test": ["CMD-SHELL", "python -c \"...urlopen('http://localhost:9200/health/ready', timeout=3)\""],
 "Interval": "10s", "Timeout": "5s", "Retries": 5}

The probe times out after 3 seconds, Compose gives it 5, and the endpoint needs 34. It cannot pass. In the run, the API container sat permanently at:

soit-api-1   Up 3 minutes (unhealthy)

The service itself is fine — I logged into it. Only the health check fails. But web declares depends_on: api: condition: service_healthy, so a normal up -d web means web never starts at all. You get a stack with a perfectly working API and no UI, and very little to tell you why.

The fix is small: pass --no-deps for web as well. It is a static frontend; it only needs the browser to reach the API, not Compose's opinion about the API's health.

docker compose ... up -d --no-deps web

Started that way, web comes up healthy and serves HTTP 200.

This is the one finding in this post that reading the code could never produce. On paper you get a guide that looks right and leaves you staring at a dead URL.

5. Vault genuinely does degrade

The secrets port is wired differently (same container.py):

if not settings.vault_url or not settings.vault_token:
    if self._allows_in_memory_adapters():
        from app.adapters.secrets.memory import InMemorySecretValueStore
        return InMemorySecretValueStore()
    raise RuntimeError("Production requires Vault URL and token for the secrets adapter")

_allows_in_memory_adapters() accepts ENVIRONMENT values dev / development / local / test / testing, and compose defaults to development. So leaving VAULT_URL and VAULT_TOKEN empty swaps in the in-process secret store and the Vault container can stay down. Verified in the run: migrate, bootstrap and api all worked with no Vault anywhere.

The cost is in the name: in-process means not durable. The model API key you configure during the demo is gone the moment the container restarts.

6. Redis is three different questions

Redis is interesting because it is not a binary. The three places that use it disagree about what its absence means.

The event bus can be switched. memory is the default; compose is what changes it to redis:

backend = (settings.event_bus_backend or "memory").lower()
if backend == "redis":
    return RedisEventBus(...)
if backend == "memory" and self._allows_in_memory_adapters():
    return InMemoryEventBus()

The same ENVIRONMENT guard applies — in production that branch raises. The in-memory bus only delivers within a single process, which is exactly why it pairs with folding background work into the API process.

The permission cache degrades gracefully. In server/app/kernel/identity/permissions.py the Redis accessor returns None when it cannot connect, and callers treat None as a cache miss and re-check against the database. One less cache layer, same answers.

Rate limiting is a hard dependency that usually never fires. RateLimiter (server/app/kernel/ports/common/rate_limiter.py) is a Redis sliding window with no in-memory equivalent. But the call sites are conditional (server/app/kernel/ports/tools/policy.py):

rate_limit = kwargs.get("rate_limit_per_minute") or self.rate_limit_per_minute
if rate_limit:
    await self.rate_limiter.check_rate_limit(...)
if self.daily_quota:
    await self.rate_limiter.check_rate_limit(...)

No configured limit, no Redis call. Dropping Redis from a demo is therefore safe as long as you do not configure per-tool rate limits or daily quotas. That is the one item here that depends on what you do during the demo.

7. One service you fold in rather than remove

outbox-dispatcher runs the transactional outbox. Its setting says exactly what the flag means (server/app/settings/settings.py):

outbox_dispatcher_enabled: bool = False
"""Enable background outbox dispatcher in the API process."""

The flag does not control whether dispatching happens — it controls where. Compose sets it to false and runs the same logic in a separate container. For a demo, invert it: set OUTBOX_DISPATCHER_ENABLED=true on the api service and skip the container. server/app/main.py reads the flag at startup and attaches the dispatcher to the API's lifespan.

Why production does the opposite: validate_runtime_requirements() contains if self.outbox_dispatcher_enabled: raise ValueError("Production requires the dedicated outbox dispatcher process"). Dispatching and request handling in one process compete for the same resources, and a restart interrupts both at once. Fine for a demo — and note that this is enforced by code, not advised by documentation.

8. Skip the ingestion worker unless you are demoing RAG

knowledge-ingest-worker builds from its own image target (server/Dockerfile) with one extra dependency group:

FROM base AS knowledge-worker
RUN --mount=type=cache,target=/root/.cache/uv \
    /bin/uv sync --frozen --no-dev --extra knowledge-worker

That extra is docling[rapidocr] — document parsing and OCR. While we are here, a common misconception: torch, torchvision and torchaudio live in the local-embedding extra in pyproject.toml, not in knowledge-worker, and not in the API image either. The worker is lighter than people assume — but if your demo never uploads a document, it has no reason to exist.

9. The commands, as actually run

One Compose trap first: api lists milvus and vault in depends_on, so Compose starts them for you even when you leave them off the command line. Every step needs an explicit --no-deps, and you sequence the one-shot jobs yourself.

The env file (all of these override compose defaults):

printf '%s\n' \
  'ENVIRONMENT=development' \
  'VAULT_URL=' \
  'VAULT_TOKEN=' \
  'EVENT_BUS_BACKEND=memory' \
  'OUTBOX_DISPATCHER_ENABLED=true' \
  > .env.minimal

Bring it up on the published images — overlay docker-compose.images.yml and pass --no-build, or Compose will build from source:

COMPOSE="docker compose --env-file .env.minimal -f docker/docker-compose.yml -f docker/docker-compose.images.yml"

$COMPOSE up -d --no-build postgres minio minio-init
$COMPOSE run --rm --no-deps migrate
$COMPOSE run --rm --no-deps bootstrap
$COMPOSE up -d --no-build --no-deps api web

migrate prints a run of alembic upgrades; bootstrap prints Bootstrap completed. along with the admin ids.

Then verify. Remember that readiness takes more than 30 seconds (section 4), so give curl a generous timeout:

curl -s -m 60 http://localhost:9200/health/ready

From the run:

{"status":"ready","database":"connected","storage":"connected","vector":"unavailable"}

vector: unavailable while the whole thing still reports ready is section 1's code path observed from the outside — the output is its own proof.

Then exercise a real path, not just the health endpoint:

curl -s -X POST http://localhost:9200/api/v1/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"changeme123"}'

An access_token in the response means the database and auth path are both working. The UI is on http://localhost:5000 with the same credentials.

docker ps will show the API as unhealthy, and that is expected (section 4). The service is fine.

What this is not

As usual, the limits:

• This is not a supported deployment shape. It is a demo trim. Set ENVIRONMENT=production and every shortcut above is closed off one by one: validate_runtime_requirements() demands the Redis event bus, the dedicated outbox process, Vault, OpenTelemetry, and plugin signature and digest verification. Missing any of them fails startup. That is deliberate fail-closed behaviour.
• The API stays unhealthy, so do not hand this topology to anything that orchestrates on container health — Kubernetes probes, or start-up ordering that waits on a healthcheck, will both break.
• In-memory means gone on restart — secrets, and any event in flight on the in-memory bus.
• Without Milvus, vector features raise rather than return empty. Demoing knowledge bases means putting milvus and etcd back.
• The rate-limit caveat is yours to judge: dropping Redis assumes no configured limits.
• The default SECRET_KEY is change-me, and bootstrap will warn you about it (InsecureKeyLengthWarning). Harmless for a demo; do not let that value outlive one.

Two bugs found along the way

Writing this turned up two problems of our own. Both are filed, and it seems fair to say so here rather than quietly fix them:

1. _normalize_root_path() calls strip("/"), which turns absolute paths into relative ones, making the local filesystem storage backend unusable inside a container (section 2). That function is presumably meant to normalise object-storage key prefixes; backends like file://, where an absolute path means something, should not get the same treatment. (issue #43)
2. The vector readiness probe has no timeout, so a missing vector store drags /health/ready past 30 seconds and makes the Compose health check fail permanently (section 4). Fail-soft was implemented; fail-fast was not. A seconds-level timeout on check_ready() would give you both. (issue #44)

Worth noting: both are things you only hit by actually running a reduced topology, and our own CI runs the full one. Which is probably an argument for supporting the minimal shape officially.

Why write this down at all

If four containers are enough, why does the default ask for twelve?

Because the default topology targets the production shape, not the demo shape. Every service cut above maps to a requirement that production enforces in code: secrets need a real secret manager, events need to cross process boundaries, dispatching needs to scale independently, vectors need to persist. You get something you can experiment against as if it were production, and the price is a first command that looks frightening.

The point is that the distance between those two shapes is measurable in a handful of environment variables — and measuring it happens to be the fastest way to understand the architecture: the health check tells you the hard dependencies, the wiring code tells you which ports have fallbacks, and validate_runtime_requirements() tells you where production draws its line.

But keep the other lesson too: reading the code gives you hypotheses; running it gives you conclusions. Two of my three were wrong, and the wrong two were exactly the ones that would have stopped you.

Try it

SOIT is Apache-2.0 and the code is on GitHub:

• Repository: github.com/soit-ai/soit
• Full quickstart (the twelve-service path): docs/quickstart.md in the repo
• Governance demo: docs/governance-demo.md — a 20-minute local run that walks through permissions, secrets, call auditing, cost attribution, replay and regression

If you get the minimal topology running, or get stuck on a step, open an issue and say so. Right now this trim only exists as a blog post; if the feedback says it is useful, we will turn it into a Compose profile so --profile minimal does the whole thing — and fix those two bugs on the way.

Disclosure: I maintain SOIT.

Everything after it is not. The moment you propose pointing that server at real systems, somebody from security starts asking questions, and "the SDK handles it" stops being an answer. There turned out to be five of those questions. When they were first put to me I could not answer a single one.

Below is each question, and how we ended up answering it in SOIT — an open-source agent runtime with governance sitting in the middle of the call path. Every claim points at a file in the repo, because posts like this are unusually easy to write as a slide deck instead of as software.

1. Who is allowed to call this tool?

MCP does not have an opinion here. Whatever list_tools returns is what the model can call. Visibility is capability.

In a multi-tenant, multi-workspace deployment that is not enough. SOIT installs an MCP server as a plugin artifact rather than as a config entry. Tool references are namespaced — mcp_tool:{server}:{tool}, parsed by parse_mcp_tool_ref in server/app/adapters/tools/mcp.py — and every resolution carries a RequestContext holding tenant_id, workspace_id and user_id.

Two things follow from that:

1. From the agent's point of view, a tool from a plugin, a tool from an MCP server, and a built-in adapter all look identical. Bindings are typed and versioned.

2. Permission checks, secret injection, egress limits, audit, cost attribution, trace and replay apply to MCP tools automatically. Nobody writes the governance path twice.

Each agent version also carries a capability allowlist covering models, knowledge bases, workflows, tools, plugins and MCP servers. So "which MCP tools can v3 of this agent call" is something you can diff and roll back, rather than a runtime toggle somebody flipped.

2. Where do the credentials live?

Most MCP integration examples look like this:

{
  "auth": { "type": "bearer", "token": "sk-xxxxxxxx" }
}

A plaintext token in a config file. It ends up in git. It ends up in logs. It ends up in the config backup somebody exported to a laptop.

SOIT rejects this outright. _build_auth_headers checks for a token or value field in the auth config and raises:

MCP credentials must use secret_id

Only secret_id is accepted, resolved through SecretsPort at call time. Same for API keys — and they are only supported in headers, never in a query string, because query strings leak through logs and referrers.

The real value exists in memory for the duration of the call and nowhere else. What gets persisted — to the database, to audit records, to traces — is a redacted copy: ToolPolicyGateway._resolve_secrets builds it in the same pass that resolves the secret, keeping only secret_id and the signing policy reference (server/app/kernel/ports/tools/policy.py).

Three auth types are supported: bearer, api_key, oauth2. OAuth follows 2.1 with authorization-server discovery (RFC 9728, RFC 8414 / OpenID Connect) and resource-bound tokens (RFC 8707), using the client_credentials grant.

One limitation worth stating plainly: the browser-based authorization_code flow is not implemented. SOIT calls MCP servers on its own behalf, not on behalf of a user sitting in front of a browser. If you need "call a protected MCP server as the end user," this does not cover you.

3. Where can it connect to?

This is the one that should worry you most.

You deployed the MCP server, but it is a thing that makes network requests on your behalf. Put a URL in the tool arguments and it will fetch it. The classic shape of this is asking it for http://169.254.169.254/ — the cloud metadata service, holding temporary credentials.

SOIT's egress policy is deny-by-default, in three layers.

Layer one: domain policy. check_egress_policy matches the target domain against tenant-scoped and workspace-scoped allowlists and blocklists, with the blocklist winning. The defaults are enable_egress_policy: bool = True and egress_allowlist: list[str] = [] — an empty allowlist means nothing is permitted until you say so. And if the policy lookup itself throws, the answer is deny, not allow:

except Exception as exc:
    raise ForbiddenError(
        "Egress policy lookup failed; request denied",
        {"resource_ref": resource_ref},
    ) from exc

Fail-closed is not a slogan. It is whatever you actually wrote in each except branch.

Layer two: per-address validation after resolution. Passing the domain check is not enough — DNS rebinding lets an allowlisted hostname resolve to 127.0.0.1 or 10.0.0.x. So after the domain is allowed, GovernedEgressGuard actually resolves the hostname and checks ipaddress.ip_address(address).is_global for every address returned. One non-public address and the whole request is refused (server/app/kernel/security/egress.py).

Closed off in the same pass: non-http/https schemes are denied by default, URLs carrying userinfo (https://user:pass@host/) are denied, and a DNS failure is a denial rather than a retry.

Layer three: authorization per hop. A URL that cleared both layers returns a 302 pointing at your internal network. Now what? So the outbound HTTPX client is built like this (server/app/adapters/http/governed_client.py):

async def authorize_request(request: httpx.Request) -> None:
    await guard.authorize(ctx, resource_ref, str(request.url))

event_hooks["request"] = [authorize_request, *request_hooks]
kwargs.setdefault("follow_redirects", False)

Authorization hangs off the HTTPX request event hook, so every request that actually goes out is checked, redirect hops included — not just the URL you handed in at the entry point. And redirects are not followed by default.

The MCP adapter builds its sessions with that client, so the whole MCP path — initialization, list_tools, every call_tool — sits inside these constraints.

4. Can you find out what happened afterwards?

Tool calls are the only place an agent produces real side effects. A model saying something wrong can be asked again. A tool that changed a row in the production database changed it.

SOIT persists each tool call as a step of a run, and writes two pieces of evidence per call:

• Gateway audit. log_gateway_request with gateway_type="tool". The request side records the tool_ref, redacted parameters, and the egress decision (allow / deny plus the target URL). The response side records success, result type, metadata, and error. The failure path writes one too — the first thing the except branch does is emit the audit record. That is the one people forget, and the one you need when something has gone wrong.

• Step metrics. Latency, success flag, summarized arguments and result, error code and error details.

The same call writes a cost entry with billing_basis="requests", the provider, and source_port="tools" — so "what did this agent's MCP tools cost this month" is a query you can drill into by agent, workflow, tool, and source (source_kind=plugin | mcp | builtin).

On top of that, an OpenTelemetry span soit.tool.invoke carrying tenant, workspace, run and step ids, for whatever APM you already run.

5. Can you replay it?

The most frustrating property of agent debugging is that it does not reproduce. Same input, different reasoning.

At the tool layer you can at least be deterministic. Every tool call in SOIT carries an idempotency key, defaulting to tool:{run_id}:{tool_call_id}, and claims a leased execution record. If the claim lands on a record that already completed, the cached response comes straight back and the external tool is not called again.

The retry policy changes accordingly. The comment says it better than I can:

max_retries=1 if kwargs.get("idempotency_key") else self.max_retries,

Durable Agent calls are at-most-once at this boundary. Not every downstream adapter can honor an idempotency key.

At-most-once at this boundary, because you cannot assume the MCP server on the other end honors your idempotency key. Better to call once too few than once too many — for writes, that trade is not really a choice.

Rate limits and daily quotas come along with it, keyed by tool_ref plus tenant, workspace and user, so one runaway agent does not burn a whole tenant's third-party API budget.

What this does not do

The usual honest list:

• MCP transport is streamable HTTP only, targeting the MCP SDK v1 line. The stateless 2026-07-28 protocol revision is not supported yet.

• OAuth is client_credentials only, no authorization_code (see question 2).

• A marketplace for one-click MCP tool installation is on the roadmap; today you install plugin artifacts by hand.

• The default egress allowlist is empty, which means your first MCP server will be refused until you add its domain explicitly. That is deliberate, but it does add a step to the quickstart.

Why none of this belongs in the agent framework

A question that comes up constantly: how does this relate to LangChain and friends?

They are not the same layer. A framework answers "how do I orchestrate this call." A runtime answers "under whose identity did this call run, with whose credentials, what could it reach, what evidence did it leave, and can I replay it." The first is a concern while you write the code. The second is a concern after the code ships and someone else asks.

You can certainly put permission checks inside a framework, but then every new tool integration reimplements the governance logic. Push it down into the runtime's port layer and MCP tools, plugin tools and built-in tools all travel the same path — which is the reason question 1 could say "nobody writes it twice."

Try it

SOIT is Apache-2.0 and the code is all on GitHub:

• Repository: https://github.com/soit-ai/soit

• Quickstart: docs/quickstart.md in the repo

• Governance demo: docs/governance-demo.md — a 20-minute local script that walks through permissions, secrets, call audit, cost attribution, replay and regression, and writes a machine-readable report at the end

If you are pushing MCP toward production right now, I would genuinely like to hear which of the five questions is blocking you. In our experience the hardest one is not technical — it is "who gets to decide what goes on the allowlist."

Disclosure: I maintain SOIT.

This post is about the part that is actually hard — not building agents, but being willing to let them run in production.

The problem isn't building agents. It's trusting them.

Every team I talk to has the same story. The demo took a week and it was great. Then security, compliance and ops started asking questions, and the project parked itself at PoC:

• What is this agent allowed to do, and who decided that?

• Where do its credentials live, and what leaks if a prompt goes wrong?

• Which hosts can it reach when a tool call makes an outbound request?

• What exactly did it do last Tuesday, and can we prove it step by step?

• What did that run cost, and which team pays for it?

Frameworks answer none of these — they orchestrate calls and leave controls to you. Hosted platforms answer some, but you inherit their model choices, their data boundary and their pricing. Cloud-vendor agent services answer more, in exchange for the deepest lock-in of all.

Our answer is to make governance a kernel concern rather than a patch applied afterwards.

Governed execution

The idea is simple to state: every agent run is a governed run. Chat turn, agent loop, or workflow run — everything flows through one runtime ledger (Run / RunStep / Trace), and the same controls apply on every path:

• Permissions — tenant and workspace scoping on every resource, RBAC with resource-level grants. Every record carries tenant_id and workspace_id; there are no escape hatches.

• Approved capabilities — agents bind to models, tools, knowledge bases and workflows through per-version allowlists. A tool from a plugin, an MCP server, or a built-in adapter looks identical to the agent and passes the same checks.

• Secret boundaries — credentials live in Vault with workspace-scoped visibility and are injected at the gateway. Business code never opens a raw HTTP client or LLM SDK.

• Egress policy — outbound HTTP from tools is policy-controlled. An agent cannot quietly call a host you never approved.

• Ledger, cost, audit, replay — per-step tokens, latency and cost; a full audit log of privileged operations; a trace timeline you can replay step by step.

• Separation of duties — the Dev role that builds and runs agents cannot change egress policy, secrets, or installed plugins. That takes a workspace Owner or Admin.

None of this is a wrapper around someone else's runtime. SOIT is a hexagonal architecture: a stable kernel, versioned JSON Schema contracts on every primitive, and replaceable adapters at the edges — so the governance layer holds no matter which model or vector store you swap in.

That last property is the whole reason for the shape. Governance implemented at the integration layer has to be rewritten for every new tool and every new provider. Governance implemented at the port layer is written once, and every adapter inherits it whether it wants to or not.

What's in the box

Four pillars, all of them in the open-source edition:

• Build — visual agent assembly with versioning and release management, a DAG workflow editor, a knowledge pipeline (PDF/DOCX/Markdown/HTML into Milvus-backed retrieval), and MCP support: any Model Context Protocol server resolves into the tool registry without code changes, including OAuth 2.1-protected servers.

• Execute — an outbox-based event-driven runtime with checkpoints, retries and fallback chains; multi-model routing across OpenAI, Anthropic, DeepSeek, Qwen and any OpenAI-compatible endpoint — including the one on your own GPU.

• Observe — a workspace console built on the runtime ledger: live run volume, cost burn, failure rates, drill-down by agent, workflow and tool, plus OpenTelemetry tracing and Prometheus metrics.

• Govern — everything in the section above.

It self-hosts with one command:

git clone https://github.com/soit-ai/soit.git
cd soit
cp .env.example .env
docker compose --env-file .env -f docker/docker-compose.yml up -d

A supply chain you can verify

If your agents run in production, so does your agent platform — which makes it part of your attack surface.

Every SOIT release is built by a tag-triggered pipeline that publishes digest-addressable images, SPDX SBOMs, Sigstore-backed build provenance and SBOM attestations, a deterministic source archive, and SHA256SUMS. v1.0.0 shipped that way: three images on GHCR that pull anonymously, and artifacts you can check with gh attestation verify before they enter your environment — we ran it ourselves and got exit 0.

Secret scanning, dependency audit and container scanning run in CI as gates, not as dashboards.

What SOIT is not

A post like this should also say what you are not getting:

• It is not a lightweight chatbot builder. If you want a prompt box and a share link, plenty of tools do that with far less infrastructure.

• Content safety and PII detection are not implemented. SOIT exposes a content-safety port and an HTTP adapter so you can plug in a classifier you operate, and inspection outcomes become part of run evidence — but with no adapter configured, no inspection happens. I would rather say that than ship a checkbox that does nothing.

• The project is young. v1.0.0 is released and the CI gates are in place, but there is no large-scale production deployment vouching for it yet. We run it ourselves. Early adopters welcome, with eyes open.

License: Apache 2.0

Commercial use, self-hosting, internal deployments and building products on top are all unrestricted. The core platform is and will remain open source; SSO, advanced audit reports and multi-region deployment live in SOIT Enterprise. The commercial boundary is drawn in the feature set, not in the license.

Come break it

The repo is at github.com/soit-ai/soit. The quickstart takes about ten minutes on a machine with Docker. There are good first issues seeded and the roadmap is pinned.

If the architecture trade-offs are the interesting part for you — the outbox runtime, the spec-first contracts, lease-based worker recovery — say so and I will write those up separately. I also wrote a companion piece on what happens when an MCP tool call has to obey RBAC, secrets and egress policy: Five questions to answer before you put MCP in production.

If your agents graduated from notebooks and hit the trust wall, this was built for you. Tell me where it falls short.

Disclosure: I maintain SOIT.

Originally published at https://soit.ai/en/blog/soit-open-source-launch