Skip to main content
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: 
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:
1

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.
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);
});
2

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).
3

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