System Manifest
Recipe-based multi-agent deployment via YAML manifest files. Deploy entire agent teams with pre-configured permissions, shared folders, schedules, and auto-start.
Concepts
system_view: block. Use system views to monitor and manage agents that belong to the same manifest.How It Works
Create a system manifest YAML file defining agents and their relationships.
Deploy it from the web UI (see below), the deploy_system MCP tool, or the REST API.
All agents are created, configured, and started according to the manifest.
Agents appear on the Dashboard with appropriate tags for grouping.
Installing a System from the UI
Go to Library → Systems (/library?tab=systems). You need the creator role or above, because installing a system creates agents — below that role the tab is not shown at all.
Pick one of three sources:
Pick a system — cards for the manifests bundled with your Trinity instance (config/manifests/). Each card shows how many agents it creates, whether it adds schedules, whether it replaces the global system prompt, and whether it looks already installed.
Upload a file — choose a .yaml/.yml file. It is read in your browser; the file itself is never uploaded.
Paste YAML — paste or hand-edit a manifest directly.

Then:
Click Preview. This validates the manifest without creating anything and shows you the agent names that would be created, which agents would be able to call which, and any schedules that would start. Fix anything listed under Blockers and preview again.
Click Deploy. Deploy stays disabled until you have previewed the current text — if you edit the manifest afterwards, preview again.
Things the Preview Will Make You Confirm
Some manifests do more than create agents, so Deploy is gated on an explicit checkbox when either applies:
It replaces the global system prompt. A top-level prompt: key overwrites the platform-wide instructions for every agent on your instance, not just the ones in the manifest. Only an admin's deploy applies it. For anyone else the agents still deploy, the prompt is left as it is, and the preview (and the result, once agents are created) says so with a prompt_requires_admin note instead of asking you to confirm.
It starts recurring schedules. A schedule is enabled unless you write enabled: false, so those agents begin running on a timer as soon as they deploy — consuming API budget without anyone asking them to.
Reading the Result
"All agents created" — everything worked.
"Some agents were created" — the rest are listed with the reason. Note that re-running the same manifest does not retry the missing ones; it creates a second, suffixed copy of the ones that already succeeded. Fix the cause and create the missing agents individually.
"No agents were created" — nothing was deployed, so there is nothing to clean up.
Things needing attention — the header only describes whether agents were created. Shared folders, permissions, schedules, tags and starting the agents are all best-effort, so read this section: a system can report "agents created" while none of its schedules were set up.
"Outcome unknown" — the request timed out or the server errored mid-deploy. The deployment may still be running. Check your agent list before retrying, because deploying twice creates duplicate agents.
Unrecognised keys are reported as warnings rather than silently ignored — at the top level and inside an agent entry alike (credentials:, skills:, and display_label: are the ones people try first; the manifest does not carry them). The per-agent guardrails — disallowed_tools, extra_path_deny, extra_bash_deny — are not manifest keys either: a manifest that declares them gets an unknown-key warning and configures nothing, so set them on the agent after deploy (Agent Guardrails). Preview and deploy resolve the same default resources, so a preview that passes on the fleet default will not fail at deploy because the two disagreed.
Two known limits of the preview, both deliberate:
Templates referenced as github: are only checked when you actually deploy, so a clean preview cannot promise a remote-template manifest will work.
Agent names are provisional. If a name is taken, Trinity appends _2, _3, and so on, and it re-checks at deploy time — so a name can shift if something else is created in between.
What a Manifest Describes
preset: (full-mesh: everyone can call everyone; orchestrator-workers: only an agent named orchestrator can call the rest; none: isolated) or an explicit: map of each caller to the agents it may call. Setting both is an error.model is written on deploy and apply, compared on apply (a change is a schedule_update naming model), and exported, so an export re-applies with the same model.default_tags — tags applied to every agent in the system (the system name is always applied as a tag too).tags — additional tags applied to a specific agent, on top of default_tags.system_view — an optional block (name, icon, color, shared) that auto-creates a System View filtered to the system's tags, so the fleet shows up as one group in the Dashboard sidebar.Manifest Sketch
name: content-production
default_tags: [production, content-team]
system_view:
name: Content Production
icon: "📝"
color: "#8B5CF6"
shared: true
agents:
orchestrator:
template: github:YourOrg/orchestrator-agent
resources: { cpu: "2", memory: "4g" }
folders: { expose: true, consume: true }
tags: [lead]
schedules:
- name: daily-planning
cron: "0 9 * * *"
message: "Create today's content plan"
writer:
template: local:scribe
folders: { expose: true, consume: true }
tags: [worker]
permissions:
preset: orchestrator-workersTarget-State Keys (Apply and Deploy)
A manifest can also carry the configuration each member should have, so one file describes the whole system. Every key is optional and per member unless noted. Both deploy (create mode) and apply (apply_system, POST /api/systems/apply, which reconciles a live system and previews by default) read them.
name: content-production
naming: bare # top level: optional, default `prefixed`
agents:
content-lead: # under `bare` the key is the agent's full name
template: github:YourOrg/lead-agent
skills: [research, publish] # library skills
skill_sets: [ops-core] # skill sets
gates: # approval map: which skills need a person's approval
publish: { approver: primary, deadline_hours: 24 }
grants: [agents.manage] # admin grants (capabilities)
seat: content-lead # the canon role this AGENT holds
person_seats: # seats a PERSON must fill: role and kind only
- { role: content-owner, kind: approver }
style-guide:
template: github:YourOrg/style-guide
deploy: false # named in the system, never created| Key | What it does |
|---|---|
| naming | prefixed (default): members are named <system>-<key>. bare: the key is the full agent name, and apply adopts an existing untagged agent of that name by adding the system tag (listed in adopted). |
| skills, skill_sets | Assigned when missing. An unknown skill or set is a blocker. |
| gates | {<skill>: {approver, deadline_hours}}. Written when missing or different; approver is primary, approver, or role:<id>. The preview reports the same refusal the write would give. A gate is written before its skill: if the gate does not land, that skill, or a skill set carrying it, is held back and named, never delivered without its approval. If the gate's write fails on a skill the member already holds and no gate is in force, apply unassigns that skill (no gate, no skill): the result shows skill_unassigned_gate_failed and one line in warnings. Fix the gate, re-declare the skill if it is not under skills:, and re-apply; the next apply holds the assignment back until the gate lands. An admin can turn this off under Settings → Access (Unassign a skill whose gate cannot be written, on by default); then the skill stays assigned and the result says skill_runs_ungated (also one line in warnings). Two cases are always report-only and leave the skill assigned: previous_gate_stands, when the gate stored before still applies, and skill_held_via_set, when the skill comes from an assigned skill set (unassigning it would take the set's other skills too) — fix the gate and re-apply, set it by hand, or unassign the skill or set by hand. The preview says ahead of time which of these a failed write would lead to. |
| grants | Capabilities from the admin grant list. Written only when the caller is an admin in a signed-in session. Any other caller (an agent key, an admin's own MCP key, a non-admin) gets the grant reported as held back (grant_requires_interactive_admin, plus one warning line), and the rest of the manifest still applies. |
| seat | The canon role the agent itself holds. Written only when an installed assignment module provides a seat writer; otherwise reported seat_unobserved and nothing is written. On apply and on deploy alike, a seat is written only for an admin in a signed-in session, the same gate as a grant; any other caller gets it reported as held back (seat_requires_interactive_admin on apply, seats_require_interactive_admin on deploy). |
| person_seats | [{role, kind}], where kind is primary, approver, collaborator or viewer. Report-only: apply says whether each seat is filled, vacant or unobserved and never fills one. A person seat names the role and the kind, never a person: an email address anywhere in seat or person_seats (or an extra key such as person:) is refused, because the manifest is meant to be committed to git. |
| deploy: false | A declared-only member. Apply gives it the verdict declared_only and reports whether its template is in the catalog and whether an agent already holds its name. That agent is never created, changed or deleted. An explicit permission edge or folders: naming a declared-only member is refused; a preset skips it with a warning. Any other key it carries is ignored, and validation says which in one warning. deploy: false governs apply only: if that agent carries the system tag, restarting the system restarts it and a teardown removes it, and apply says so (declared_only_member_tagged); remove the tag to keep it out. In a prefixed system an untagged agent whose name starts with <system>- is reached the same way, by name (declared_only_member_prefixed); rename it to keep it out. |
Rules that hold for every key:
skill_extra, grant_extra, gate_undeclared, …) and never unassigns, revokes or clears it. Removing something is a human act in the agent's own settings. The one exception is named and switchable: a skill whose declared gate could not be written is unassigned (see gates above), unless the setting is off or a skill set brings it, in which case it stays assigned and is only reported.summary in the apply result counts, per group (skills, grants, gates, roles, members), what is written, what is only reported, and what is unobserved. Unobserved means this install has nothing that can answer for that group (each member lists its unobserved groups). It is never shown as “in sync”. A failed read is different: it blocks the member with the retryable member_reads_unavailable. A dry run counts what apply would write; a real run counts only the writes that actually landed (a skill held back for its gate, or a write that failed, is not counted), and a refused run counts none. Likewise adopted lists only agents whose system tag was actually added.# unobserved: comments that say so (and name anything that could not be read — including every member's seat on an install with no assignment module). Grants, gates and seats appear only where the caller could read them directly: grants and seats for the agent's owner or an admin, and gates for anyone the Skills tab's gate read admits. An export names what was withheld from this caller. resources are the member's effective values, so re-applying an export keeps a limit that is waiting for a restart. A dry run of an export on the system it came from shows nothing to create, nothing to write and no drift: something an agent already holds stays in sync even if it has since left the library (a skill or skill set, a retired capability, a gate whose approver can no longer be resolved). Person seats in a manifest, and a seat the assignment module did not answer for, read back as unobserved. Exporting the same system twice gives the same text.local: template declares its own schedules, the preview shows what happens to each one: a manifest schedule with the same name updates the template's schedule in place (which keeps the template's on/off state, reported as enabled_differs), and a schedule only the template declares is reported as schedule_undeclared. A github: template is not read during a preview, so its schedules show as pending_template_resolution until the run, and the run reports the template's own schedules. If the run could not create the member or read its schedules back, they are still shown as pending_template_resolution, next to the failure. If a data volume agent-<name>-workspace is left over from an earlier agent of that name, the preview is invalid with member_workspace_volume_leftover and the run is refused before anything is written. Apply never takes over leftover data: remove the volume (docker volume rm agent-<name>-workspace) or rename the member. The deploy preview also warns when a manifest schedule shares its name with one the template declares and differs from it, because deploy keeps the template's schedule.Deploy Result (Best-Effort by Default)
Deploy is best-effort / continue-on-error by default: if one agent fails to create, the rest still deploy. Read the response status field, not just the HTTP code:
| status | Meaning | HTTP |
|---|---|---|
| deployed | All agents created. | 200 |
| partial | Some agents failed; the survivors were still created and configured. | 200 |
| failed | Zero agents created. | 500 (the full report is the response body) |
| valid | Dry-run validation passed (nothing created). | 200 |
| (refused) nothing_to_deploy | Every member is deploy: false, so deploy has nothing to create. Refused on the dry run and the real deploy; use apply to report on declared-only members. | 400 |
Members marked deploy: false are listed by name in agents_declared_only[]. A partial deploy returns the survivors plus a failed[] list. Each entry carries {name, short_name, template, reason, status_code} so you can see exactly which agents failed and why. A total failure returns HTTP 500 with the same full report as the body — so always inspect status / failed[] rather than trusting the HTTP status alone.
Two deploy options control this:
dry_run — validate and preview only. Returns status: "valid" with the list of agents that would be created. Nothing is deployed.strict — restore the legacy abort-on-first-failure behavior. The first agent that fails aborts the whole deploy (re-raising with that failure's original status code).Redeploy caveat: re-running a manifest with deploy after a partial failure does not converge — it _N-suffixes the already-created agents (e.g. my-system-worker_2) instead of reusing them. Use apply (apply_system, POST /api/systems/apply) to bring a live system in line with its manifest instead; it creates only the members that are missing.
After Deploy: Reading, Restarting, and Exporting a System
Deploy is a one-shot recipe, but the deployed agents remain addressable as a system:
Membership is by tag, not by name. Deploy tags every member with the system name, and the post-deploy routes resolve membership from that tag. Only agents deployed before tagging existed fall back to the <system>-* name prefix, and even then an agent whose own tag claims a longer prefix is excluded — so restarting acme never touches the agents of a system named acme-extra. A system whose tagged members all lack the <system>- prefix is bare-named, and then an untagged <system>-* agent is not a member at all.
List (GET /api/systems, list_systems) lists a system by its tag, never by splitting agent names at a hyphen, so content-writer does not invent a content system. A tag is listed only with evidence that it is a system: the system view created for it, an apply run that named it, or a member named <tag>-*. A plain tag is not a system.
Get (GET /api/systems/{name}) returns the members you can access with their permissions, shared folders, and real schedules.
Restart (POST /api/systems/{name}/restart, restart_system) stops and starts every member. It requires the creator role or above and is human-only: an agent-scoped API key is refused, because the per-agent start/stop routes only let an agent touch agents it spawned and a bulk restart would bypass that.
Export (GET /api/systems/{name}/manifest, get_system_manifest) writes a manifest you can deploy again. Permission edges pointing outside the system are dropped rather than exported as broken names, and the instance-wide platform prompt is never embedded as the manifest's prompt: — deploying the export elsewhere would otherwise overwrite that instance's prompt for every agent.
Default System on First Run
On a fresh install(no non-system agents yet), Trinity auto-seeds a bundled default system from a shipped manifest, so a new instance comes up with a running starter fleet — zero manual steps.
TRINITY_DEFAULT_SYSTEM_MANIFEST to disabled (or none / off / 0 / false).TRINITY_DEFAULT_SYSTEM_MANIFEST at your own manifest file path. Left unset, Trinity uses its bundled manifest.MCP Tools
| Tool | Description |
|---|---|
| deploy_system(manifest, dry_run?, strict?) | Deploy a system from a manifest. dry_run validates and previews without creating; strict restores abort-on-first-failure. Check the response status / failed[]. A failed deploy comes back as a result, not a thrown error: the report with success: false and the http_status (for example the 500 failed report or a 400 manifest error) |
| list_systems() | List all deployed systems |
| restart_system(name) | Restart all agents in a system (creator role, human callers only — refused for an agent key) |
| get_system_manifest(name) | Export the system as a redeployable YAML manifest |
| apply_system(manifest, dry_run?) | Reconcile a live system to a manifest (previews unless dry_run is false). Human-only, creator role. Never deletes, revokes or restarts; see Target-state keys. An MCP key never writes grants or seat: they are only reported. They are written when an admin applies the manifest in a signed-in session; otherwise grant them in the agent's Settings |
| teardown_system(system_name, dry_run?, agents?) | Remove a deployed system's agents. Previews by default (dry_run is true unless you set it to false). Needs a matching entitlement; without it the tool reports that the capability is not available (404/403) instead of failing |
API Endpoints
| Endpoint | Method | Description |
|---|---|---|
| /api/systems/deploy | POST | Deploy a system from a YAML manifest (dry_run, strict in the body); creator role |
| /api/systems/apply | POST | Reconcile a live system to a manifest (dry_run defaults to true); creator role, human-only |
| /api/systems/manifests | GET | The bundled manifest catalogue shown under Pick a system (creator role) |
| /api/systems/manifests/{manifest_id} | GET | One bundled manifest's YAML and preview (creator role) |
| /api/systems | GET | List all deployed systems |
| /api/systems/{system_name} | GET | Get one system's agents, permissions, folders, and schedules |
| /api/systems/{system_name}/restart | POST | Restart all agents in the system (creator role, human-only) |
| /api/systems/{system_name}/manifest | GET | Export the system as a YAML manifest |
See the Backend API Docs for full request/response schemas.
Limitations
teardown_system) needs a matching entitlement._N-suffixed duplicates rather than reusing the survivors; use apply to converge.local: template names may not end in a newline.