Soot DocsHow Soot is designedMarkdown ↗

04 / Agents and packs

Agents, teams, packs and Soot Forge

What a Soot looks like on disk; packs and grants; teams, Lead and coordinators; Soot Forge, sources and bundles.

This page covers what people create and distribute on Soot: what a Soot is when it sits in files, how a pack brings skills and tools into a Soot, how several Soots work together as a team, and where Soot Forge keeps packs, team templates and releases. The problem to solve: an agent must be readable, reviewable and copyable to another machine, while its permissions are still decided by the machine's owner.

Model

Sample text · not a command
Soot Forge (catalog + release, SHA-256)          your repo (source)
   │ packs, team templates, General                   │ Soots, own packs, teams, schedules
   ▼                                                  ▼
 packs_dir/<id>/ ─ select ─►  soots/<id>/soot.json  ◄─ deploy by source
   (installed, nothing granted)  (soul, mission, packs)
        │ needs                     │ team: entries + members
        ▼                           ▼
   grants.packs ◄── host grants  groups.<id> ── coordinator takes the work first
   (deployment.json)                │
                                    ▼
                    spawn_subagent (AgentCore) ─► teammates in the same runtime

Lead: the user's personal assistant, one per server, belongs to no team.

Three principles: configuration is files (Soots, packs and teams are directories of JSON and Markdown, and can live in Git); flat composition at load time (a Soot lists packs, the loader merges them into one list, no inheritance); installing is not granting (having files in packs_dir does not let any Soot do more; the Soot must select the pack and the host must grant it).

Concepts

ConceptWhat it is
SootA small agent with a clear job: soul (identity), mission (task), the packs it selects, a model tier. Directory soots/<id>/.
PackA reusable bundle of skills and tools, with needs (what it needs from the machine). Directory packs/<id>/ with pack.json.
ToolAn executable operation or a native host tool. The operation ID is <pack>_<tool>.
GeneralThe default Soot of every workspace and Nest, created from a preset released by Soot Forge.
Team (group)A list of Soots working together, with coordination limits. It is an execution boundary, not a different agent identity.
Coordinator (Đầu mối)The first Soot in a team's entries; takes work first and has no admin rights.
LeadThe user's personal assistant in Nest. One per server, fixed name, belongs to no team.
Team templateA recipe for building a team. In Nest it is called Mẫu Soot ("Soot templates").
Soot ForgeThe 2found/soot-forge repo: pack catalog, team template catalog, General preset, releases with SHA-256.
SourceA slice of configuration (Soots, own packs, teams, schedules) owned by one repo and deployed to a shared runtime.

Three kinds of configuration, three owners

Whichever question you have, edit the matching place:

QuestionWhereOwner
Who am I, what do I do, which packs do I use?The Soot folder (soots/<id>/: soot.json, SOUL.md, MISSION.md)Agent author
Which skills and tools do I provide, what do I need from the machine?Pack (packs/<id>/pack.json)Pack author
Where does it run, what does it connect with, who is granted what, when does it receive work?Deployment (deployment.json, AI settings, vault)Host (operator)

A Soot contains no secrets, listeners, routes, schedules or permissions on outside accounts. A pack contains no identity, soul, mission, routes or credential values. This way the same pack serves many Soots, the same Soot can run on another machine, and permissions always sit in one place where people can inspect them.

A Soot is code

A Soot is a folder, and the folder name is its ID:

Sample text · not a command
soots/support/
  soot.json             settings: name, model, packs, chat, run limits
  SOUL.md               identity and behavior ({{name}} is the display name)
  MISSION.md            the job to do
  skills/**/SKILL.md    this Soot's own skills, in the Agent Skills format (including those it saved with save_skill)
  packs/<pack>/         private packs only this Soot sees (skills only)
  evals/                cases that check this Soot's own behavior
  adapter/              what was learned (soot improve, soot train), layered over the definition

Each file is used when it is there; no field points at them. soot.json keeps only the choices:

JSON sample · not a command
{
  "name": "Support",
  "description": "Answers customers from the docs",
  "avatar": "fox",
  "model": "pro",
  "packs": ["office:read", "crm:tools=find,update", "knowledge", "feedback:to=pm"],
  "chat": {"handoff": "members"},
  "execution": {"max_turns": 16}
}

FieldMeaning
avatara mascot name, an https URL, or a PNG/JPEG/WebP data URL
modela tier (flash, lite, pro, max); the host decides the provider. Or an object {tier, compact_at, effort, …} to override for this Soot only
packseverything the Soot can do, including two built-in packs: knowledge (every knowledge pool of the host, or knowledge:pools=docs,faq) and feedback:to=<soot> (the record_feedback tool, notes handed to that Soot)
chatpresent means the Soot takes conversations: publish (final by default, or reply), mode, handoff, release_after_hours, memory_write, channels
execution, improve, archivedrun limits, the self-improvement schedule, archiving

There is no field for the ID, soul, mission, skills, adapter, tools or project: the ID is the folder name, prose is a file, tools come from packs, the project comes from the team. evals/ travels with the Soot, so reviewing the code also reviews how it is checked; soot improve and soot train read that same store and write what they learn into adapter/ (evolution.md). The full fields are in soot schema soot.

skills/**/SKILL.md follows Agent Skills: the name comes from the frontmatter name:, else the folder name; an invalid or duplicate name is a soot check error, never skipped silently. A pack also scans its own skills/**/SKILL.md, and a folder under packs_dir holding only skills/ is a pack without pack.json. packs/<pack>/ inside a Soot folder is a private pack (skills only; grants stay in the deployment).

Soot deliberately does not read AGENTS.md or .agents/. Under agentsstandard.com and Codex those are rules for coding agents: they load every AGENTS.md from the repository root down to the folder they work in, and .agents/skills. If Soot read them too, a Soot's mission would become the coding agent's rules, and the repository's contributor guide would become the Soot's mission.

Moving a Codex agent to Soot:

Codex / agentsstandardSoot (soots/<id>/)
AGENTS.md (the agent's rules)rename to MISSION.md
.agents/skills/<name>/copy to skills/<name>/, SKILL.md unchanged
a skill shared by several agentscopy to packs_dir/<pack>/skills/, no pack.json needed
an MCP server, a shell commanda tool in a pack with pack.json, then soot grant <pack>

Flat composition at load time

deployment.json is the entry point and only lists paths to Soot definitions; it contains no inline agents. The loader (internal/core/config, loadConfig) reads the deployment and AI settings, reads the Soots and sources, selects packs for each Soot, checks grants.packs, loads packs_dir, and then attaches a credential binding to each operation. The result is a flat list: each Soot has exactly the skills and tools of the packs it selected.

A Soot selects a pack in one of three ways:

ReferenceThe Soot receives
"office"Every skill and every tool of the pack
"office:read"Every skill and only the read tools
"office:tools=plan,draft"Every skill and only the listed tools

The pack is the unit of switching on and off, so important boundaries (shell, admin, posting, writing data) are a pack of their own, and a write pack should leave its read part usable on its own. tools= only keeps a Soot from carrying the whole schema of a large pack; it grants no extra permission.

There is no use or capabilities (recipes nested in a pack): the loader rejects them. To split permissions, split the pack.

Packs and permissions

Sample text · not a command
pack.json   needs: {credentials: {API_KEY: {from: "env:STATUS_API_KEY"}}, env: ["HOME"]}
                              │ declares
deployment  grants.packs: {"status": {credentials: {API_KEY: "env:STATUS_API_KEY"}, env: ["HOME"]}}
                              │ host grants (soot add, soot grant, Nest "Cấp quyền" (Grant))
runtime     the tool receives exactly those variables, nothing more

"Installing is not granting" has several consequences:

  • soot add copies files into packs_dir, records the source, prints what the pack needs, and grants the host-side part into grants.packs (--no-grant to grant later). It does not run scripts, build, start adapters, or select the pack for any Soot.
  • A Soot has a pack only when it lists the pack itself. A coordinator or another Soot can only request a grant; granting always goes through a human reviewer. operator-type credentials are entered by the user in Nest.
  • Updating a pack does not widen permissions: a version that needs more than the current permissions is held until a person views the preview and grants.

Packs are split by the unit a user wants to switch on or off together: split when the integration, dependencies, release lifecycle or risk level need to be independent. The pack's execution contract (tool is a process, soot/v1 envelope, approval, unclear effects), interface, pages and storage are extensions, see extensions.md.

General

General is the Soot that soot spawn and Nest create by default. It is not hardcoded in the binary: each Soot Forge release publishes general-release_<v>.tar.gz (the definition) and general-preset_<v>.json. The preset says which packs to download (install), where to get them (sources), which packs General selects (packs), and what Nest adds (nest.packs: soot-nest, nest-lead).

What explains or operates a runtime feature ships with the runtime (builtin/corepacks/), so it never drifts from the binary; business knowledge stays in Forge. So soot (the configure tool), nest-lead (the Lead's tools and skills) and soot-nest (side-bar, nest-pieces, nest-links) are built in like toolbox. The preset still lists them in install and nest.packs for older runtimes; this runtime downloads none of them, and Soots select them as before. Two skills attach by role, with no selection and no setting: soot-domain to every Soot, coordinator-mail to every Soot in a team (the coordinator and the members, where work sent to a team arrives). A skill costs one line in the skill index, its body is read when needed, and it grants nothing.

Creating a workspace downloads the archive, checks SHA-256, installs the packs and then writes a flat configuration. From then on the workspace does not depend on the preset: reopening Nest does not restore revoked permissions, and new packs arrive only through updates. If the release asset is missing, creation fails outright and does not fall back to a neighboring checkout or an unchecked download. A newly created Nest records lead: "general", so General is that Nest's Lead. soot spawn --empty creates an empty Soot with no packs; --project and --source download nothing (see Project bundle and Source).

Teams

The user picks a Soot and gives it work. When the Soot has a granted team, it picks the right team for each task the way it picks a tool; a simple task it answers directly.

Sample text · not a command
User ─► the selected Soot (root, automatic chat)
                 │ spawn_subagent group/<id>   (AgentCore)
                 ▼
          team A: coordinator ─► teammates (named delegate)
                 │ result + evidence
                 ▼
          combined answer

There is only one execution path. AgentCore owns the model loop, jobs, budgets, retry, cancellation and subagents; Soot only attaches configuration, permissions, storage and tools. There is no second team dispatcher or separate "orchestrator"; the general coordination guidance sits in the schema of spawn_subagent, and pack skills carry only expertise.

A team declares entries (who takes the chat, the first element is the coordinator), members (the roster), description (so delegation knows when to choose it), limits (number of delegations, depth, concurrency, model calls) and optionally brief, projects, contract (workspace.md). Full fields: soot schema deployment.

Teams do not grant permissions

The most important rule: a team neither widens nor narrows its members' permissions. Each member runs as its own Soot (packs, credentials...). The old fields group_operations, members.<id>.operations and members.<id>.credentials are rejected by the loader (retired_field) instead of being ignored, so an old deployment does not accidentally gain permissions. A team decides only three things: who takes the chat and who may be called, the shared coordination limits (intersected with the entry Soot's root budget), and the data scope (group_id in the tool envelope, filled in by the host and not choosable by the model; the credential's backend must restrict data by itself).

A team run also follows these rules:

  • The team receives the user's original request, not a task or context written by the root Soot, so model-generated text cannot carry one team's data to another.
  • Native history, memory and artifacts are separated by conversation, team and Soot, and are not moved between teams. The conversation records every team that contributed; reading it back requires permission on all of them, and losing permission on one team hides the whole mixed conversation.
  • Each turn freezes the destination and the configuration fingerprint; if the configuration changes midway, queued work is blocked and does not widen on its own. Effects with an unclear outcome do not rerun on their own.
  • Host shell is not a sandbox: a member with shell still has shell inside the team.

A teammate that delegation calls must be on the same runtime as the root Soot, because identity, grants, store and receipts belong to a single runtime. The narrow exception is a remote team (served by another runtime): it takes data contracts and sent work (send, contracts/team-mail.md), and is not a chat or delegation target (workspace.md).

Chat has two modes that do not change after creation: automatic (group_id: "auto", the Soot picks the team for each task, still one chat) and pinned (a fixed team). Sidebar folders grant no permissions. The old configuration collaboration.<soot>.members still runs for old chats and is not migrated into teams automatically.

In Nest, Đội Soot → Tạo nhóm ("Soot team → Create team") builds a team; saving makes a draft revision, and Áp dụng ("Apply") waits for running work to finish. Only an operator can edit team permissions (surfaces.md).

Lead and coordinator

Lead is the user's personal assistant in Nest: one per server, never part of a team, with admin rights (nest-lead_manage; anything that needs money, a budget or a permission change waits for a person in Cần bạn ("Needs you")). The coordinator is the first Soot in a team's entries: it takes work first, runs the team's schedules and bots, hands tasks to teammates, and has no admin rights. Lead is configured with lead in the deployment; the coordinator is just the order of entries.

Work sent to a team (send, workspace.md) is routed by the host and costs no model turn: work for team:<id> runs as the coordinator; work for soot:<member> runs as that member itself, inside the team, with its own tools and permissions, the team's budget and its own daily_tokens and max_run_tokens. A tool-only schedule of a member, when wake_when is true, wakes that member; only a failing tool chain wakes the coordinator. A team with inbox: "hold" holds work from other teams until a person starts it.

Lead is recognized through the nest-lead pack, not by name. A roster that lists Lead is still loaded, but Lead is dropped from it; a team's schedules, bots and tasks never run as Lead. When Nest opens without a Lead, it adds a lead Soot: the nest-lead pack and the Lead's prompts ship with the runtime; its other packs follow the workspace's General, or the General preset of the Forge release (SHA-256 checked) when the workspace never had them. Full contract: contracts/lead.md.

Team templates

A team template (soot/group-template/v1 to v3) is how a "prebuilt team" is distributed: members with soul and mission, the packs they need (archives with SHA-256), and the credentials that need connecting. From v2 it has inputs (questions to confirm), profiles (a token budget per member) and schedules that run under the coordinator's name; a template can leave root: "" so the user picks the coordinator at install time. v3 adds team contracts and schedules that run a chain of tools without a model.

A template contains no running deployment, provider, credential, history or DB, and grants nothing beyond the packs it names. There are two ways to install, both producing the same configuration change:

  • Ask Lead in chat. Lead reads the authenticated Forge catalog (offline, only the templates on the machine), asks the inputs, proposes a profile, then calls group.create. The Cần bạn card lists the team, coordinator, members, token ceiling, cycle and brief. On approval it installs any missing archives and saves everything in one revision; Undo archives those Soots and removes the team.
  • Tạo nhóm ("Create team") in Nest, or the CLI soot group add|inspect|create.

A template's credentials attach by reference into the host's tool credential store; the user enters the values afterward. soot group save and export save an edited team as a new template (they read no credentials or transcripts). Submitting to Forge is a PR.

Soot Forge

Soot Forge is the public place to find, install and share things Soot can use; the page trysoot.com/forge is built from the repo's catalog.json.

The repo contains catalog.json (the pack catalog, handwritten), groups.json (the team template catalog, kept separate), packs/, groups/ and general/ (the preset).

  • Contribute by PR: the pack lives in the repo, or a catalog entry points to a public repo, a directory and a reviewed full commit. Pin the commit so a branch change does not change a reviewed pack.
  • Each release builds one archive per entry, with SHA256SUMS; published tags and assets do not change. The runtime fetches the latest stable release and checks SHA-256 before writing. A pack installed from a Forge asset URL leaves a receipt pointing back to it, so automatic updates know it is a Forge pack.
  • The catalog is metadata and not permission: reading an entry or installing a pack grants nothing to any Soot. Forge CI checks the rules (every tool declares run.mode, every {{cred:NAME}} appears in needs). A checksum tells you which bytes you got and does not authenticate the publisher.
  • toolbox, soot, nest-lead and soot-nest are not installed from Forge: the runtime provides them (builtin/toolbox/, builtin/corepacks/), and soot add and soot pack add refuse them. Forge keeps its copies of the last three and the coordinator-mail skill in team-rhythm, marked deprecated, for runtimes up to 0.21. A packs/<id> folder an older runtime installed is ignored, a Forge pack's skill of the same name yields to the runtime's, and soot check writes a note for each (not a warning).
  • Installing from outside Forge still works (soot add from Git or an archive), but it is not updated automatically. Forge is not a paid marketplace or a runtime registry.

Updates

A single update service keeps four kinds of installed things current: Forge packs, General, teams created from Forge templates, and the Soot software itself. Clients (Nest, soot updates) only display a document returned by the service; no client compares versions itself. Three rules:

  • Only non-MAJOR versions apply automatically. A MAJOR version, a kind set to manual, or a blocked entry is only listed and waits for soot updates apply.
  • Hand edits are never overwritten. Teams are merged field by field: fields the user edited are kept, the rest take the new version. A change to team composition waits.
  • Installing is not granting. A version that gives a Soot or team wider permissions (a new pack, a new need) is not applied automatically and waits for a person to agree. A pack installed from Git or a file is not part of Forge and stays as it is.

Command: soot updates.

Source: many repos, one runtime

One runtime takes Soots from many repos. Each repo owns one source and deploys independently; the host keeps the rest.

Each repo writes only under sources.d/<id>/; deployment.json, AI settings, the vault and Soots created in Nest belong to the host.

Host'sSource's
Listener, AI provider, tier, vault, data poolSoots (choosing only a tier in model), own packs
default_soot, lead, routes, grants.sourcesTeams, website clients, schedules attached to the source's Soots or teams
Soots created in NestA source's Soot edited in Nest for a quick trial, but it shows drift until the repo deploys again

The reason for the split: adding or changing a provider never needs a source to be redeployed, and deploying one source never touches the provider or another source. The rules that keep that boundary: a source chooses a tier and not a provider; IDs are runtime-wide; a source carries no secrets. A source's Soot lists packs in packs like any Soot; a pack its source does not ship (for example the machine's browser) is a request to the host, and the host allows it or not in grants.sources. Asking is not being granted.

soot spawn --source <id> creates a source, soot bundle checks it, soot source deploy puts it into the Nest on this machine, or 2srv deploy for a runtime managed by 2server. A deploy is prepare then commit, writes only under sources.d/<id>/, and has no rollback of its own (redeploy the old commit). Removing a source is deploying an empty source; conversations and history remain. Improving a source's Soot creates no drift: the learned version sits in .soot/adapters/ outside the slice, and is pulled into the repo with soot improve <soot> --pull --into <repo>.

Project bundle

soot spawn --project <root> creates a project as files: a deployment, a scripted AI for local checks, a support Soot with no grants, schemas, guidance for coding agents, a .env.example with placeholders only, and soot.bundle.json. It installs nothing and does not run a runtime.

soot.bundle.json (C1 v1) is a digested inventory of the authored part. Each pack pins three different values, none a substitute for another: archive_sha256 (the archive bytes), tree_digest (the extracted file tree, counting the executable bit) and the source (a local archive, or Git with a full commit). selected_executables must equal exactly the operations the host actually grants, so installing a pack adds no entry. source_digest covers both the manifest and every file. Symlinks, special files and private state (.git, .env, *.db, *.pem...) are rejected.

soot bundle checks, --refresh rewrites the digests after a review of a deliberate change, and soot bundle-admit is the receiving side: it rehashes offline, trusts no receipt, and rejects a mismatch instead of fixing it. A bundle grants no permissions. Fixture: internal/compose/scaffold/testdata/c1-v1.json.

Boundaries

AgentCore owns the model loop, jobs, budgets, cancellation and subagents (runtime.md). The core (internal/core/config, internal/core/conversation) selects packs, intersects permissions and freezes the configuration for each turn. A pack carries skills, tools, needs, interface and storage (extensions.md). The host keeps credentials, listeners, providers, grants.packs and team permissions. Nest draws the roster, team chat and Cần bạn cards (surfaces.md).

Deliberately not done: a separate team dispatcher (delegation is an AgentCore tool), letting teams grant permissions (easy to widen permissions implicitly), letting packs carry identity or schedules (one pack must serve many Soots), trusting the catalog (reading, installing and updating all grant nothing), writing new agents into the core (adding an agent means adding config, packs and skills).

Not yet available

Teams with members on another runtime (today only the remote team for data contracts); rollback for sources (redeploy the old commit); pushing team templates from Nest to Forge (today a manual PR); packs integrating outside platforms (Telegram, Facebook, X, YouTube, TikTok) are only planned.

Content reviewed: 2026-11-12