Redeploying Existing Agents

Both golem and golem-cli can be used — all commands below work with either binary.

Overview

Redeploying an agent means deleting it and recreating it with the same name and stored per-agent environment and local configuration overrides, but using the currently deployed component version. Defaults come from that component, so effective environment variables and configuration can change. Unlike an in-place update, redeployment destroys the agent’s execution state, including its operation log (oplog) and internal WASM state. Guest key-value storage is scoped by environment, bucket, and key, not by the agent lifecycle: redeploy and reset do not clear it. Clean up application KV data separately when a fully clean start is required.

Use redeployment when:

• The agent’s persisted state is incompatible with the new component version and cannot be migrated via snapshot-based updates.
• You want to force a clean start for all agents without manually deleting and recreating them one by one.
• During iterative development when preserving agent state is not important.

If you need to preserve agent state across component version changes, use update (--update-agents) instead — see the golem-update-running-agents guide.

Method 1: Redeploy During Deploy

The simplest approach — pass --redeploy-agents to golem deploy:

golem deploy --yes --redeploy-agents

This applies deployment changes, if any, and then processes existing durable agents across all components in the resulting deployment, including unchanged components. Redeployment also runs when there is no deployment diff. Ephemeral agents are not enumerated for redeployment.

1. Lists the durable agents of each deployed component.
2. Deletes each agent (destroying its oplog and stored state).
3. Recreates each agent with the same name and stored per-agent environment and local configuration overrides, using the currently deployed component and its defaults.

Comparison with Other Post-Deploy Flags

These flags are mutually exclusive — only one can be used at a time; the CLI rejects combining them.

Unlike --redeploy-agents, --reset does not recreate agents; they are created again on invocation. It does not clear domains, HTTP and MCP deployments, secrets, retry policies, plugins, or component revision history. The deployment still reconciles the manifest and can update these resources. Reset also permits incompatible component configuration changes and replacement of incompatible agent secrets.

Method 2: Environment-Level Default

You can configure --redeploy-agents as the default behavior for an environment in the application manifest (golem.yaml). This is useful during development so you don’t have to pass the flag every time:

environments:
  local:
    cli:
      redeployAgents: true

With this configuration, every golem deploy targeting the local environment will automatically redeploy agents. Passing --update-agents, --redeploy-agents, or --reset on the command line overrides this setting.

What Gets Preserved

When to Use Redeploy vs. Update vs. Reset

Example Workflow

# 1. Make code changes to your component
 
# 2. Deploy and redeploy all agents
golem deploy --yes --redeploy-agents
 
# 3. Verify agents are running with the new version
golem agent list --component-name my-component

Notes

• Redeployment requires confirmation in interactive mode. Always pass --yes to skip the prompt.
• If no agents exist for a component, the redeploy step is skipped with a warning.
• Redeployment is performed sequentially — agents are deleted and recreated one at a time.