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

# Handle SIGTERM for graceful Dolphinclaw agent shutdown

> Learn how to catch the SIGTERM signal in your agent, use the 10-second grace period to clean up, and safely exit long-running loops and connections.

When you stop a running agent — either manually from the dashboard or through the API — the DolphinClaw platform sends a `SIGTERM` signal to your agent's process. By listening for this signal, your agent can finish in-progress work, close external connections, flush pending data, and log a clean final status before the container exits. Without a handler, the process may be terminated mid-operation, leaving connections open or data in an inconsistent state.

## The grace period

After sending `SIGTERM`, the platform waits **10 seconds** for your process to exit on its own. If your agent is still running after 10 seconds, the container is forcibly killed. Use this window to perform any cleanup that matters — flushing writes, closing database connections, sending a final log line — and then call `process.exit(0)`.

## Basic SIGTERM handler

Register the handler once at the top level of your entry file, outside any function:

```javascript theme={null}
process.on('SIGTERM', () => {
  sdk.log('SIGTERM received. Cleaning up...');
  // cleanup logic
  process.exit(0);
});
```

Replace the comment with whatever your agent needs to do before exiting. Call `process.exit(0)` explicitly once cleanup is complete so the container shuts down immediately without waiting out the full grace period.

## Recommendations for long-running agents

Agents that run continuous loops or maintain persistent external connections need a shutdown strategy:

<Steps>
  <Step title="Set a shutdown flag">
    Declare a boolean variable (e.g. `let isShuttingDown = false`) and set it to `true` inside the `SIGTERM` handler. Check this flag in your loop condition so the loop exits cleanly on the next iteration.

    ```javascript theme={null}
    let isShuttingDown = false;

    const interval = setInterval(() => {
      if (isShuttingDown) return;
      sdk.log('Running scheduled task...');
      // task logic
    }, 5000);

    process.on('SIGTERM', () => {
      sdk.log('SIGTERM received. Cleaning up...');
      isShuttingDown = true;
      clearInterval(interval);
      process.exit(0);
    });
    ```
  </Step>

  <Step title="Close external connections">
    If your agent holds open database connections, HTTP keep-alive sockets, or WebSocket connections, close them inside the handler before calling `process.exit(0)`.
  </Step>

  <Step title="Flush pending SDK logs">
    Call `sdk.log` or `sdk.success` with a final status message so the dashboard shows a clear shutdown record rather than an abrupt cutoff in the log stream.
  </Step>
</Steps>

<Tip>
  For short one-shot agents that do a single task and exit, a SIGTERM handler is optional — the process finishes before a stop signal is likely to arrive. For any agent that runs a `setInterval` loop, holds open connections, or is designed to run continuously, a SIGTERM handler is critical to avoid leaving orphaned resources or corrupted state.
</Tip>