Skip to Content
How-To GuidesGeneralDeploying a Golem Application with `golem deploy`

Deploying a Golem Application with golem deploy

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

Usage

golem deploy --yes

Run this from the application root directory (where the root golem.yaml is located). It automatically builds all components (with up-to-date checks), uploads them to the configured Golem server, and creates or updates the deployment. Always pass --yes to avoid interactive prompts.

What golem deploy Does

  1. Builds — automatically builds all components if needed, with proper up-to-date checks (same as golem build).
  2. Stages — compares local component artifacts with what is currently deployed on the server.
  3. Uploads — pushes new or changed component versions to the server.
  4. Deploys — activates the uploaded components so agents can be created and invoked.

Existing running agents are not affected by default — they continue running with their previous component version. Use --update-agents or --redeploy-agents to change this behavior.

Available Options

OptionDescription
--planOnly plan deployment, apply no changes
--full-diffShow the full deployment and environment setup diff instead of only changed entries
--version <VERSION>Roll the environment back to the deployment with this version label (see golem-rollback)
--revision <REVISION>Roll the environment back to the deployment with this revision (see golem-rollback)
--force-buildSkip modification-time based up-to-date checks
-u, --update-agents <MODE>Update existing agents: automatic or manual
--redeploy-agentsDelete and recreate existing agents
-r, --resetDeploy, then delete existing agents of the deployed components; their state is lost, and the environment is retained
-P, --preset <PRESET>Select custom component presets
-Y, --yesNon-interactive mode — always use this flag

Environment Selection

OptionDescription
-E, --environment <NAME>Select a Golem environment by name
-L, --localUse local environment or profile
-C, --cloudUse cloud environment or profile
--profile <PROFILE>Select a Golem profile by name

Deployment Strategies

Fresh deployment

golem deploy --yes

Builds, uploads, and activates all components. Agents are created on first invocation.

golem deploy --yes --reset

Deploys, then deletes existing agents of the deployed components, even if the deployment is already up to date. Their state is lost. Agents are created again on invocation rather than recreated by the command. Use this when iterating on code changes — without it, existing agent instances keep running with the old component version.

--reset retains the environment. 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; it does not create a new environment.

Update running agents in-place

golem deploy --yes --update-agents automatic

Updates existing agents to the new component version automatically. Suspended agents are woken up, and the command waits until the updates complete.

Preview changes without applying

golem deploy --yes --plan

Shows what would be deployed without making any changes.

Common Deployment Errors

  • Build failure: fix the build errors reported in the output — golem deploy runs the build automatically.
  • Server not reachable: ensure the Golem server is running and accessible at the configured address.
  • Port conflict: if deploying locally, make sure no other process is using the Golem server ports.
  • Version-related errors (tagPattern required, working tree dirty, version already exists): see golem-deployment-version.
Deleting an AgentDeployment Versions