Architecture

How Trellaris is built, and why it is built that way. The through-line is a single rule: there is one path that runs an agent. Every surface, every trigger, and every integration converges on it, which is what lets one governance decision be authoritative everywhere instead of being re-implemented per feature.

The rules the code obeys

How the pieces fit together

The functional picture: what an agent is made of, what it is granted, where requests come from, and what a run leaves behind.

Reading the diagram

• The workspace and ring are the outer frame: every entity inside belongs to one organization and is visible only within its ring.
• The agent is the only thing that runs. Skills, knowledge, and memory are attached to it; tools, connectors, and MCP servers are granted by it.
• Governance sits on the way in, not beside it. A surface cannot route around it, because the surface's only route to the agent goes through the executor.
• The run record is what makes the whole thing auditable after the fact — events for replay, an artifact set, a cost line, and audit entries.
• Canvas appears as a surface because that is what it is: a shared document the agent writes to and the human edits back, with each revision immutable.

What happens on every run

The same six steps regardless of what triggered the work. The right-hand column is where governance actually lands — each check is at a specific point, not a general aspiration.

What the loop actually does

1. Assembly is per run, not per agent. The tool registry is rebuilt every time from the declaration plus configuration, so a policy change or a revoked credential takes effect on the next run without touching the definition.
2. The system prompt is composed from the guardrail preamble, the agent body, a compact skill index, and injected context — memories, knowledge citation rules, attached documents, and a canvas diff if the human edited past the agent.
3. The model turn streams. Tokens, tool calls, and status land on the run's event stream as they happen, so the interface is live and the same sequence can be replayed later.
4. Tool results are treated as data. They are screened before re-entering the model — this is where a prompt-injection attempt planted in a fetched page is caught.
5. Parking is real suspension. Loop state is serialized to the run row; the worker is released. Approving reconstructs the loop and executes the call exactly once.
6. Nothing is left hanging. Workers hold a heartbeat lease. If one dies, a reaper resolves the run — resuming a background run from its last checkpoint, or failing it with a reason.

Deployment topology

Four planes and one ingress. Each service scales independently, and the documentation site you are reading is its own container with no runtime dependency on the API.

What each plane is responsible for

Module map

The API is one deployable but twelve owned boundaries. Each module owns its tables and exposes a service; nothing reaches across.

Data model highlights

Extension seams

Every external dependency sits behind an interface with a deterministic default, which is why the whole test suite runs with no cloud account and no model provider.

Tech stack

Open-source packages

Everything Trellaris depends on is OSI open source, and CI enforces an allowlist on every build so a proprietary transitive dependency fails the pipeline rather than shipping. Licenses below are as published by each project; the build's own check is the authoritative gate.

API — runtime

Agent-format package

API — development and CI

Web application

Web — development and CI

Security scanners

Pinned binaries baked into the API and worker image, each reporting its own stage.

Sandbox image

Preinstalled so sandboxed scripts start fast and work entirely offline — the container has no network, so nothing can be installed at run time.

Infrastructure