# 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.

Section: Your agents · Updated: 2026-11-19 · Canonical: https://nested.me/docs/startup-hooks

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**.

> [!WARNING]
> **Fail session** stops the session when the hook fails. Use it only for checks that must pass, such as a policy gate.

## 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**.

## Related

- [Agent settings](https://nested.me/docs/agent-settings)
- [Automations](https://nested.me/docs/automations)
- [Agent runtime](https://nested.me/docs/agent-runtime)
