> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dolphinclaw.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Understand the Dolphinclaw agent execution lifecycle

> Agent runs move through four stages: mounting, boot, real-time feedback, and termination with a 10-second SIGTERM grace period before forced shutdown.

When you start an agent on Dolphinclaw, the platform takes your code through a defined sequence of steps before your logic ever runs. Understanding this lifecycle helps you write agents that start cleanly, report progress in real time, and shut down gracefully without data loss.

## Lifecycle stages

<Steps>
  <Step title="Mounting">
    The platform downloads your agent's source code from its private Git repository and runs `npm install` to restore all declared dependencies. Your agent is not yet executing — this step prepares the environment.
  </Step>

  <Step title="Boot">
    A Docker container launches and executes your entry file (`index.js` by default, or a custom entrypoint you configure). From this moment, your agent logic is running and billing begins.
  </Step>

  <Step title="Real-time feedback">
    Any calls to the SDK (`sdk.log`, `sdk.success`, `sdk.error`) are streamed instantly to the dashboard terminal. You can watch your agent's activity in real time without any polling or refresh.
  </Step>

  <Step title="Termination">
    When you or a renter stops the agent, the platform sends a `SIGTERM` signal to the container. Your agent has **10 seconds** to finish in-flight work and exit cleanly. If the process has not exited after 10 seconds, the container is forcibly killed.
  </Step>
</Steps>

<Warning>
  Your agent has exactly 10 seconds after receiving `SIGTERM` to clean up and exit. Any work not completed within that window is lost. For long-running agents, listen for `SIGTERM` and flush state, close connections, or write checkpoints before calling `process.exit(0)`.
</Warning>

## Handling SIGTERM gracefully

Add a `SIGTERM` listener to your agent to perform cleanup before the container exits:

```javascript theme={null}
const sdk = require('@dolphinclaw/sdk');

// Main agent logic
setInterval(() => {
  sdk.log('Scanning market data...');
}, 5000);

// Graceful shutdown
process.on('SIGTERM', () => {
  sdk.log('SIGTERM received. Cleaning up...');
  process.exit(0);
});
```

## Real-time logs in the dashboard

The dashboard terminal displays every SDK log call the moment it is emitted. Log entries are color-coded by level so you can scan for issues at a glance:

| Level     | Method                            | When to use                          |
| :-------- | :-------------------------------- | :----------------------------------- |
| `info`    | `sdk.log(message, metadata?)`     | General status updates and progress  |
| `success` | `sdk.success(message, metadata?)` | Completed tasks or positive outcomes |
| `warn`    | `sdk.warn(message, metadata?)`    | Non-fatal issues worth noting        |
| `error`   | `sdk.error(message, metadata?)`   | Failures or caught exceptions        |

You can pass an optional data object as a second argument to any log call. It is displayed inline in the terminal alongside the message.

## Isolated execution

Each agent runs inside its own Docker container. Containers are isolated from each other and from the host system — one agent cannot read the memory, filesystem, or network state of another agent running on the same platform. This isolation is enforced by the Runner layer regardless of who owns the agents.