Skip to content
Browse the docs

Startup tasks and lifecycle hooks

Run messages every time an agent starts, and call shell scripts or HTTP endpoints before and after each session or prompt with lifecycle hooks.

Updated 1 min readView as Markdown

Two advanced settings let an owner run work around an agent’s life. Startup tasks send messages each time the agent process starts. Lifecycle hooks run a shell script or an HTTP callback at session and prompt boundaries.

Before you start#

  • Own the agent and open its settings → Advanced.

Startup tasks#

Use startup tasks to warm an agent up: clone a repository, refresh a cache, or check that its tools work.

  1. Open Startup tasks and select Add task.
  2. Enter a unique Display name and the Message, a markdown prompt sent to the agent on startup.
  3. Choose the Run mode: Background (non-blocking) or Foreground (blocking).
  4. Order tasks with Move up and Move down, then select Save tasks.

Changes apply on the next restart of the agent’s pod. All startup tasks together must stay under 256 KiB. Tasks they create appear in the task list under the Startup kind.

Lifecycle hooks#

  1. Open Lifecycle hooks and select Add hook stage.
  2. Pick the Stage: Before session, After session, Before prompt, or After prompt.
  3. Pick the Type. A Shell script runs inside the agent’s sandbox, with optional environment variables (KEY=value, one per line). An HTTP callback calls an HTTP URL with an HTTP method and optional headers (Header: Value, one per line).
  4. Set On failure to Continue session or Fail session, and an optional Timeout such as 30s or 5m.
  5. Select Save hooks.

Example#

Add a foreground startup task named “Sync repo” with the message “Pull the latest main branch of acme/app and run the test suite once.” Add an After prompt HTTP callback to your audit service with Continue session on failure.

Questions

When do startup task changes take effect?
On the next restart of the agent’s pod, for example after Save & redeploy or a Stop and Start.