Manage the Agent lifecycle

Open the Agent from the Organization's Home page.

A Stopped Agent shows the status Idle and a Start action. An Agent in Error shows Needs attention and the same Start action.

Select Start. The action changes to Starting… while the request is in progress.

What Start does

Agent Barn renders and reconciles the following:

• Confirms lifecycle permission
• Rejects the request if the Agent is already Running
• Loads the exact pinned Template version
• Renders Template placeholders using the Agent identity
• Confirms the configured model is still allowed by the Organization
• Decrypts the required platform and integration credentials
• Loads the Agent's pinned Skill versions
• Selects the Hermes or OpenClaw builder
• Generates a fresh ingest key
• Generates platform-routing and mention-gating configuration
• Reconciles the managed configuration, Secret, storage, Service, and Deployment
• Changes the persisted state to Running and clears a previous lifecycle error
• Emits the agent.started Domain Event

Expected: The Agent briefly displays Initializing while its pod and platform connection become ready, then Working. Continue only once it reads Working.

Starting can also enter Error when credential checks or Runtime resource creation fail.

Start from Error

Start is the recovery transition from Error. A successful Start rebuilds the Runtime resources, generates fresh Runtime and ingest configuration, changes the state to Running, and clears the previous error.

If the underlying problem remains, the Agent returns to or stays in Error.

Open a Running Agent. The page shows its Runtime health, such as Working, and a Pause action.

Select Pause. The action changes to Pausing… while Agent Barn stops the Runtime.

What Pause does

Agent Barn attempts to:

1. Capture a final Runtime Log snapshot.
2. Remove the active Runtime Deployment.
3. Remove the active generated ConfigMap and Kubernetes Secret.
4. Mark the Agent Stopped.
5. Emit the agent.stopped Domain Event.

The UI then displays the status:

Idle

What Pause preserves

Pause does not retire the Agent, and it does not release its Slack or Discord bot token for another active Agent.

Effects of Pause

While the Agent is Idle, it has no active Runtime Deployment, cannot receive or process new platform work, and does not execute scheduled Runtime work. Configuration can be applied without an automatic restart, and the Agent can be started again later.

The current Agent detail page does not provide a separate Restart button. Pause followed by Start is the manual restart path.

To restart without changing configuration:

1. Open the Agent.
2. Select Pause.
3. Wait for the status to become Idle.
4. Select Start.
5. Wait for the status to become Working.
6. Send a controlled platform verification message.

Restarting causes Agent Barn to regenerate Runtime configuration from the current persisted Agent state. It is useful after a recoverable platform outage, external credential rotation, platform permission changes, Runtime health degradation, changes outside Agent Barn that require the platform connection to be rebuilt, or a controlled maintenance window.

Restarting does not change the Runtime, platform, Template pin, Skill pins, model, or Agent Access unless you apply those supported changes separately.

What a restart refreshes

• Rendered Template files
• Generated Runtime configuration
• Platform-routing rules and mention gating
• Integration context
• The Runtime Kubernetes Secret and ConfigMap
• The Deployment
• The ingest key

Persistent Runtime storage remains associated with the Agent unless the Agent is retired.

Open the Agent and select Configuration. Agent Barn uses state-aware apply actions.

Sections that can require Apply or Apply & Restart include profile and model, Hermes command approval, Template selection, platform routing, Skills, keys and integrations, and published Agent Template Override selection.

Apply & Restart

For a Running Agent:

1. Select Edit in the relevant configuration section.
2. Make the change.
3. Select Apply & Restart.
4. Review the confirmation dialog and confirm the action.
5. Wait for the Agent to return to Working.
6. Verify the changed behavior.

Agent Barn stops the Agent before sending the update, because direct Agent configuration update is rejected while the Agent is Running.

If the update fails, the UI still attempts to start the Agent again. That prevents a failed edit from leaving a previously Running Agent stopped solely because the update did not apply, and the previous persisted configuration remains in effect.

Apply while Stopped

1. Open Configuration.
2. Edit the required section.
3. Select Apply and confirm the change.
4. Return to the Agent detail page.
5. Select Start when ready.

Apply does not automatically start an Agent that was already Stopped.

Apply while in Error

An Agent in Error is not Running, so its configuration changes use Apply rather than Apply & Restart. Correct the configuration, apply it, then select Start.

An Agent can require recovery when start-time credential validation fails, the configured model is no longer allowed, a required Runtime resource cannot be created, the Runtime image cannot be pulled, Kubernetes cannot schedule the pod, a platform connection fails, the live Runtime crashes, or an integration or Tool repeatedly fails.

Determine the persisted state

Needs attention can represent more than one situation, and the available lifecycle action tells you which one.

Recovery procedure

1. Open the Agent.
2. Read the error reason shown near the Agent header.
3. Open Logs.
4. Identify whether the failure relates to credentials, model access, Runtime resources, platform connectivity, or a Tool.
5. Open Configuration if a persisted value must change.
6. Apply the correction.
7. If the Agent is still Running, use Apply & Restart, or Pause followed by Start.
8. If the Agent is in Error or Idle, select Start.
9. Wait for Working.
10. Send a controlled platform verification message.
11. Confirm that Conversations and Tool calls are reaching Agent Barn.

Common recovery decisions

A Runtime crash is not the same as a successful Pause. It does not represent an intentional transition to Stopped.

Retirement permanently removes the Agent from active use. It requires Agent delete permission, normally available to an Agent Owner, and can be initiated from any non-deleted state.

Open Configuration → Danger zone, select Retire Agent, then review the confirmation and select Retire Agent again.

Before retiring

• Confirm that the correct Agent is selected
• Announce the shutdown to affected users
• Stop new platform work
• Review Conversations and Tool calls
• Export or record any required operational evidence
• Review costs
• Review live Logs
• Pause the Agent if a final stopped-session Log snapshot matters
• Confirm that a replacement Agent is already verified
• Confirm that the platform bot token may be released

What retirement removes

Agent Barn deletes the Agent's managed Deployment, Service, persistent volume, Kubernetes Secret, and ConfigMap, then soft-deletes the Agent record. It also:

• Attempts to block the Agent's LiteLLM key
• Releases the active Slack bot-token hash, where applicable
• Releases the active Discord bot-token hash, where applicable
• Removes the Agent from normal active-Agent views
• Prevents the configuration from being restored through the UI

Historical records may remain internally for cost attribution and related history, but the retired Agent is not available as an active or restorable Agent.

Pause before retirement

Retirement can be initiated while an Agent is Running, and it does not run the normal Pause workflow first. Pause before retiring when you need Agent Barn to attempt a final stopped-session Log snapshot.