Configuration¶
Routine database logs¶
Permission and task-archive repository initialization messages and
gateway_transcript_page_loaded history-read events use DEBUG logging. Set
logging.level: DEBUG to include them when diagnosing startup or browser
refreshes. Repository initialization checks an existing database as well as a
new one; the message does not mean the database was reset. Initialization
failures remain visible at ERROR.
Active runtime state and admission¶
agent.max_deferred_messages limits durable inbox admission while an agent is busy
or paused. It defaults to 100 and must be positive. New messages beyond the limit
remain in NATS for redelivery. A duplicate already owned by the inbox can still be
acknowledged. Lowering the limit preserves an existing backlog during recovery,
logs a warning, and prevents new admission until the backlog falls below the limit.
NATS can deliver a task a second time, for example when the agent that took it stopped before acknowledging it. Agents of a team that share one database then handle the copy like this:
- While the agent holding the task looks alive, the copy is dropped
(
event=task_copy_dropped_held_elsewhere). If that agent stops later, the replacement that takes over its saved work runs the task. - When the holder has stopped, or handed the task back after losing its launch
lease, the agent that received the copy runs it (
event=task_custody_takeover), and a later takeover of the stopped agent's saved work leaves that task out. - If the holder only looked stopped and is still running, it drops the task the
next time it saves its work and stops working on it without replying
(
event=task_custody_taken_over). Work it did before that may happen twice. - A copy of a task any agent of the team already finished is dropped
(
event=duplicate_archived_delivery_ignored).
These rules need agent.same_role_runtime_takeover_enabled left on (the
default). With it off, nobody takes over a stopped agent's saved work, so a copy
dropped while its holder looked alive is not run if that holder stops later.
After upgrading to a release with this check, each agent's first start may log one
event=runtime_snapshot_orphans_dropped warning per saved snapshot. Earlier
releases left records of finished tasks in saved snapshots; they are dropped when
the snapshot is read. No action is needed.
Going back to an earlier release is not supported while agents hold unfinished
work. This release records an action the runtime held back (for example an answer
kept for a final review) with the outbox status held_back, which earlier releases
do not know: they refuse a saved snapshot that contains it, so that agent cannot
restore its work. Finish or abandon in-flight work before downgrading.
The active task snapshot layout now uses strict version-3 records and does not read the previous monolithic layout. Before deploying this change, finish or explicitly abandon in-flight work and stop affected runtimes. Back up the database before removing obsolete active task snapshots under operator control. Clearing snapshots does not recover their work. Archived task history, conversations and independent schedule/authorization records are outside this layout change.
Repair an active runtime snapshot upgrade¶
If config loading first fails with Unknown memory plugin id(s) for
long_term_profile_full, memory_graph_retrieval, team_profile_summary, or
user_profile_summary, remove those retired settings while the instance is
stopped:
python -m scripts.retire_memory_plugins --config /data/instance_config.yaml --dry-run
python -m scripts.retire_memory_plugins --config /data/instance_config.yaml --yes
This standalone script backs up the original config beside it, then removes
only those plugin entries and their references in agent.memory.plugins.order.
It preserves supported plugin settings and does not access stored memories.
The edited YAML is reformatted; original comments remain in the backup. Apply
the same cleanup to the deployment's source config so a redeploy retains it.
Then proceed with snapshot retirement below.
Unsupported active task storage layout means a persisted owner still has an
unsupported storage header. Updating authorization settings does not change it.
The wire document can already be version 3 while its database layout is obsolete.
The opposite is also possible: a supported storage header can contain records
that the current runtime rejects. Run the preflight below even when there is no
storage-layout error; it validates the complete snapshot with the same decoder
used during recovery.
If unfinished work must complete, run the previous build to drain it before upgrading. Otherwise, explicitly abandon that work using the offline command below. Stop every runtime using the affected manager database and retain a full database backup before proceeding. The command archives raw snapshots for inspection; it does not make their tasks resumable in the new build.
Run from the repository or /app in a maintenance container with the instance's
usual mounts and secret environment. Use the instance's team_id and config path:
python -m scripts.retire_runtime_snapshots \
--config /data/instance_config.yaml --team-id TEAM_ID --dry-run
The preview lists incompatible owners without printing task contents. Select
the stored owner IDs from this preview, which can differ from the new agent
IDs in the startup log. Repeat --owner-agent-id for each owner to retire:
python -m scripts.retire_runtime_snapshots \
--config /data/instance_config.yaml --team-id TEAM_ID \
--owner-agent-id STORED_OWNER_ID --reason "Abandon old work for snapshot upgrade" --yes
--config accepts generic and instance YAML. Use --env /path/to/team.env if
the maintenance process needs an env file; mounted secret-file variables also
work. For an explicit SQLite target, replace --config ... with
--sqlite-path /data/dbs/task_history.db. Use the repository's .venv
Python when running outside the container.
Retirement copies each selected header and its child rows into
retired_task_runtime, verifies the archive, and removes those active rows in
one transaction. Archive or removal failure rolls back the whole operation.
Fully recoverable snapshots and owners outside the selected team are rejected.
Retirement revalidates the selected owners inside its transaction, so an old
preview cannot authorize removal of work that has since become recoverable.
Deferred messages, cancellation records, task history, conversations, schedules,
and permissions are left intact. This command does not cancel external work or
mark old gateway requests complete. Review unresolved requests after restart
before resubmitting them.
Run the preview again, then restart the new build once the affected team has no
incompatible owners. Do not use reset_agent_storage.py for this failure; it
resets the entire store.
The system uses two different YAML configuration tracks plus env files.
Separate requests changing the same record¶
A person can have several requests running at once, for example in separate Web Chat threads. When two of them change the same record (today, one of the person's own knowledge pages), the later change is refused instead of being saved over the earlier one, and the agent tells the person, who can repeat it in a new message. A request that was stopped or has finished changes nothing, including a helper agent still working on it. Changes made from a page that is out of date ("changed since you read it") are always refused. Memory facts, schedules, heartbeat items and Objectives have only that "changed since you read it" check. Files the agent writes with its file tools, and its shell or Python commands, are not checked. A file tool write replaces the whole file at once, so another request never reads a half-written file and two writes never mix, but the later write still replaces the earlier one.
agent.request_conflict_checks (default true) turns the checks between
requests on or off. With false, the later change is saved over the earlier
one, as before this check existed, and the Status page shows a note while it is
off. Agents cannot change this setting. Turning it on again counts only
changes made from then on.
File Roles¶
| File | Role |
|---|---|
config.example.yaml |
Checked-in example for the generic config.yaml schema |
config.yaml |
Optional generic/base manager config, gitignored |
instance_config.yaml |
Onboarded instance runtime config |
team.env |
Secrets and generated internal credentials for one instance |
control/SOUL.md and other control/ files |
TeamArchitect behavior, model overrides, the startup roster, team templates, agent definitions, and team skills |
config.yaml and instance_config.yaml have different schemas and migration
histories. Do not copy fields blindly between them.
Tool allow and block lists¶
agent.tool_allowlist and agent.tool_blocklist use exact built-in tool
function names from this release's catalog. An unknown name stops configuration
loading and the error identifies its setting path. Both YAML formats check the
defaults and every agent_types.<type>.agent override, including types that are
not running and defaults that another list overrides. This avoids discovering
an invalid list only when a worker first starts.
Correct misspelled or removed names before restarting. For example, the old
delete_coremem function is now an action of memory, so a function-level block
must name memory. These lists cannot select individual actions; use
access blocks for operation-specific restrictions. MCP server
tools are not filtered by these lists and their names are refused.
Instance Folders¶
Only the instance root is configurable (instance_root in
instance_config.yaml, agent.instance_root in config.yaml; /data in
Docker). Every other location is derived from it:
<instance_root>/
├── instance_config.yaml, team.env operator files
├── control/ team control files
│ ├── SOUL.md, LLM_OVERRIDES.yaml, TEAM_AGENTS.yaml, TEAM_TEMPLATES.yaml
│ ├── agent_definitions/, agent_bundles/ (team_lead_generated/)
│ ├── skills/ operator-added and external skills
│ ├── access/tools/ web API tools and command-line tools
│ │ the team added
│ └── objective_execution_profiles/
├── dbs/ task_history.db and other databases
├── state/ runtime records: tool_results/, uploads/,
│ published_sites/ (page records),
│ attachment_copies/, model_failover/,
│ diagnostics/, execution_artifacts/
├── auth/ model sign-in tokens (OpenAI Codex, xAI)
├── exports/ team exports written by /upgrade
├── import/ team exports copied in for onboarding's Import
├── runtime/ records trusted services keep:
│ mcp-connections/ (installed MCP servers),
│ mcp-hosting/ (hosted MCP servers),
│ installed-permissions/,
│ skill-installation/ (reviewed skills),
│ team-import/ and team-export/ (team transfer)
└── workspaces/ the only area agents work in
├── users/<person>/ one person's private folder, with
│ sites/ (published pages) and scratch/
│ (temporary files; scratch/sent/ holds
│ copies of files sent to the person)
├── team/ shared by the whole team; team-shared/ is
│ everyone's common working folder, and
│ administrators may name more when adding
│ someone (/user ... --shared <name>)
└── agents/ shared by agents; the working folder
for work that runs for no person
Agents work only in workspaces/ and in the data folders an
administrator registers outside the instance. A task that works for a person
uses that person's folder as its default folder and can also use team/ and
agents/; it cannot see anyone else's folder except what that person
shared with the task's person. File tools, shell and Python commands (in
the code sandbox), notify_user attachments, research files, and Python
environments all follow this rule, and with authorization on each folder is
also an access decision (Files and folders).
Agents cannot open anything else under the root; they read and change team control files only through TeamArchitect's
typed settings, roster, and installation tools. The one exception is the two skill folders
(control/skills and runtime/skill-installation/installed): agents can read
a skill's files and run its scripts there but cannot change them. New or
changed team skills go through reviewed installation. Chat uploads are stored in
state/uploads; an agent copies one into its task's folder when shell or
Python needs to process it. Files agents attach to messages for people are
copied into scratch/sent/ of the person's folder before they are sent, and
pages agents publish for a person are written into sites/ of that folder
(Generated Sites). Old files in every scratch/ folder
are deleted automatically (Scratch retention), and so
are old saved tool outputs (Saved tool output retention).
Scratch retention¶
Agents keep temporary files in scratch/ of their task's folder
(users/<person>/scratch/, or agents/scratch/ for work for no person), and
the gateway keeps its copies of files sent to a person there too. Each time the
internal-improvement maintenance schedule runs, the manager deletes files in
every scratch/ folder that were last changed more than
tool_policy.scratch_retention_days days ago, removes folders that end up
empty, and never follows links:
tool_policy:
scratch_retention_days: 21 # 0 keeps scratch files
The same key is accepted in instance_config.yaml. The maintenance run's
report includes how many files it removed. Web Chat shows an attachment whose
copy was removed as no longer available. Administrators can also change the
number in Settings → Team → File Retention; the manager reads it when it
starts, so a change there applies after the next restart.
Saved tool output retention¶
Agents' tools save what they produce while they work, so a large result does
not have to stay in the conversation. Each time the internal-improvement
maintenance schedule runs (every six hours by default), the manager deletes
those saved outputs written more than tool_policy.output_retention_days days
ago (90 by default, about three months; at most 3650):
- Tool results too large for one answer, in
state/tool_results/, aged by the date in their folder name. - Long tool output saved from conversations (conversation artifacts): the
full text of a tool's output that was too long to keep in the conversation,
in
dbs/conversation_artifacts/, with its record in the task database, aged by the record's date. These files hold tool output, not chat messages. - Research results, in
research/of each person's folder and ofagents/. Only the result folders the research tools wrote go: they are recognized by the date and time at the start of their names and aged by it. Folders and files people or agents made there themselves stay, however old. - Execution run folders in
agents/execution/: folders that an interrupted run left behind, and Rust build folders not used for the period, each aged by when the folder itself last changed (a build changes its folder). A run or build folder is never deleted while it may still be in use, and never when it is less than two days old.
tool_policy:
output_retention_days: 90 # 0 keeps saved tool outputs
Conversations, their summaries, task links and completed tasks are kept
whatever this number is. After a saved output is deleted, an old conversation
still shows what the output was about, and an agent that tries to open it is
told that it was deleted under the retention policy; the agent can run the
tool again. Links are never followed. The maintenance run's record lists, for
each kind, how many items, files and bytes were deleted, and the manager keeps
the latest counts in state/output_retention.json. If no cleanup has
succeeded for two days, the Status page warns administrators.
Administrators can also change the number in Settings → Team → File
Retention; like scratch retention it applies after the next restart.
A week's notice first. When saved tool output retention first becomes active on an installation (the first maintenance run after an upgrade to this version, or after the number changes from 0 to a period), nothing is deleted for 7 days. During that week each maintenance run only counts what it would delete. Administrators get one Inbox notice saying on which date about how many items (and how much space) will be deleted, why, and what they can do: keep the default, change the number of days, or set it to 0 to keep everything. The Status page shows the date and the latest counts for the whole week and clears once deletion starts. A restart does not start the week again. Lowering an active period is your own choice, so it applies without a waiting week: the older outputs are deleted at the next maintenance run after the restart.
Upgrading: the first maintenance run after the upgrade starts that week. Seven days later, the backlog of saved tool output older than 90 days is deleted, unless an administrator changed the number or set it to 0 first.
Both clean-ups (scratch and saved tool outputs) run only with the
internal-improvement maintenance schedule. They run even when the
maintenance agent itself cannot start, but if
agent.schedule_maintenance.internal_improvement_review_interval_seconds is
0 the schedule is never set up and nothing is ever deleted: the manager says
so in its log when it starts (event=retention_cleanup_off), and the Status
page warning appears. A paused or turned-off schedule also stops them.
Upload retention¶
Files people send in any chat app are kept in state/uploads, with a record
in the gateway's database. The gateway deletes uploads older than
retention_days when it starts and every six hours after, together with
their records and the folders left empty, and never follows links. Agents
copy an upload into their task's folder to work on it, and those copies are
not affected.
interactive_apps:
plugins:
builtin.internal_website:
settings:
attachments:
retention_days: 90 # about three months; 0 keeps uploads
Administrators can also change the number in Settings → Team → File Retention; the next cleanup uses it, without a restart. Everyone signed in sees the current numbers there. Once an upload is deleted, opening it from an older chat message says the attachment was not found.
Until then, the assistant can use a file sent earlier in the same chat, for example "the photo I sent yesterday", without it being sent again; files sent with an answer to the assistant's question count too. It cannot reach files from another chat or another person, nor files sent before the team's update that started keeping each message's files; send those again. The same holds for files sent with a request that was still waiting to start when the team was updated: the request runs, but without its files. To avoid this, update when no requests are waiting; otherwise ask people to send those files again. Whenever files sent with a request could not be accepted, the assistant is told how many, and asks for them again if the request needs them.
A person's folder is named after their user id: generated ids such as
usr_3f9a1b2c4d5e are used as they are, and other ids become a readable name
plus a short hash.
Storage notices¶
Chat transcripts and completed tasks are kept; nothing deletes them. So that nobody's stored data grows unnoticed, the gateway and the manager each measure once a day how much they store for each active person, and the gateway sends the person an Inbox notice each time the total passes another step: at 5 GB, 10 GB, 15 GB and so on (1 GB is 1,000,000,000 bytes). The notice lists what takes the space: their folder, their chats, their completed tasks and conversation records, long texts saved with their conversations, and chat uploads still kept.
gateway:
storage_warnings:
person_step_gb: 5 # 0 turns these notices off
Administrators can also change the step, and the levels below, in Settings → Team → File Retention; the next check uses them, without a restart.
Each crossing is announced once, also across restarts. Someone whose data is first measured at 16 GB gets one notice, for 15 GB. When stored data falls below a step, for example after files were deleted from the person's folder, and later grows past it again, that is a new crossing and is announced again. If the manager has not measured a person's data for three days, the gateway sends them no notice, because the total would be incomplete. Status checks both processes' measurements and warns administrators when either is out of date, identifying the gateway or manager and which log to check. New people have time for the next daily check, and the first gateway check waits 15 minutes after startup. A folder that cannot be fully read keeps the previous total and measurement time, so a permission or filesystem failure cannot make a smaller total look current. The sizes are approximate: they count the stored text and files, not the space the databases and the disk use to hold them. Like other notices, these appear only in Settings → Inbox, not in a chat.
Administrators hear about the instance's storage on the Status page: the disk holding the instance folder, the disk of each SQLite database when it is another one, and the message server's stored messages when its account has a limit. A place nearing its limit is a warning and one Inbox notice; nearly full is a problem and another notice:
gateway:
storage_warnings:
nearing_limit_percent: 80 # warning, and administrators are told
nearly_full_percent: 95 # problem; must be above nearing_limit_percent
If a disk cannot be measured, Status reports that its free space is unknown and asks administrators to check the folder's availability and permissions. Other disks and the message server still show their results.
The bundled NATS server sets no limit for stored messages, so the page notes how much they take instead of a percentage; they are on the instance's disk. When a server does set a limit for the account, the percentage counts the bytes stored, not the space its streams reserve, so leave room for those reservations (64 MB for set-aside messages).
Upgrading from the single workspace folder¶
Earlier versions kept everything in <instance_root>/workspace. Upgrading the
configuration (assistant_cli.py migrate-config --config <instance_config.yaml>,
or the prompt on start) drops location settings that still hold their old defaults and stops
with an explanation if one was customized. The MCP folder settings
(mcp.registry_dir, mcp.hosting.definitions_dir, mcp.hosting.state_dir)
are dropped the same way by the upgrade to instance configuration version 12
(config.yaml version 10); if you had moved those folders, move their
contents to runtime/mcp-connections, runtime/mcp-hosting/definitions and
runtime/mcp-hosting/state under the instance root, remove the settings, and
upgrade again. Files are never moved for you:
startup refuses to run while old-layout files remain and prints the exact
mv -n commands. Existing shared workspace content moves to
workspaces/team/, because nothing records which person each file belongs to;
people can move private items into their own folders afterwards. Stop the
instance, run the printed commands, and start again.
Data Folders¶
A data folder is a folder outside the instance that agents can be given access to, such as a shared reports folder or a read-only reference library. Data folders are not configuration settings: an owner or administrator registers and removes them while Universal Agents runs, and every process sees the change without a restart. The list is kept in the access store, in the manager database.
/access folders add reports /srv/team-reports
/access folders add reference /mnt/reference --read-only
/access folders
/access folders remove reports
.venv/bin/python assistant_cli.py access folders add reports /srv/team-reports \
--config <instance_root>/instance_config.yaml --by <your user id>
The Access page's Files tab and an approved TeamLead proposal can register
them too. Agents, grants and blocks name a folder data/<name>, never its host
path. The path must be an existing absolute folder (in Docker, the path inside
the container, so mount the host folder there first), and a folder that holds
or sits inside the instance root, instance_config.yaml or the secure
broker's credentials folder is refused, because grants and shell commands would
then reach control files and secrets. The same check runs again whenever a
process reads the list; a folder that fails it is left out and logged
(event=data_folder_refused).
With authorization on, agents reach a data folder only with a folder grant,
such as /access grant agent-type:WebResearchAgent data/reports read. A grant
on a folder covers everything below it, so a grant on data/reports/2026 gives
only that part. File tools, notify_user attachments and shell or Python
commands in the code sandbox follow the same grants. With authorization off,
every registered data folder is open to agents: read-write, or read-only when
registered with --read-only. In OpenShell mode, sandboxes hold copies of
only the person's folder, team/ and agents/, so code there does not see
data folders at all. See Data folders for the
rules and Files and folders for levels,
requests and blocks.
tool_policy.data_folders is removed: startup refuses a configuration that
still lists folders there and names the key. Delete it and register each
folder again with /access folders add, under the same name so grants that
name data/<name> apply to it. Data folders also replace the removed
tool_policy.restrict_to_workspace switch. tool_policy.allow_web_search
and tool_policy.allow_shell_commands are removed too, because web research
is part of internet access and shell tools are given with grants, and so are
the environment variables TOOL_RESTRICT_TO_WORKSPACE, TOOL_DENY_PATHS and
TOOL_DENIED_PATHS. Startup refuses each of them by name; see
Removed settings.
Defaults and example values¶
Omitted settings follow the defaults documented in config.example.yaml,
with these exceptions:
agent.default_team_iddoes not adopt the example'steam_uaidentity. Each instance supplies its own team identity.agent.external_mcp_serversdefaults to an empty list. The example's Crawl4AI connection requires explicit configuration and review.
Memory hydration supports coremem, usermem, and domain_topic_recall, in that
default order. Configuration now rejects unsupported plugin ids in either
agent.memory.plugins.order or the plugin settings, even when an entry or the
plugin manager is disabled. Remove user_profile_summary, team_profile_summary,
long_term_profile_full, and memory_graph_retrieval from existing configurations.
They no longer have implementations and are no longer silently discarded. Stored
memories are unaffected.
The website now defaults to port 18090 for both listening and generated
links. If an existing deployment omitted its website ports and relied on the
former 18500 default, configure the desired port explicitly or update its
container and reverse-proxy routing.
instance_config.yaml¶
Gateway commands and headless launch use the onboarded instance_config.yaml.
It owns durable non-secret settings such as:
- Message broker, server URLs, credentials, stream settings, and team id.
- Gateway request timeout and delivery policy.
- Manager and gateway storage backend choices.
- The instance root, from which every folder is derived.
- Tool settings that are not access, such as
tool_policy.scratch_retention_daysandtool_policy.output_retention_days(see Saved tool output retention). - How long chat uploads are kept (
attachments.retention_daysof the internal website; see Upload retention). - LLM and embedding defaults.
- Activity collector bind/base URL settings.
- Voice settings.
- Interactive app enablement and allowlists.
- Shared website host settings for docs, skills, and generated sites.
- Secure broker mode, bind settings, and credential-state directory.
- Deterministic execution profiles, controller policy, artifact paths, Kubernetes placement, and pinned SSH targets.
- Reviewed GitHub skill-installation scanner and quarantine limits.
instance_root is the only location setting. agent.workspace_dir and the
former per-file location settings (for example workspace.skills_dir,
workspace.llm_override_path, the website sites_dir, and the MCP folders
mcp.registry_dir, mcp.hosting.definitions_dir and mcp.hosting.state_dir)
were removed; see Instance Folders.
One saved file, and when changes take effect¶
Every process reads the saved instance_config.yaml in the instance root.
The gateway's settings pages and configuration editor save settings there;
TeamLead saves model overrides in control/LLM_OVERRIDES.yaml. A change takes effect as
it says: "takes effect now" at once, "at each running agent's next turn" when
that agent starts its next piece of work (model settings for other agent types
or the team's default model), "after a manager restart" (or gateway, or
team-wide) after that in-app restart, with no container restart. On an in-app
restart the launcher recomputes the environment variables it derived from the
saved file. It keeps the variables you set yourself (environment, team.env,
Docker secrets): such a variable, for example LLM_MODEL_ID, keeps overriding
the saved setting until you remove it. The Docker bundle adds its own NATS and
PostgreSQL details in memory and never writes them to the file.
Concurrent settings saves never overwrite a file changed since they read it.
If a save or backup restore asks you to reload, the newer settings were kept;
reload and reapply your edit. Open configuration editors from an earlier
version must reload before saving. Stop runtime writers before hand-editing
instance_config.yaml outside the browser, since external editors do not
share the application's file lock.
Model overrides need no restart. A change explicitly targeting TeamLead's own
type applies to it immediately. Changes to another type or the workspace default
reach affected running agents at their next turn, including TeamLead when it
inherits the default. New agents read them at startup. In an agent-type override,
omit a field to inherit its default; set an optional field to null to clear it.
For example, reasoning_summary: null disables an inherited summary even when
the entry does not name a provider or model. This applies with failover on or off.
Time zone¶
user.timezone (an IANA name such as America/Chicago, asked during
onboarding) is the instance time zone:
- The launcher sets
TZto it for itself and every process it starts, so log times and local clocks use it. ATZyou set in the container's environment overrides it for all of them. An unknown name makes the C library fall back to UTC without an error, so check the launcher'sevent=process_timezoneline. - Requests without a person's own time zone, and cron schedules the runtime
creates without a person, use it (
DEFAULT_REQUEST_TIMEZONEoverrides it for those). A person's own schedules run in the time zone of their profile; see Time zones.
team.env¶
launch.secrets_source in instance_config.yaml (or in a base
config.yaml, as the starting value for onboarding) says where secrets come
from:
env_file(default): onboarding writes secrets and generated internal credentials toteam.env(launch.env_file_path), and the launcher reads it.environment: secrets come only from environment variables and Docker secrets (<NAME>_FILE). Onboarding writes noteam.env, generates nothing, and lists any required secret the environment lacks; the launcher reads no env file and warns once if ateam.envis still present.launch.env_file_pathmust then be empty. See Secrets from the Environment.
With env_file, use team.env for secrets and generated internal credentials
(model keys are saved with /auth model instead; see below):
POSTGRES_DSN=
TELEGRAM_BOT_TOKEN=
DISCORD_BOT_TOKEN=
TWILIO_ACCOUNT_SID=
TWILIO_AUTH_TOKEN=
TWILIO_WHATSAPP_FROM=
SECURE_TOOL_BROKER_TOKEN=
ACTIVITY_COLLECTOR_USER_TOKEN=
ACTIVITY_COLLECTOR_ADMIN_TOKEN=
SECURE_TOOL_BROKER_TOKEN is the secure tool broker's secret. The supervisor
gives the broker that value and every other process its own token made from
it, so the broker knows which process is calling; the broker never accepts the
plain value. A gateway or agent started by hand makes its own token at start. The internal credentials step also writes the
task-context signing keys (ACCESS_GATEWAY_SIGNING_KEY,
ACCESS_SCHEDULER_SIGNING_KEY, ACCESS_CONTEXT_VERIFY_KEYS), which sign the
record of whom each task works for. Do not edit them. The signing keys can also
come from Docker secrets (ACCESS_GATEWAY_SIGNING_KEY_FILE,
ACCESS_SCHEDULER_SIGNING_KEY_FILE); the supervisor derives the verification
keys from them. See
Tool access and account links.
Every secret can also come from a Docker secret file: set <NAME>_FILE to the
mounted file instead of setting <NAME>. A secret file beats a team.env
value. Docker lists the supported
names.
See Model Providers for the complete provider matrix.
For ChatGPT/Codex OAuth-backed model access, see
OpenAI Codex OAuth for file-backed Codex CLI and Docker
token setup.
For xAI account OAuth-backed Grok access, see
xAI Grok OAuth. Device login writes rotating credentials
to an instance-owned auth store rather than team.env or YAML.
When the external adapter host is enabled, also set
ADAPTER_HOST_AUTH_TOKEN (or ADAPTER_HOST_AUTH_TOKEN_FILE) to a random value
of at least 32 characters. Keep the value out of YAML.
Public URLs and Reverse Proxies¶
network.public_origin is the shared browser-facing scheme and hostname for
the website and secure broker. It cannot contain a path. The service-specific
public ports control whether generated links append a port:
interactive_apps.plugins.builtin.internal_website.settings.public_port: nulluses the public origin as-is for Web Chat, docs, assets, and generated sites.security_layer.broker_public_port: nulluses the same origin for generated/auth/...,/credential-collection/..., and/account-link/...broker links.- Bind ports remain the private listener ports used by Docker or a reverse proxy and do not need to match public ports.
An explicit null is different from omitting either public-port field. Omission
uses that service's default public port, while null keeps the shared origin
unchanged. Generated instance and bundled runtime configs preserve this
distinction.
For Traefik routing, Docker Swarm labels, first-onboarding behavior, and the supported public broker route split, see Reverse Proxy and Docker Swarm.
Storage¶
Independent instances must use separate PostgreSQL schemas or databases. Separate instance folders do not isolate records kept in the same schema.
Storage can be SQLite or Postgres. Postgres-backed instances should keep DSNs in
team.env or process env instead of instance_config.yaml.
Check:
.venv/bin/python assistant_cli.py chat \
--config <instance_root>/instance_config.yaml \
--env <instance_root>/team.env
If storage fails, inspect POSTGRES_DSN, STORAGE_BACKEND, and any configured
manager or gateway storage blocks.
Moving memories to a new instance¶
To move a whole team (settings, people, access, schedules, credentials and pinned memory) to a new version, use the team transfer instead: Moving a team to a new version. The commands below move only pinned memories, and also read instances older than the team transfer.
assistant_cli.py memory export and memory import copy pinned memories from
an old instance to a new one: the team's memory (coremem, the facts every
agent sees) and each person's memory (usermem). The learned memory graph is
not included; the new instance builds its own. Both work on SQLite or
PostgreSQL.
You run both commands with the new version. The export only reads the old instance, and the old instance may run an earlier version:
- It needs only the old database. Name it with
--sqlite <path>or--postgres-dsn-file <file holding the connection string>, or give the old--config <instance_config.yaml or config.yaml>and the export finds the database the way the old version did. Earlier versions kept it at<old root>/workspace/dbs/task_history.db; this version keeps it at<root>/dbs/task_history.db. The export looks in both places and stops if it finds none or both. - It reads nothing else from the old configuration except the instance name, so settings this version removed do not matter.
- The team id comes from the stored team memory. If the database holds team
memory for several teams, the export asks for
--team-id. A name or team id it cannot tell is written as null in the file;--instance-namesets the name. - It never changes the old database, so a read-only copy or mount works, and the old instance can keep running. Facts added after the export are not moved, so stop the old instance first if people still use it.
- With no choice flags it exports the team's memory and every person's;
--team,--person <id>(repeatable) or--all-peoplenarrow it. People removed from the team are left out, because their memories are held only until deletion. Earlier versions did not record removed people, so everyone is exported from them.
With Docker¶
- Before you stop the old instance, list its people: an administrator sends
/user listin chat. Note each person's id (for exampleusr_old123). - Onboard and start the new instance on its own data volume, sign everyone in
once, and list its people the same way with
/user list. Starting the new gateway also records its people, which the import checks ids against. - Export with the new image, with the old data volume mounted read-only at
/oldand the new one at/data. Point--configat the oldinstance_config.yaml(in a subfolder if the old container usedTEAM_INSTANCE_ROOT). The configuration records paths under/data; the export reads them under/old.
docker run --rm --entrypoint python \
-v <old-data>:/old:ro -v <new-data>:/data \
<new-image> -m assistant_cli memory export \
--config /old/instance_config.yaml --out /data/memories.json
For PostgreSQL, give the connection string as a file and run the container on a network that reaches the old database server (for example the old Compose network):
docker run --rm --entrypoint python --network <old-network> \
-v <new-data>:/data -v <secrets>/postgres_dsn:/run/secrets/postgres_dsn:ro \
<new-image> -m assistant_cli memory export \
--postgres-dsn-file /run/secrets/postgres_dsn --out /data/memories.json
The export prints the database it read, the team id and how many facts it
wrote for each person id.
4. Check the import in the new container with --dry-run, which changes
nothing. Map each old person id to the new one with --map-person OLD=NEW
(repeatable); a person whose id is the same in both instances needs no
mapping.
docker exec <new-container> python -m assistant_cli memory import \
--config /data/instance_config.yaml --in /data/memories.json \
--map-person usr_old123=usr_new456 --dry-run
- Run the same command without
--dry-run, then delete the file:docker exec <new-container> rm /data/memories.json.
python -m assistant_cli works whether or not the image keeps its Python
source files. --entrypoint python is needed for docker run because the
image's entrypoint accepts only run, onboard and onboard-web.
Without Docker¶
.venv/bin/python assistant_cli.py memory export \
--config <old_root>/instance_config.yaml --out memories.json
.venv/bin/python assistant_cli.py memory import \
--config <new_root>/instance_config.yaml --in memories.json \
--map-person usr_old123=usr_new456 --dry-run
Then run the import again without --dry-run. If the old configuration cannot
be used, name the database instead, for example
memory export --sqlite <old_root>/workspace/dbs/task_history.db --out memories.json.
Rules the import follows:
- People. Person ids differ between instances.
--map-person OLD=NEW(repeatable) says whose memory each old person's becomes. A person without a mapping keeps the same id only if the new instance's people records list them and they were not removed. Otherwise their facts are refused and listed. Mapped ids are checked against those records once the new gateway has started. - Team. The team memory goes to the new instance's team, or to
--team-id <team>. - Repeats. A fact whose text is already in the same memory for the same owner is skipped, so running the import again is safe.
- Limits. The new instance's limits apply (
agent.memory.coremem.max_facts_per_team,agent.memory.usermem.max_facts_per_userand the tag and metadata limits). Facts that do not fit are reported, not dropped silently. Facts whose end time has passed are skipped. - History. Each imported fact is recorded as created by the memory import,
with the original author and creation time kept in its metadata under
imported_from.
The import prints counts per team and person and lists every fact it did not import with the reason. It exits with status 1 when any fact was refused or did not fit.
The export file is JSON (format: universal-agents-pinned-memory,
schema_version: 1). It holds the old instance's name and team id (null when
unknown) and each fact's text, tags, metadata, start and end times, author and
times, and its person id for personal facts. It holds no
secrets and no conversation, task or chat ids from the old instance. It does
hold people's memories, so it is written readable only by you and never over an
existing file: keep it private and delete it after the import.
Message Broker¶
The manager, gateway, and spawned agents communicate through NATS with JetStream-backed delivery where configured. Verify:
NATS_URLorNATS_SERVERSpoints to reachable NATS servers.NATS_USERandNATS_PASSWORD, orNATS_CREDENTIALS_FILE, match the server.- The managed local NATS server always requires a user and password. Values
you set in
NATS_USER/NATS_PASSWORD(directly, inteam.env, or through*_FILEsecrets) are used unchanged. When you leaveNATS_USERandNATS_PASSWORDunset, the first start generates them and stores them in<nats service root>/auth/credentials.json(readable only by the service owner; default/data/services/nats/auth). Later starts andscripts/reconcile_nats_consumers.pyreuse that file. The password reachesnats-serverthrough a private configuration file, not its command line. Delete the file only while every runtime process is stopped. - The configured JetStream stream exists or the runtime is allowed to create and reconcile it.
- Bundle mode runs the bundled NATS service unless explicitly configured for an external NATS deployment.
Process-scoped consumers use this crash-cleanup delay:
transport:
process_consumer_inactive_threshold_seconds: 300
Generated agent mailboxes are deleted during clean shutdown and expire after
this delay when a process crashes. Explicit agent.agent_id mailboxes, team
lead routes, named-worker queues, and gateway routes remain persistent. The
runtime requires NATS Server 2.10 or newer for the consumer ownership metadata;
the bundled image includes a newer pinned release.
Every durable consumer is a pull consumer: an agent asks for its next message
when it can act on it. Workers of one type share one queue and ask for a task
only while they are free, so a busy worker never holds tasks another worker
could run. Upgrading from a release that used push consumers replaces them on
the first start (each replacement is logged as nats_consumer_replaced);
messages still in the stream are kept and delivered by the new consumers.
Worker pools¶
Delegated tasks wait in their worker type's shared queue until a free worker takes one. The runtime starts workers while tasks wait and no worker is free, up to each type's pool size, and workers leave again after their idle time. One pool size per type covers delegated and scheduled work.
agent:
worker_pools:
enabled: true # Start workers automatically for waiting delegated tasks.
default_max_workers_per_type: 4 # Pool size until TeamArchitect sets another.
max_workers_per_type_ceiling: 16 # Most workers of one type; TeamArchitect cannot go above it.
max_total_workers_per_team: 32 # Most workers of the team, however they were started.
max_launches_per_type_per_hour: 60
scale_up_wait_seconds: 20 # A task waiting this long with no free worker starts another.
TeamArchitect sets pool sizes itself inside the ceilings, for a while or for
good, when it reviews a pool at its limit, a model provider that keeps refusing
calls, or workers that cannot start. Administrators get an Inbox notice of each
change and of problems that keep coming back. Only an operator changes the
ceilings. The full list of settings, with comments, is in config.example.yaml.
Upgrading moves agent.schedule_workers.max_total_workers_per_team and
max_launches_per_type_per_hour to agent.worker_pools when they were changed
from their defaults, and drops max_auto_workers_per_type,
max_auto_workers_per_team and agent.delegation_assurance; the configuration
upgrade step does this automatically (instance configuration version 11,
config.yaml version 9). Finish in-flight delegated work before upgrading: the
earlier release's pickup checks are not carried over.
Deterministic execution¶
execution_control configures immutable code jobs and managed services. The
controller stores source, build, revision, occurrence, lease, and service state
outside the agent process. Use a manager schedule for work that needs reasoning.
Use an execution job for fixed Python or single-file Rust code.
An OpenShell profile names the exact sandbox and toolchain. A Kubernetes profile
must specify a runtime image pinned by sha256 digest, artifact helper, namespace,
service account, and artifact PVC. If the program writes state that must survive
pod replacement, configure a different kubernetes_workload_pvc_name. The
container receives that volume at UA_DATA_DIR=/ua/data; it never receives
write access to promoted artifacts.
For Kubernetes deployments, mount <instance_root>/state/execution_artifacts
on the controller so it refers to the same bytes as the profile's artifact PVC.
Set execution_control.kubernetes.network_policy_enforced: true only after the
namespace enforces the universal-agents.io/network labels.
SSH is disabled by default. Each execution_control.ssh.targets item pins the
host, port, username, host-key algorithm and fingerprint, the id of its key
material (credential_binding_id), identity file, and known-hosts file. Keep key files outside workspaces/.
An optional remote_persistent_session_name uses remote tmux for explicit
reattachment after a local broker restart.
Execution revisions accept non-secret environment entries only. Names beginning
with UA_ are reserved. A revision that names credentials
(broker_capability_binding_ids) is refused, because secret injection into
deterministic workloads is not installed.
With authorization on, the execution controller checks access with the same
Cedar evaluator and access store as the agents (authorization.cedar_binary_path
and the manager storage). Each job, service and SSH session records who allowed
it; see Features for who
decides what. A profile with backend: local runs code on the controller host
outside any sandbox, so a job on it also needs the job's agent type and person
to hold lasting full access to code:unconfined, checked when the job is
turned on and before every run
(Shell and Python code).
Jobs, services and SSH sessions saved before access model 2 name approvals from
the removed permission store. The controller refuses to start while any remain
(reason_code=old_execution_records_present). With Universal Agents stopped, run
assistant_cli.py execution-retire-old-records --config <instance_config.yaml>.
It disables those jobs, sets those services to stopped (the controller stops their
workloads when it starts) and makes those SSH sessions unusable. Turn jobs on
again and restart services through TeamLead; a service needs a new approval.
LLM and Embeddings¶
Non-secret model defaults belong in config:
llm.providerllm.model_id- provider-specific non-secret settings under
llm.openai_codexandllm.xai_oauth - OpenAI API-compatible base URL used by
llm.provider: litellm - embedding provider/model/api-base/dimensions
Model keys never go in config. Administrators save every model key (the
OpenAI-compatible endpoint, the embedding service, OpenAI, Anthropic, Gemini
and xAI) with /auth model,
which tests each key before storing it in the secure broker; agents use a
saved key on their next request, without a restart. These environment
variables override a saved key while they are set, and /auth model shows
when they do:
LITELLM_API_KEY=
EMBEDDING_API_KEY=
OPENAI_API_KEY=
GEMINI_API_KEY=
ANTHROPIC_API_KEY=
XAI_API_KEY=
See Model Keys.
Fresh onboarding uses OpenRouter at https://openrouter.ai/api/v1 and
pre-fills DeepSeek V4.1 Flash as deepseek/deepseek-v4.1-flash. In Universal Agents,
llm.provider: litellm is equivalent to selecting the OpenAI API-compatible
runtime path; a separate LiteLLM proxy is optional, not required.
Cross-provider model failover is disabled by default and starts with an empty
fallback list. Configure llm.failover.fallbacks and explicitly set
llm.failover.enabled: true only when automatic switching is appropriate for
the instance. Explicit model changes in control/LLM_OVERRIDES.yaml
supersede any active failover lease.
For llm.provider: xai-oauth, omit llm.model_id to use grok-4.5 and run
assistant_cli.py xai-oauth-login --config <instance_config.yaml> to populate
the instance-owned auth store. XAI_OAUTH_ACCESS_TOKEN and its _FILE form
are ephemeral overrides; XAI_API_KEY belongs to API-key workflows and is not
accepted by the OAuth provider.
If graph memory is enabled, startup fails closed when the configured embedding profile drifts from the active persisted graph profile.
Access workflows¶
Access workflows are the plans the team lead publishes before it asks for access; you follow them on the workflow page. Two settings bound them:
access_workflows.max_steps(default 32, at most 64): the most steps one plan may have.access_workflows.diagnostic_event_limit(default 1000, 20 to 10000): the most events a diagnostic download keeps. It says when older events were left out.
These settings used to be human_interactions.workflow_max_steps and
human_interactions.workflow_diagnostic_event_limit. The human_interactions
block is removed; move the two values to the access_workflows block and
delete the rest (see
Removed settings).
Authorization¶
Access control decides which agent may use which tool, for which person. How
it works (levels, grants, requests in the Inbox, blocks) is described in
Access and approval. Four settings remain, in both
config.yaml and instance_config.yaml:
authorization:
enabled: true # false runs trusted single-person mode
cedar_binary_path: null # null finds ua-cedar-authorizer
starter_profile: trusted # trusted, careful or manual
presentation:
mode: friendly # friendly or technical
authorization.enabled (default true) turns access control on. With
false, Universal Agents runs in trusted single-person mode: every tool is
available without a grant, agents do not get the access tools, and nothing
waits in the Inbox. Platform changes, such as bounded runtime settings, new
specialists, team skills, and the new web API tools and data folders of an
access proposal, apply after the person agrees in the conversation. The signed record of whom a task works for, the secure
broker's checks, account links, the code sandbox, protected folders, and each
component's own checks still apply.
authorization.cedar_binary_path names the Cedar evaluator program. Agents,
the secure broker, the gateway and the execution controller all use it. With
null (the default), Universal Agents looks for ua-cedar-authorizer on
PATH and then in the Cargo build folder (target/release, then
target/debug); the Docker image includes it. The Cedar policies and schema
ship in ua_definitions/access/cedar/ and are not configurable. When the
evaluator fails or reports an error, the operation is refused.
authorization.starter_profile chooses TeamLead's standing access for the
first user's work (the instance's user) when authorization is on: trusted
(default; full access to the standard tool set, handed on to workers without
asking, with a notice each time), careful (read access, handed on; changes
need approval) or manual (nothing). It is that user's default: the gateway
applies it at start, as that user, until they choose a profile themselves in
chat, on the Access page or with assistant_cli.py access starter-profile.
Until then, changing the setting replaces the grants the earlier profile made
at the next start; after that their own choice stays. It does not apply to anyone else: every other person
chooses their own with /access profile or on the Access page, and until they
do, every access for their work is asked for. See
How agents get access.
authorization.presentation.mode controls how much detail a refused or failed
action shows in Web Chat, such as an Access page button or an MCP control.
friendly (default) shows a plain-language explanation and the next step.
technical adds a stable error code, the HTTP-style status, the operation, and
the failure type. Internal exception text is never shown in either mode. The
setting applies to the whole instance after the gateway restarts and does not
change any access decision.
The settings of the earlier permission system (authorization.engine,
fail_closed, policy_path, schema_path, cedar_request_timeout_seconds,
user_approval, admin_elevation, emergency_deny, permission_delegation,
shell_command_profiles, and the top-level human_interactions block) are
removed. Startup refuses a configuration that still contains any of them and
names each one; delete them. See
Removed settings for what replaces each.
workspace.skill_installation controls the TeamArchitect-only reviewed install
pipeline. enabled exposes the workflow; scanner_executable names the
operator-owned SkillSpector binary (the supported Docker and native installers
put their isolated locked scanner on PATH); scanner_timeout_seconds limits
one static scan; safe_max_score may only narrow SkillSpector's LOW/SAFE band
from 20; plan_ttl_seconds (default one day, at most one day) is how long a
scanned plan waits for approval; and
max_repository_bytes caps the quarantined checkout. The selected skill has
separate 500-file, 20 MiB total, and 5 MiB per-file limits in the trusted
acquisition boundary.
semantic_review.mode defaults to "off", so local checks finish without
extra model configuration. Set it to "task_model" to add semantic assessment
using the model selected for the calling task, including a person's own model
and its existing broker-managed authentication. Do not supply a key in these
settings or expose one to the scanner. Configure an existing provider with
/auth model or /auth model me when needed. This setting authorizes submitting
the quarantined skill contents to that selected model; a local model stays local.
semantic_review.max_input_bytes defaults to 262144 and accepts 1024-1048576.
It bounds the complete UTF-8 request, including metadata. Selected assessment
refuses binary content, exceeded bounds, partial coverage and provider failures
rather than truncating or silently dropping back to local-only review. It also
refuses when the task that staged the skill has no model or stops before the
review ends; only mode: "off" finishes on the local checks alone. MEDIUM
or higher semantic findings also prevent a plan. Both the result and settings
are bound to the approved snapshot: approval checks the report again against
the settings in force, so changing these settings means staging the skill
again. Existing pending installation plans must be re-staged after this
update; already installed attested skills remain valid.
workspace:
skill_installation:
semantic_review:
mode: "task_model"
max_input_bytes: 262144
When a selected review does not pass, no installation is proposed. The lead
tells you the reason and what to do, the report shows that the local checks
passed, and the log line event=skill_semantic_review_refused names the
change id, skill, reason and model (never file contents or keys). The reasons:
task_model_unavailableorturn_finished: the review needs the running task that staged the skill. Stage it again from a running task; if no model is found again, check the agent's model settings.input_too_large: the skill is larger thanmax_input_bytes. Raisemax_input_bytes(up to 1 MiB), or use a smaller skill.input_too_large_for_model: the skill fitsmax_input_bytesbut not the model's context window, so raisingmax_input_bytesdoes not help. Use a model with a larger context window for this agent, or lowermax_input_bytesso such skills are refused before any model call.model_key_refusedormodel_key_rejected: the task may not use a model key, or the provider refused it. The refusal says who saves a working key with/auth modelor/auth model me.model_timed_out,model_unreachableormodel_busy: the provider did not answer. Try again later; check the endpoint if it continues.model_did_not_finish: the model stopped early, at its output token limit or at the provider's content filter. Raise the model's output token limit, or use a smaller skill.model_output_invalid,incomplete_file_coverageorfinding_outside_reviewed_files: the model's answer could not be used. Try again, or choose a model that follows structured output well.non_text_content: the skill holds a binary file; remove it.input_changedorartifact_changed: a file changed during the review; stage the skill again.findings: the model found a MEDIUM or higher risk, so the skill cannot be installed as it is.model_call_failed: any other failure; the log names the error type.
Team skills belong to the team. With authorization on, TeamArchitect applies
a scanned plan with apply_change: a person approves each install, replacement
or removal in the Inbox, unless an administrator granted TeamArchitect full
access to fn:team_skills (for example assistant_cli.py access grant --to
agent-type:TeamArchitect --tool fn:team_skills --level full); then it applies
changes itself and administrators get a notice for each one. With
authorization off, the person's agreement in chat applies the plan.
TeamArchitect can also propose a new or changed team skill from a draft
folder an agent wrote in its task's folders (plan_team_skill_change). The
draft goes through the same quarantine, scan, and approval; replacing an
installed skill shows the added, removed, and changed files and keeps the old
version recoverable. Agents can read installed skills but never write them.
workspace.external_skill_repositories remains an operator-owned startup
refresh channel into control/skills. Each value is a credential-free public
GitHub repository; the importer discovers skills under directories named
skills at any depth. These trusted startup snapshots are distinct from an
agent-requested installation, which always uses quarantine, SkillSpector, and
the reviewed install workflow.
MCP¶
An installed MCP server is one tool, mcp:<name>, and agents use it when they
hold access to it (see MCP permissions). Each
MCP operation needs full access until an administrator confirms a lower level,
so full access to the server covers every operation; see
Access levels.
mcp.enabled: true enables the secure-broker MCP control/data plane. All
onboarded agent.external_mcp_servers and top-level mcp_profiles are desired
state, not authorization grants: the runtime reconciles them into the
secret-free registry at <instance_root>/runtime/mcp-connections before an
agent starts. The folder is fixed; it is not a setting.
The one-time v4-to-v5 upgrade records the exact existing static baseline;
subsequent new or changed definitions wait for review in Settings before any
DNS or protocol traffic. With authorization off, each agent loads the active
servers meant for it: servers from its own configuration
(agent.external_mcp_servers, or agent_types.<type>.agent.external_mcp_servers
when its type has its own list, plus any profiles it was started with), and
servers that TeamArchitect installed or that run as managed services whose
definition names its type. With it on, an agent loads a server only while it
holds access to it, and approving a pending server in Settings gives the types
it names that access for everyone's work. In both modes agents load servers
before each step, not when they start: a server approved or installed while an
agent runs is available on its next step, and a server that does not answer
never stops an agent from starting.
An MCP definition cannot run from an ad hoc agent configuration that lacks a persisted instance configuration and installed registry. That path fails closed; initialize the instance and approve the reconciled definition instead.
Use Streamable HTTP for new servers. mcp.legacy_sse.enabled retains the rare
SSE compatibility path until its 2026-11-12 removal review. Loopback and
private-network targets are denied unless the matching mcp.network_policy
exception is explicitly enabled. Prefer an exact
mcp.network_policy.allowed_private_hosts entry for an approved internal DNS
name over the broad allow_private_networks switch. Exact-host exceptions
still reject loopback, link-local, reserved, multicast, and other hostnames,
and the resolved address remains pinned for the connection. The bundled
Docker configuration allows only crawl4ai this way. Do not put secrets in
MCP registry or hosted settings; use an environment reference or an account
link, described below.
Static operator configuration may use environment references such as
Authorization: "Bearer ${DOCS_SEARCH_TOKEN}". The secret-free reference is
included in the installed definition digest, while its value is materialized
only from the secure broker process environment immediately before the
transport is constructed. Missing or empty references fail closed and identify
the variable name without logging its value. A reference ${NAME} can also
be filled from a Docker secret file named by NAME_FILE; a missing or
unreadable file fails closed the same way.
A connection can instead use a credential from the credential store. Declare
where each credential field goes with credential_injections:
agent:
external_mcp_servers:
- name: "docs_search"
transport: "streamable_http"
server_url_env: "DOCS_SEARCH_MCP_SERVER_URL"
tool_name_prefix: "docs_search"
credential_injections:
- target_kind: header # header for HTTP servers, env for stdio servers
target_name: Authorization
field_name: api_token # the stored credential's field
template: "Bearer {value}" # optional; the value alone when omitted
A connection with credential slots becomes a catalog tool
(mcp:<connection_name>) that needs an account link. A team owner or
administrator links the team's account with /link mcp:docs_search team, or
TeamArchitect asks for a link when the broker reports that none exists. For a
call, the broker uses the link of the person the task works for first, then
the team's while the team shares the server (see
Shared or private; listing the server's
tools, which happens once without a person, uses the link of the person who
proposed it, then the team's); it fills the
slots when it connects, keeps one session per link, and removes any configured
header of the same name. No token is copied into chat or configuration. See
Account links. Changing a server's
configuration changes its definition, so it waits for approval again.
After a link is created, the server's tools load on each allowed agent's next
step. When the broker refuses to list a server's tools (no access, no account
linked yet), an agent does not keep asking: it tries again when access changes
(such as a new account link), when the server's definition changes, or when
the agent restarts. When a server does not answer, an agent tries again after
1, 2, 4, 8 and 16 minutes, then every 30 minutes, for up to
mcp.load_retry_window_minutes (60 by default, 1 to 10080). Then it stops and
administrators get an Inbox notice naming the server, since when it has not
answered, and the last error; there is one notice per server per day, however
many agents gave up. Check that the server is running, then update or
reinstall it in Settings; agents try again when it changes or when they
restart. Agents see why a server's tools are missing (load_status in
find_tools and mcp_connections(action="list")) and can tell you. An active
inventory record describes installation, not a successful connection. An
OpenShell credential lease does not authorize MCP access. Removing the account
link stops further use of the credential, including through cached
connections.
An external_mcp_servers entry no longer takes continue_on_error: a server
that does not answer never stops an agent from starting. The runtime refuses
a configuration that still has it and names the entry. Deleting the key
changes the server's definition, so the server waits for approval in Settings
again.
mcp.hosting.enabled permits trusted data-only hosted definitions. The
definitions and state directories, local bind host, and reserved port range are
operator-owned. Agent proposals cannot contain code, imports, packages,
commands, executables, endpoints, or credentials. Hosted publication is a
separate high-impact authority and remains closed when no trusted ingress and
authentication profile is configured.
Agent Definitions¶
Core agent definitions live under ua_definitions/agent_definitions/.
Additional shipped roles live in startup-loaded bundles under
ua_definitions/agent_bundles/, and remain available by default.
To add your own agent roles, place catalog files or bundle directories under the team control folder:
control/
agent_bundles/
custom_roles/
agent.yaml
prompts/
custom_role.md
You can also list extra files or directories under
agent.agent_definition_paths; relative paths resolve under control/.
Validate definitions before restart:
.venv/bin/python scripts/validate_agent_catalog.py --config config.yaml
Agent YAML lists the tools a type works with under default_tools, as tool
catalog ids or tool set ids (ua_definitions/agent_definitions/builtins.yaml
has examples); it cannot import arbitrary Python tools. With authorization on,
default_tools only tell TeamLead what to give a new type, and the agent's
tools follow the access it holds; with it off, they are the agent's tools. The
removed fields tool_capabilities and capability_registry_ids are refused
when a definition loads. Runtime/model overrides for a type still belong under
agent_types.<AgentType> in config.
TeamArchitect-managed composition lives in control/TEAM_AGENTS.yaml. It
records generated agent bundle location, startup-agent overrides, and ephemeral
child-agent TTL policy. Generated definitions are ordinary bundles under
control/agent_bundles/team_lead_generated/ and are validated
through the same catalog loader, which reads them each time a type is listed or
started. A new generated type is available to the running manager as soon as it
is created, with no restart; startup roster overrides apply the next time the
headless supervisor launches.
TeamArchitect creates or removes a specialist by staging an exact plan and
calling apply_change. With authorization enabled, a person approves that plan
in the Inbox; with it off, the person agrees in the conversation.
If the plan or its task ended before the approval, TeamArchitect stages a fresh
plan. Approving a specialist never gives it access to tools or lets it publish
anything; its tool calls are checked like any other agent's (see
How agents get access).
Secure Broker¶
The secure tool broker always runs: every credentialed tool call (web research
tools, GitHub, Google, Hugging Face, X and MCP servers) goes through it, so
there is no setting that turns it off. security_layer.mode is broker (the
default) or openshell, which also runs agent commands in an OpenShell sandbox.
Startup refuses the removed security_layer.mode: disabled,
security_layer.secure_cli_enabled and SECURE_CLI_ENABLED with a message
that names them; delete them. Keep security_layer.broker_internal_base_url
reachable from agent/gateway processes. Browser-facing auth and credential form
links derive from network.public_origin plus
security_layer.broker_public_port. In Docker, this commonly means:
network:
public_origin: http://127.0.0.1
security_layer:
broker_internal_base_url: http://127.0.0.1:18600
broker_public_port: 18600
broker_bind_host: 0.0.0.0
broker_bind_port: 18600
credential_catalog:
enabled: true
database_path: credential_catalog.db
template_overrides_path: credential_template_overrides.yaml
default_write_source: bitwarden
openshell_binding_ttl_seconds: 900
collection_session_ttl_seconds: 900
For broker-only credentials, prefer:
SECURE_TOOL_BROKER_ENV_FILE=/data/broker.env
and put BW_SESSION_FILE, OP_SERVICE_ACCOUNT_TOKEN_FILE,
KEEPASSXC_DATABASE, KEEPASSXC_PASSWORD_FILE, VAULT_ADDR,
VAULT_TOKEN_FILE and GOG_KEYRING_PASSWORD_FILE in that separate file. The
broker maps CLI state such as GH_CONFIG_DIR, Bitwarden app data, and
OP_CONFIG_DIR under broker_credentials/, one folder per person.
GitHub, Google, Hugging Face and X tokens are not configuration: each person
signs in with /link cli:github, /link cli:google and /link cli:x; an
administrator stores the team's sign-in apps with /auth google team_client and
/auth x team_client; Hugging Face uses account links (/link cli:huggingface,
with team for the team's account); and X falls back to the team's linked X
account (/link cli:x team) only after an administrator shares X with
/accounts share cli:x (see Shared or private).
Startup stops while a removed token variable (GH_TOKEN,
GITHUB_TOKEN, GH_ENTERPRISE_TOKEN, GITHUB_ENTERPRISE_TOKEN,
GOG_CLIENT_SECRET, GOG_REFRESH_TOKEN, GOOGLE_OAUTH_ACCESS_TOKEN,
GOOGLE_OAUTH_REFRESH_TOKEN, GOG_TOKEN_FILE, HF_TOKEN,
GOOGLE_APPLICATION_CREDENTIALS and the other old Google file variables, or
their _FILE forms) is set. Google tools run with each person's own sign-in
(/link cli:google), never a service-account key file.
Tool setup checks¶
The runtime remembers, for each person and each tool that acts with an account, whether it last worked (and how: signed in, or which account is linked) or what it still needs, so TeamLead does not check the setup every time it uses a tool. Every call of the tool keeps this up to date. For a tool that is set up but nobody used for a while, the broker checks again now and then:
security_layer:
tool_setup_recheck_days: 30 # 0 turns the re-check off
Every tool_setup_recheck_days days (default 30) since a person last used or
checked a tool, the broker re-checks it with the same read-only checks as
TeamLead's setup check. For GitHub (gh auth status) and Google (a token check
with Google) this asks the service itself; for X it checks that the sign-in is
stored (X checks it when an agent posts), and for other tools that an account
is linked (the credential is checked when it is used). When a tool that
worked needs setting up again, the person gets one Inbox notice saying what to
do, such as "Your Google sign-in no longer works. Run /link cli:google, or ask
TeamLead to walk you through it." People who are disabled or removed are
skipped. Restart the broker after changing the setting.
The credential catalog defaults to <instance_root>/credential_catalog.db.
The one-time import of an old credential_bindings.yaml catalog has been
removed: startup stops while security_layer.credential_catalog.path,
security_layer.credential_catalog.legacy_owner_canonical_user_id,
SECURE_TOOL_BROKER_CREDENTIAL_CATALOG_PATH or
SECURE_TOOL_BROKER_LEGACY_OWNER_CANONICAL_USER_ID is set. Delete them.
The catalog stores names, purposes, usernames/emails, and password-manager source refs
for newly collected workflow credentials. Passwords and tokens are submitted
through broker forms and stay in the configured credential store. Which tool
uses a credential, and where the broker puts its values, is an
account link, not part of the saved credential.
Agent web requests through the broker (secure_requests and
credential.api_request) reach only hosts that a
web API tool covers. The broker adds the
linked credential and refuses credential_key parameters and ${VAR}
placeholders. In OpenShell mode, credential.bind_for_openshell takes a
tool_id and gives the environment-variable (env) entries of that tool's
account link, for openshell_binding_ttl_seconds, to the sandbox of the person
the task works for; the broker picks that sandbox itself and refuses any
other. A link without
env entries is refused (account_link_has_no_environment); add env
entries to the tool definition and link the account again.
Credential onboarding templates help agents create the right broker form for a
service. Built-in templates live in ua_definitions/credential_templates/builtins.yaml;
approved agent-customized variants default to
<instance_root>/credential_template_overrides.yaml; see
ua_definitions/credential_templates/credential_template_overrides.example.yaml for a
non-secret override example. Existing bootstrap env or Docker-secret
credentials are registered by user-named env var, not copied into the catalog.
To store reusable broker auth payloads in Vault or Bitwarden instead of long-lived broker files, configure:
security_layer:
credential_state_backend:
mode: credential_source
source: vault # or bitwarden
namespace: agent-credential-store
fallback_to_files: false
This currently covers GitHub token auth, GitHub browser-auth token mirroring,
and Google gog token/client JSON imports or web-auth exports. For Bitwarden,
the broker uses stable item names such as
agent-credential-store :: github :: token and requires broker-side bw to
already be authenticated/unlocked.
With Sealbox, a missing tenant means the owner has no stored record. Reads
create no tenant; the first authorized write creates it. Existing-tenant
authentication, missing or damaged key files and other storage errors stop
the operation, even with fallback_to_files: true. File fallback can supply
an absent record, but cannot repair a Sealbox failure.
Code Execution Sandbox¶
The python_env tool gives each request its own default environment when the
agent omits env_name. Helpers working on that request share it. Every
scheduled run gets a separate default too. Trusted maintenance removes the
whole default environment after 7 days without use, keeping it intact while
a tool call is running. Save lasting results outside default environments.
For a reusable script or a schedule that needs earlier code, give the
environment a name explicitly. Named environments stay until deleted;
the earlier shared environment remains available by the name default.
This choice remains in effect if the original request later omits the name.
Cleanup skips busy environments and checks them on a later maintenance run,
so running Python code does not delay other scheduled work.
Agents with shell or python_env run every command in a Linux Landlock
sandbox unless security_layer.mode is openshell (see
OpenShell mode). What one command can reach follows the
access of the agent and of the person it works for, worked out again for each
command (Shell and Python code). A
sandboxed command can:
- read and write the task's folders: the person's own folder (the default
working folder) and the shared
workspaces/teamandworkspaces/agentsfolders; - read or write data folders, folders the agent was given for this person's work, and what other people shared with the person, as far as the grants and shares allow: read-write where the agent and the person may write, read-only where they may only read;
- read and write a private temporary
HOME/TMPDIRthat is deleted after the command; - read operating-system and Python interpreter files, and the team's skill folders (to run a skill's bundled scripts);
- use any extra paths you list outside the instance root.
Landlock can only add access, never take part of a folder away, so a folder with a blocked folder inside it is left out of the command entirely; the command result's sandbox note says so, and file tools still reach the rest.
It cannot read team.env, the instance configuration, control files,
credential files, databases, runtime records, other people's folders, or other
processes' memory and environment. The runtime sets SKILLS_DIR to
control/skills for each command.
Environment variables that name a path outside these areas (for example a
GIT_CONFIG_GLOBAL in your home directory) are removed for the command.
Commands may create links in the folders they can write (Python environments
need them); file tools, attachments and the gateway never follow those links.
Network. A command can open TCP connections and listen on a port when the
agent and its person hold internet access,
which every agent and person has until someone blocks it. The level on the
code tool does not matter for the network; installing packages with
python_env needs write on code:python and internet access. When internet
access is blocked, the sandbox closes TCP, which needs Landlock ABI 4 (Linux
6.7 or later). On an older kernel such a command is refused, with a message
saying so, rather than run with the network open; commands with internet
access still run. Landlock does not cover UDP, so commands can still send UDP
traffic such as DNS lookups. Internal services therefore still require
credentials that sandboxed code cannot read. With authorization off, the
network is open.
security_layer:
code_execution:
sandbox: required # or "off"
extra_read_paths: [] # absolute paths code may read
extra_write_paths: [] # absolute paths code may read and write
required refuses to run a command when the sandbox cannot be applied. Landlock
needs Linux 5.13 or later with Landlock enabled and a container security profile
that allows its system calls (Docker's default profile does); in Docker Desktop
and Colima, the kernel is the one in their Linux virtual machine. off runs
every agent command with the runtime's full filesystem access and an open
network, and logs event=code_sandbox_disabled; use it only when every agent
with code execution is fully trusted. With authorization off it is the only way
to run agent code outside the sandbox. With authorization on, one command runs
outside the sandbox when a person approved full access to code:unconfined
for that agent (Shell and Python code);
each such command is logged with event=code_unconfined_run. Extra paths must
be outside the instance root; the runtime refuses to grant any directory inside
or containing the instance root, and any directory containing the broker
credentials directory.
Command-line tools the team installed through an access proposal
(Command-line tools) always run in
this sandbox on the secure broker's host, whatever sandbox says here, and
without the extra paths: they reach only system folders and their own private
run folder. On a broker host without Landlock they are refused
(event=installed_cli_sandbox_unavailable); the built-in tools are not
affected.
With authorization on, an agent sees shell and python_env only while it
holds access to code:shell or code:python for the person it works for now.
With authorization off, the agent types whose definitions list those tools
among their default tools get them.
OpenShell mode¶
With security_layer.mode: openshell, commands run in
OpenShell sandboxes instead of Landlock.
Each person gets their own sandbox, created the first time their code runs and
holding copies of only their folder and the shared team/ and agents/
folders. Work that runs for no person uses a shared sandbox with the two shared
folders. Because OpenShell copies files in rather than sharing a folder with
the host, one sandbox for everyone would have given each person a copy of
everyone else's folder.
security_layer:
mode: openshell
openshell:
sandbox_name: null # name prefix; null uses team-<instance name>
policy_file: null # the OpenShell policy each sandbox gets
create_if_missing: true # false: you create each sandbox yourself
delete_on_shutdown: false # true: delete this instance's sandboxes at stop
upload_workspace: true # copy the folders in when a sandbox is created
- Sandboxes are named
<prefix>-p-<part of the person's folder name>-<short hash>, and<prefix>-sharedfor work with no person; the prefix is lowercased and cut to 24 characters. Withcreate_if_missing: false, create each sandbox under that name first, or commands for that person are refused. - Files are copied in once, when a sandbox is created. Files written on the host later are not in it, and files code writes inside the sandbox stay there; the file tools on the host do not see them.
- The OpenShell policy file decides the network and everything else a sandbox can reach. Folder grants, data folders and the network rule above do not apply to OpenShell sandboxes, and the skill folders are not copied in.
delete_on_shutdown: truedeletes every sandbox whose name starts with the prefix when Universal Agents stops.- A command approved to run outside the sandbox (
code:unconfined) runs on the host, not in OpenShell.
Activity Collector¶
The activity collector needs user and admin tokens in env. Verify:
ACTIVITY_COLLECTOR_USER_TOKENis present.ACTIVITY_COLLECTOR_ADMIN_TOKENis present.activity_collector.base_urlis reachable by manager and spawned agents.- The collector process starts in logs.
API clients send the matching token in an Authorization: Bearer ... header.
Dashboard pages use the browser's sign-in prompt. Enter user or admin as
the username and that dashboard's token as the password. Tokens in URL query
parameters are refused, so they do not enter browser history or URL logs.
The Compose example publishes the secure broker's port on loopback only. Access from another machine needs an explicitly configured authenticated HTTPS proxy. Keep the broker's internal address reachable by the runtime processes.
Voice¶
Voice settings live under voice. Grok voice uses the xAI key: save it with
/auth model (provider xAI; onboarding does this for the key you type), or
set XAI_API_KEY, which overrides the saved key. Voice in a separate adapter
host process reads only XAI_API_KEY, because that process has no broker
access.
Voice is disabled when voice.enabled: false. Inbound speech-to-text and
outbound text-to-speech are controlled separately.
Website Host and Generated Sites¶
The shared website app serves user docs, generated skill docs, generated article, comparison, how-to, app, and work report sites, plus embedded generated-site chat. The default settings are:
interactive_apps:
plugins:
builtin.internal_website:
settings:
enabled: true
bind_host: 0.0.0.0
bind_port: 18090
public_port: 18090
docs_root: null
skills_dir: null
Use base_url for the browser-reachable URL. A generated page is written into
sites/<site_id>/ of the folder of the person it was made for, and a record of
it (which folder, whose, and the SHA-256 of each file) is kept in
state/published_sites/<site_id>.json. The website serves a page only through
its record and only while its files still match; see
Generated Sites.
External Adapter Host¶
Channel plugins may select execution: adapter_host under their registry entry.
Enable interactive_apps.adapter_host at the same time. Same-host deployments
should use the default permission-restricted Unix socket. Cross-container or
remote deployments must use mutual TLS and configure both the gateway listener
(bind_host/bind_port) and the host connection address (connect_host). The
TLS client certificate identity must match host_id exactly.
The internal Website/Web Chat entry must remain execution: in_process. See
Interactive App Plugins for registration,
acknowledgement, reconnect, queue, attachment, and health behavior.
Verification Checklist¶
assistant_cli.py chatworks with--configand--env./docsreturns a browser docs URL./auth statusreturns broker status when broker mode is enabled./docs/sites/opens the generated-site index when the website app is enabled; it lists your pages when you are signed in to Web Chat in the same browser.- Enabled channels start cleanly and receive a test message.
- Proactive delivery goes to the intended default channel.
- Secrets are absent from
instance_config.yamland workspace files. assistant_cli.py execution-job-listreturns the team-scoped job inventory.- Kubernetes profiles can read promoted code but only a separate data PVC is writable by the workload.
Bounded Objective execution¶
Long-running Objectives can use explicitly activated, resumable work sessions without changing normal task execution. The capability and its built-in policy are available by default:
workspace:
objective_execution_enabled: true
objective_execution_paths:
- "builtin://objective-execution/default"
This loads the profiles but does not time-box any Objective. An Objective becomes
bounded only after you explicitly accept the manager's suggestion or ask it to
enable a named profile in an authenticated request. Each run must activate the
packaged long-horizon-plan-execution skill; skill authorization is still
enforced. Set objective_execution_enabled: false to remove the capability
globally. A TeamArchitect restart is required after changing these main-config
fields; activating another Objective does not require a restart.
If the built-in profiles do not fit, discuss the intended cadence, material-work allowance, and all total and checkpoint-reserved budgets with TeamArchitect. It can stage an immutable custom-profile proposal within the operator envelope. The proposal is inert until you accept its exact id and digest in an authenticated request. Choose either:
- an
objectiveprofile, applied once to one active Objective; or - a
reusableprofile, installed in your private TeamArchitect profile catalog for selection on future Objectives.
Installing a reusable profile does not activate any Objective. Removing it prevents future selection but leaves already accepted Objective policies unchanged because every policy stores a profile snapshot. Profile replacement and Objective reconfiguration reject state drift and require a fresh proposal if the target changed after the proposal was staged. Reconfiguration updates the existing protected schedule rather than creating a second recurring job.
Objective execution policies are strict schema-v2 YAML layers. Configure one or more in an ordered list; later layers add profiles, replace same-named profiles, and override only the policy fields they declare:
workspace:
objective_execution_paths:
- "builtin://objective-execution/default"
- "objective_execution_profiles/nightly.yaml"
- "objective_execution_profiles/high-context.yaml"
Relative paths resolve under control/. A referenced file that is
absent emits an objective_execution_policy_file_missing warning and is skipped,
so the manager can continue with the remaining layers. A malformed or invalid
file fails startup rather than silently weakening bounds. If no configured file
is available, the manager still starts but bounded Objective execution is
unavailable. Changes to this list or any loaded layer require a manager restart.
The former singular objective_execution_path field is removed; replace it with
an array before upgrading to current config.yaml schema 7 or
instance_config.yaml schema 9.
Ask TeamArchitect to render a profile with
objective_work_profiles(action="export"). With explicit confirmation it can save an
inert layer under objective_execution_profiles/; the tool cannot edit the main
config, activate the layer, or restart the manager. Add the returned relative
path to objective_execution_paths when you want that YAML profile to become an
operator-loaded profile.
Each profile contains its cron cadence and cumulative work-session budgets.
The cadence runs in cadence_timezone: owner (the default) is the time zone
of the person who owns the Objective, else the instance time zone; any IANA
name such as Europe/Berlin fixes it.
No profile budget resets per model turn. active_seconds is the total
wall-clock window for one session. turns counts model cycles across the
session. total_tokens accumulates input plus output tokens across those
cycles, including repeated prompt and tool-schema input. tool_calls counts
all tool calls across the session. The checkpoint fields reserve subsets of
those totals, and the runtime withholds them from material work. If a safe boundary is reached
without a checkpoint, it uses the reserve for a narrow checkpoint-only model
invocation and falls back to a deterministic degraded checkpoint only if that
pass cannot persist the handoff. Input, output, total, and cache token usage are
stored separately for tuning. Suggestion rules, the required skill list,
default-profile selection, activity snapshot emission, and checkpoint retention
are policy-wide rather than per-profile.
The same policy file owns custom_profiles; these controls are deliberately
separate from the main runtime config. The built-in envelope enables one-time
and reusable proposals, keeps them acceptable for 86400s (24h), requires at
least 3600s (60min) between scheduled runs, and allows 50 installed profiles
per user and TeamArchitect. Agent-authored budgets are bounded as follows:
| Budget | Accounting scope | Minimum | Maximum |
|---|---|---|---|
| Active duration | Total wall-clock window per session | 300s (5min) |
28800s (8h) |
| Wall-clock checkpoint reserve | Subset of the session window | 60s (1min) |
3600s (60min) |
| Model cycles | Cumulative count per session | 2 |
200 |
| Checkpoint-reserved cycles | Subset of session cycles | 1 |
20 |
| Input plus output tokens | Cumulative total per session | 25000 |
3000000 |
| Checkpoint-reserved tokens | Subset of session tokens | 10000 |
500000 |
| Tool calls | Cumulative total per session, not per turn | 2 |
500 |
| Checkpoint-reserved tool calls | Subset of session tool calls | 1 |
5 |
Each reserve must be smaller than its corresponding total. Operators can tune these fields in a later Objective execution policy layer without changing the ordinary task-execution defaults. The built-in profiles are:
| Profile | Cadence | Session time total / reserve | Session turns total / reserve | Session token total / reserve | Session tool-call total / reserve |
|---|---|---|---|---|---|
nightly |
0 9 * * * (09:00 UTC daily) |
1800s (30min) / 300s (5min) |
30 / 2 |
1500000 / 150000 |
150 / 5 |
deep |
0 10 * * * (10:00 UTC daily) |
5400s (90min) / 300s (5min) |
50 / 3 |
3000000 / 250000 |
300 / 5 |
After a limit_* stop, objective_work_sessions(action="status") reports the binding
dimension, work-token overshoot, average tokens per turn, and input/output ratio.
TeamArchitect may use those observations to propose a complete replacement
profile, but it cannot apply wider bounds without the same exact user acceptance
flow.
agent.max_tool_calls_per_task defaults to 150 cumulative calls across one
ordinary task-processing invocation. It is not a per-turn allowance.
An accepted Objective work profile is separate: its tool_calls total is the
authoritative session limit, while checkpoint_reserve_tool_calls holds at most
five attempts for the checkpoint-only record_objective_work_checkpoint pass.
The reserve does not fund research, shell, delegation, or other material work.
Objective, Plan, and bounded-session ownership survives TeamArchitect process
replacement. The durable owner is the same-team TeamArchitect role, represented
as manager_scope:<team>:TeamArchitect, rather than one process id. Startup
atomically adopts older rows from a prior same-team TeamArchitect process. It
does not transfer work across teams, roles, or canonical users. Protected
schedules already claim that team and role, so the replacement TeamArchitect
can fire and resume them without bypassing the schedule authorization boundary.
Authenticated Objective list/control also performs a targeted same-user,
same-team adoption for legacy rows whose old team metadata is absent. This is
observable and collision-safe; it never widens canonical-user, team, or named
role authority. If multiple legacy snapshots map to the same durable record,
reconciliation keeps the uniquely newest snapshot by updated_at and then
created_at, and archives each superseded snapshot in
durable_owner_scope_reconciliation_archive before removing it. An existing
durable record takes precedence. Equally fresh snapshots with different
payloads remain an error so startup cannot silently choose between ambiguous
workflow histories.
Profiles intentionally do not select a model, team, tools, credentials,
authorization, storage, Objective goals, Plan subgoals, or evaluation criteria.
Those remain controlled by their existing runtime, security, and Objective
configuration surfaces. Web Chat's Runtime Controls page reads current
Objective state and allowed mutations from the live manager, while Activity
Collector user/admin pages remain read-only history and telemetry projections.
Runtime Controls shows the current goal, Plan subgoals, progress, linked
schedules, work-policy status, and available lifecycle actions. Activity
Collector projections can additionally show the selected profile and its
configured, installed, or one_time source, session budgets, next run, and
recent checkpoints. TeamArchitect's objective_work_profiles(action="list") tool shows
the authenticated user's installed catalog and proposal history; those private
proposal records are not projected into the team-wide activity stream.
The built-in nightly profile allows 1,800 seconds (30 minutes), reserves 300
seconds (5 minutes) for checkpointing, and permits 1,500,000 cumulative input
and output tokens. The deep profile allows 5,400 seconds (90 minutes), reserves
300 seconds (5 minutes), and permits 3,000,000 cumulative tokens. Token usage
includes the system prompt, tool schemas, repeated model-cycle context, and
generated output. A TeamArchitect with a large tool set can therefore consume
tens of thousands of tokens before doing material work. Keep enough token
headroom for the final checkpoint. The runtime finishes an active model or tool
operation before applying a boundary, so actual usage can exceed a configured
limit by the cost of that final operation.