Agent Configuration controls an Agent's identity, selected model, exact Template and Skill versions, messaging routes, credentials, integrations, and Agent-specific instructions.
Configuration is version-aware, permission-aware, and lifecycle-aware: it pins exact published versions rather than tracking the newest, what you can edit depends on your effective Agent Permissions, and how a change is applied depends on whether the Agent is Running, Stopped, or in Error.
Overview
Open Configuration when you need to change how an existing Agent operates without creating a new Agent. You can configure:
- Agent name
- Model
- Hermes command approval
- The exact Template version
- Platform routing and access policy
- Assigned Skills and their exact versions
- Platform credentials
- Provider integrations
- Agent-owned Template overrides
You cannot change the Agent's Organization, creator, Runtime, communication platform, or Agent ID. Those are creation-time or immutable properties, described under Settings you cannot change.
Configuration map
The configuration sidebar is organized in this order.
| Section | Purpose | Primary Permission |
|---|---|---|
| Profile | Name, model, command approval, and Runtime facts | Agent update |
| Template selection | Select and pin a published shared or Agent-owned version | Agent update |
| Channels & endpoint | Configure messaging routes and platform access | Agent update |
| Skills | Add, remove, or repin Agent Skills | Agent update |
| Keys & integrations | Manage platform and provider credentials | Agent secret management |
| Agent-owned override | Draft and publish private Agent instructions | Agent update |
| Danger zone | Retire the Agent | Agent delete |
The routing-section label changes by platform.
| Platform | Section label |
|---|---|
| Slack | Channels & endpoint |
| Telegram | Chats & endpoint |
| Discord | Channels & endpoint |
| Microsoft Teams | Endpoint |
Agent General Access and direct Agent Access are managed through Share on the Agent detail page, not through Configuration. Retirement lives in Danger zone and is documented in Manage the Agent lifecycle.
Before you begin
You need:
- Access to the Organization that owns the Agent
- Access to the Agent
- Agent update permission, for ordinary configuration
- Agent secret-management permission, for credentials
- Lifecycle permission, when editing a Running Agent
- A supported model allowed by the Organization
- Any new Template and Skill versions already published
- Credentials required by newly assigned Skills
- A controlled platform location for post-change verification
| Role or Permission | Configuration authority |
|---|---|
| Agent Viewer | Read-only Agent and activity access |
| Agent Editor | Profile, Template, routing, Skills, credentials, and lifecycle |
| Agent Owner | Editor authority, plus access management and retirement |
| Organization Administrator | Implicit full authority over the Organization's Agents |
| Organization Owner | Implicit full authority over the Organization's Agents |
agent.update | Ordinary configuration |
agent.secret.manage | Platform and integration credentials |
agent.lifecycle.manage | Required when a Running Agent must restart |
agent.delete | Retirement |
Configuration permissions come from server-computed Agent Permissions, and the page displays either Editor access or Read-only access.
Individual sections can still carry stricter requirements. A user with Agent update permission but without secret-management permission cannot edit Keys & integrations.
Apply behavior
Agent Barn changes the apply action based on lifecycle state. The two actions are named differently because they do different things: Apply saves only, while Apply & Restart saves and cycles the Runtime.
| Agent state | Action | Result |
|---|---|---|
| Running | Apply & Restart | Stops the Agent, applies the change, and starts it again |
| Stopped | Apply | Saves the change and leaves the Agent Stopped |
| Error | Apply | Saves the change; select Start afterward |
Apply & Restart
For a Running Agent, Agent Barn:
- Stops the Agent.
- Attempts to capture a Runtime Log snapshot.
- Applies the configuration update.
- Starts the Agent again.
- Regenerates Runtime configuration from the updated values.
Direct Agent update is rejected while the Agent is Running, so the web application performs the stop and start around the update.
If the update fails, the UI still attempts to restart a previously Running Agent, which avoids leaving it Stopped solely because the update did not apply.
Apply while Stopped or in Error
For a Stopped Agent, Apply saves the configuration and leaves it Idle.
For an Agent in Error, Apply saves the configuration but does not clear the Error or start the Agent. Return to the Agent page and select Start after correcting the problem.
Finish or cancel the current section edit before moving to another configuration section.
Open Configuration
Open the Organization that owns the Agent. From Home, select the Agent, then select Configuration.
The page header shows the Agent name, a Runtime badge, a platform badge, the current lifecycle condition, and whether you have editor or read-only access.
- Running
- Running · edits restart the Agent
- Stopped
- Stopped
- Error
- Needs attention
When an Agent is in Error, the page also shows the reported reason where one is available, and links to its Logs for users with activity permission.
Configure the Profile
Open Profile and select Edit.
Editable identity fields
| Field | Behavior |
|---|---|
| Agent name | Changes the display name used across Agent Barn and in regenerated Runtime configuration |
| Model | Selects one of the Organization's allowed models |
| Command approval | Available for Hermes only |
Hermes command approval offers three modes:
| Mode | Behavior |
|---|---|
| Auto | Automatically approves low-risk commands |
| Manual | Requests approval before commands run |
| Off | Skips command approval prompts |
For OpenClaw, command approval is displayed as Managed by OpenClaw, and the Agent Barn approval selector is not available.
Read-only Runtime and deployment facts
Profile also displays the Runtime, communication platform, lifecycle state, and Runtime resource-management behavior. These are operational facts rather than editable fields.
The live Kubernetes deployment inventory is intentionally not editable from Configuration. Starting or stopping the Agent reconciles its managed deployment, Service, storage, Secret, and configuration.
Select Apply or Apply & Restart, depending on the Agent state.
Select a Template version
Open Template selection. The selector includes published versions from four sources.
| Source | Meaning |
|---|---|
| Built-in platform | Maintained globally by Agent Barn |
| Organization fork | An Organization-owned copy of a built-in Template |
| Organization-owned | A custom Template created by the Organization |
| Agent override | An immutable version owned by this Agent |
Search by Template name, version, Template key, or source. The active version is marked Active, and the newest version in a lineage may be marked Latest.
Review before applying
Selecting a version displays its name, exact version, source, description, update date, Markdown artifacts, and required Skills. Review the available artifacts, including Soul, Identity, User, Tools, Agents, Boot, Bootstrap, and Heartbeat.
Required Skills
A Template version cannot be applied until its required-Skill contract is satisfied. Requirements can include standalone required Skills and at-least-one-of Skill groups.
If the selected Template reports missing assignments:
- Open Skills.
- Add the required Skills.
- Provide any required credentials.
- Apply the Skill changes.
- Return to Template selection.
- Select the Template version again.
- Apply it.
Source updates
A Template can indicate that a newer platform or Organization source version is available. Source updates are explicit: Agent Barn does not automatically merge or activate them.
Selecting a newer source version repins the Agent to that complete published version. It does not mutate an existing Agent Override Draft, and it does not automatically merge Agent-owned edits.
For a Running Agent, select Apply & Restart. For a Stopped Agent, select Apply and start it later.
Configure channels and endpoints
Open the platform routing section.
Slack
| Setting | Behavior |
|---|---|
| Channel access | Open or Allowlist |
| Allowed channels | The Slack channels the Agent may use |
| Direct messages | Off, Allowlist, or Open |
| Allowed users | Users permitted under a direct-message allowlist |
| Home channel | Optional Hermes destination for scheduled or proactive delivery |
| Verbosity | Hermes Slack only; Verbose or Concise |
For production, prefer Allowlist channel access, direct messages set to Off or Allowlist, a small set of approved channels, and Concise verbosity once testing is complete. Hermes Verbose mode announces work steps; Concise mode shows final answers only.
Slack requires an explicit Agent mention in shared channels, and a fresh mention on every message, including thread replies.
Telegram
| Setting | Behavior |
|---|---|
| Group chats | Open or Allowlist |
| Allowed chats | The Telegram groups the Agent may use |
| Direct messages | Off, Allowlist, or Open |
| Allowed users | Users permitted under a direct-message allowlist |
| Home chat | Optional Hermes destination for scheduled or proactive delivery |
Use an allowlist when the bot should participate only in known groups.
Discord
| Setting | Behavior |
|---|---|
| Server access | Open or Allowlist |
| Allowed servers | The server identifiers permitted under the allowlist |
| Allowed channels | The channels the Agent may use |
| Allow all users | Permits any user inside the allowed server and channel boundary |
| Allowed users | Explicit Discord user identifiers |
| Allowed roles | Explicit Discord role identifiers |
| Alert destination | Optional channel for scheduled or proactive messages |
| Require mention | Requires an explicit mention in server channels |
Discord direct messages remain disabled. If Allow all users is off, configure at least one allowed user or role, and keep Require mention enabled unless you have a reviewed reason to allow unsolicited Agent participation.
Discord bots need Message Content Intent, and role-based restrictions also require Server Members Intent.
Microsoft Teams
The Microsoft Teams routing section displays the Agent's webhook endpoint, which you configure in the Agent's Azure Bot registration.
This section is currently read-only. Update Teams platform credentials under Keys & integrations.
Apply the routing change
For a Running Agent, select Apply & Restart. Platform access and mention configuration is regenerated when the Agent starts.
After the restart, test an allowed location with a mention, an allowed location without a mention, a disallowed location, and direct-message behavior where applicable.
Configure Skills
Open Skills and select Edit. The section shows assigned Skills, each Skill's source, its exact pinned version, its required status, its required providers, and the Skills available to add.
| Action | Behavior |
|---|---|
| Add Skill | Assigns the Skill and pins a selected or current published version |
| Change version | Repins the Agent to another existing Skill version |
| Remove optional Skill | Removes the assignment |
| Remove required Skill | Blocked while the active Template requires it |
| Add provider-dependent Skill | Requires a matching credential |
| Add Slack-dependent Skill | Available only to a Slack Agent |
Publishing a newer Skill version does not move an existing Agent's pin. Use the version selector to move deliberately between versions; repinning to an older version is the supported recovery path for a bad Skill release.
Required Skills
A Skill marked Required cannot be removed while the active Template requires it.
For a required-Skill group, the Agent must retain at least one group member. A sole remaining member is protected until another member is assigned or the Template requirement changes.
Skill credentials
When a newly added Skill requires a provider, the Skills section displays its required credential form. Depending on the provider, you can enter a per-Agent credential, attach an eligible Shared Credential, or rely on the Agent's Slack bot token, which a Slack requirement uses automatically.
A Slack-required Skill cannot be assigned to a Telegram, Discord, or Teams Agent.
Removing Skills
When removing a Skill, review its required providers. If no remaining Skill requires a provider, applying the removal can also remove that now-orphaned provider credential from the Agent.
Review Keys & integrations after changing the Skill set, then select Apply or Apply & Restart.
Configure keys and integrations
Open Keys & integrations. This section requires Agent secret-management permission.
The read-only view shows whether platform credentials are configured, the communication platform, configured integration names, whether an integration uses a Shared Credential, and credential validation results.
Platform credentials
Select Edit to replace the current platform credentials. The fields depend on the Agent platform.
| Platform | Credential fields |
|---|---|
| Slack | App-level token and bot token |
| Microsoft Teams | App ID, app password, and tenant ID |
| Telegram | Bot token |
| Discord | Bot token |
Slack app-level tokens carry the xapp- prefix, and bot tokens carry the xoxb- prefix.
Leave a platform credential field blank to keep the existing value. Entering a value replaces the existing encrypted value when the change is applied.
Integration credentials
You can add, replace, or remove a provider credential, attach an eligible Shared Credential, switch from Shared to per-Agent credentials, or validate an existing integration.
An Agent can have at most one credential for each provider, and it cannot use both a Shared Credential and a per-Agent secret for the same provider.
Supported integrations include providers such as GitHub, Jira, Confluence, Bitbucket, Google Workspace, Zoho Mail, Zoho Calendar, Firecrawl, and Pipedrive. The available providers depend on the current deployment and UI.
Validate a credential
Use Validate next to an existing integration. Validation can report the validation status, the provider identity, a validation error, or missing scopes.
A successful validation confirms provider access at that moment. It does not prove that every Skill operation is allowed.
Removing credentials
Agent Barn validates that the remaining assigned Skills retain their required providers. To remove a credential that a Skill requires:
- Remove or replace the dependent Skill.
- Apply the Skill change.
- Return to Keys & integrations.
- Remove the unused credential.
- Apply the credential change.
For a Running Agent, credential changes require Apply & Restart before the new values reach the Runtime.
Create an Agent-owned override
Use an Agent-owned override when one Agent needs private instructions that should not change the Organization's shared Template. Use a shared Template instead when several Agents should receive the same behavior.
Override lifecycle
An override reaches an Agent in six ordered steps.
- Create draft Agent Barn copies the complete active source version into a private draft
- Edit and save the draft Saving preserves the draft without changing the active configuration
- Publish an immutable Agent-owned version Publishing freezes the draft and clears the editable draft slot
- Open Template selection The published override appears alongside shared Template versions
- Select the published override version Review its artifacts and required Skills first
- Apply, or Apply & Restart Only this step activates the override on the Agent
In text: create the draft, edit and save it, publish an immutable Agent-owned version, open Template selection, select that published version, then Apply or Apply & Restart. Publishing alone does not activate the override — only the final apply does.
Create the draft
Open Agent-owned override. If no draft exists, select Create override when the Agent uses a shared Template, or Create new draft when the Agent already uses a published override.
Agent Barn copies the complete active source version into the private draft, including its metadata, Markdown artifacts, required standalone Skills, and required-Skill groups. An Agent has at most one override draft at a time.
Edit and save
You can edit the Template name, description, Soul, Identity, User, Tools, Agents, Boot, Bootstrap, Heartbeat, and required Skills.
Saving preserves the editable draft. It does not change the Agent's active configuration and does not restart it.
Draft updates use concurrency protection. If another editor changed the draft, reload it before attempting to overwrite their work.
Publish
Review the complete draft and select Publish. Publishing freezes the draft as an immutable Agent-owned version, adds it to override history, clears the editable draft slot, and leaves the active Agent configuration unchanged.
Activate the published override
- Open Template selection.
- Find the newly published Agent override version.
- Review its artifacts and required Skills.
- Select it.
- Select Apply or Apply & Restart.
Applying a published override to a Running Agent restarts the Agent. Overrides are private to one Agent, and existing source updates do not modify or merge the override draft — it remains an independent Agent-owned snapshot.
Verify the configuration
After applying a change, verify both the persisted value and the live behavior.
Configuration checks
- The intended Profile values are displayed
- The correct Template version is marked Active
- Required Skills are assigned
- Skill version pins are correct
- Platform routing shows the intended policy
- Credential metadata shows Configured
- Removed credentials no longer appear
- The Agent-owned override is active only if deliberately selected
Runtime checks
For a Running Agent, confirm:
- The Agent returns to Working
- An allowed mention receives a response
- An unmentioned shared message receives no response
- Disallowed locations remain blocked
- Direct-message behavior matches policy
- Conversations contain the test exchange
- Expected Tool calls complete successfully
- Logs contain no unresolved startup or credential error
- Model usage is attributed to the correct Agent, where cost reporting is configured
For a Stopped Agent or one in Error, return to the Agent detail page, select Start, wait for Working, then perform the controlled verification.
See Verify your Agent for the complete procedure.
Settings you cannot change
Some Agent properties are intentionally not editable.
| Property | Configuration behavior | Required approach |
|---|---|---|
| Organization | Immutable ownership boundary | Create an Agent in the target Organization |
| Creator | Immutable provenance | Cannot be reassigned |
| Runtime | Read-only after creation | Create a replacement Agent |
| Communication platform | Read-only after creation | Create a replacement Agent |
| Agent ID | Immutable identity | Create a replacement Agent |
| Published Template version | Immutable snapshot | Publish another version and repin |
| Published Skill version | Immutable snapshot | Publish another version and repin |
| Published Agent override | Immutable snapshot | Create and publish another override version |
| Live Kubernetes inventory | Managed by the Agent lifecycle | Start or Pause the Agent |
| Agent Access | Separate from Configuration | Use Share on the Agent detail page |
Troubleshooting
Apply & Restart fails
Establish which phase failed
Confirm whether the failure occurred while pausing the Agent, applying the update, or starting the Agent again. The UI attempts to restart a previously Running Agent even when the update fails.
Review:
- Whether the requested value changed
- Whether the Agent returned to Working
- The Agent error reason
- Runtime Logs
- The model allowlist
- Platform credentials
- Skill and provider requirements
Do not assume that a failed update left the Agent Stopped, or that the new value was saved.
The Agent remains Stopped after Apply
Expected when it was already Stopped
Apply saves the configuration without starting the Agent.
Return to the Agent detail page and select Start.
The Agent remains in Error after Apply
Apply does not perform an Error-to-Running transition
Apply changes the configuration but does not start the Agent.
Return to the Agent detail page and select Start. A successful Start clears the previous error.
Template Apply is disabled
Usually a missing required Skill
Check whether:
- The selected version is already Active
- You have Agent update permission
- A Running Agent also grants you lifecycle permission
- Required Skills are missing
- A required-Skill group has no selected member
- Template versions are still loading
Add the missing Skills before applying the Template.
A required Skill cannot be removed
The active Template requires it
Select another Template version whose requirements do not include the Skill, or satisfy a required-Skill group with another member before removing the current Skill.
A Skill cannot be added
Check platform support and credentials
Confirm that:
- The Skill is visible to the Organization
- The Skill supports the Agent's platform
- A Slack-only Skill is being assigned only to a Slack Agent
- Required provider credentials can be configured
- You have Agent update permission
A credential cannot be removed
A remaining Skill still requires the provider
Remove or replace the dependent Skill first, then remove the credential.
Agent Barn will not allow the resulting Agent configuration to violate current Skill provider requirements.
Stored secret values are not visible
Expected: reads return metadata only
Secret reads return metadata, not plaintext. Leave a platform field blank to keep the existing value, or enter a new value to replace it.
Agent Barn does not provide a reveal-existing-secret operation.
Credential validation fails
Check identity, scopes, and expiry
Review the provider identity, missing scopes, token expiration, repository or project or account allowlist, OAuth consent, Shared Credential ownership, and provider availability.
Correct the credential and validate it again before restarting the Agent.
Publishing an override did not change the Agent
Publishing does not activate
Publishing creates an immutable version but does not activate it.
Open Template selection, select the published Agent override version, and choose Apply or Apply & Restart.
An override draft conflicts with another edit
Drafts use optimistic concurrency
Reload the latest draft, review the other editor's changes, and apply your edits again.
Do not overwrite the newer draft without reconciling both versions.
Channels changed but behavior did not
Routing is generated at start
Routing and mention configuration is generated when the Agent starts.
For a Running Agent, use Apply & Restart. For a Stopped Agent or one in Error, Apply the change and then select Start.
After startup, verify both an allowed and a disallowed platform location.
Runtime or platform cannot be edited
Both are creation-time properties
Runtime and platform are set when the Agent is created and are read-only afterward. Configuration displays them as facts and provides no field for either.
Create a replacement Agent with the required Runtime or platform, reproduce the other required configuration, verify it, and then retire the original Agent.
Next steps
After configuring the Agent: