Understand the Dolphinclaw agent execution lifecycle

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

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.

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.

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.

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.

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

Handling SIGTERM gracefully

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

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.

Get Started

Core Concepts

Building Agents

Guides

Understand the Dolphinclaw agent execution lifecycle

Lifecycle stages

Handling SIGTERM gracefully

Real-time logs in the dashboard

Isolated execution

​Lifecycle stages

​Handling SIGTERM gracefully

​Real-time logs in the dashboard

​Isolated execution

Lifecycle stages

Handling SIGTERM gracefully

Real-time logs in the dashboard

Isolated execution