Startup and shutdown

This page describes what happens when the runtime starts, when it becomes ready, and how it shuts down cleanly.

In short

Startup follows this path:

• read the bootstrap input
• decrypt it if needed
• substitute variables and secrets
• validate and parse the bootstrap
• load each enabled deployment in priority order
• load workflow configuration
• activate timers, triggers, and listeners
• mark the agent as ready

Shutdown is the reverse goal:

• stop accepting new startup work
• cancel scheduled startup dependency waits
• ask loaded deployments to shut down
• let running work finish where possible
• close resources

Variable and secret substitution

Variable and secret substitution happens while the bootstrap is being read, before it is validated or parsed.

This means:

• the runtime first reads the raw bootstrap text
• if the bootstrap is encrypted, it is decrypted first
• placeholders are then resolved from environment variables and configured secrets
• validation runs on the substituted result
• if a placeholder cannot be resolved and no default is provided, startup fails

This substitution step applies to the bootstrap itself, not to workflow content loaded later.

Startup sequence

1. The runtime starts and checks whether legal acceptance has already been provided.
2. It reads the bootstrap from the command line, environment, or a file.
3. If the bootstrap is encrypted, it is decrypted before further processing.
4. Variable and secret substitution is applied.
5. The bootstrap is validated and split into enabled deployments.
6. Deployments are ordered by startup priority.
7. Each deployment is loaded into memory and its runtime resources are prepared.
8. Workflow configuration loading begins.
9. When the workflow has been loaded, startup activation runs in stages:
   • one-time startup tasks
   • startup tasks that prepare timers and listeners
   • final activation
10. Once those stages complete, the deployment is considered ready.
11. After all deployments finish, the agent marks itself initialized and reports that it is ready.

If a deployment depends on another deployment, the dependent deployment waits until the required deployment is ready before completing its own startup activation.

Shutdown sequence

Shutdown can happen at any time, including during startup.

When shutdown begins:

• the runtime stops scheduling new startup work
• pending startup dependency waits are cancelled
• already loaded deployments are notified
• in-flight work is allowed to settle where possible
• shutdown and pre-shutdown hooks run
• client and licensing resources are closed

If shutdown begins before startup completes, the agent stops waiting for configuration or dependency readiness and exits without reporting readiness.

What “Ready” means

A deployment is ready when:

• its workflow configuration has been loaded
• its startup activation has completed
• its timers and listeners have started
• any required post-startup initialization has been run

Some work can begin before the global Agent Ready point.

In particular, a deployment may start work earlier through:

• runOnce startup tasks
• scheduled timers

The agent is ready only after every enabled deployment has reached its ready state and the global startup sequence has completed.