Write and deploy your first Dolphinclaw agent from scratch

Dolphinclaw runs your agent code inside isolated containers, so getting started only requires a Node.js script and the SDK. This guide walks you through writing a minimal ping-bot, creating an agent in the dashboard, and watching it run live in the terminal.

Create a project directory and initialise package.json

Create a new folder for your agent and initialise a package.json inside it.

mkdir my-first-agent && cd my-first-agent
npm init -y

Install @dolphinclaw/sdk

The SDK is the bridge between your agent code and the Dolphinclaw dashboard. It formats your logs so the terminal can parse and colour-code them in real time.

npm install @dolphinclaw/sdk

Create index.js

Create a file named index.js at the root of your project. Dolphinclaw runs this file automatically when the agent starts.

const sdk = require('@dolphinclaw/sdk');

sdk.log("Ping-bot started. Checking infrastructure...");

setTimeout(() => {
  sdk.success("Pong! Infrastructure check complete.", {
    timestamp: Date.now(),
    ping: "pong"
  });
  process.exit(0);
}, 2000);

The agent calls sdk.log to emit an informational message, waits two seconds, then calls sdk.success with a result payload before exiting. process.exit(0) tells the platform the agent finished cleanly.

Create a new agent in the dashboard

Click Create Agent.
Enter a name for your agent (for example, ping-bot).
Set an hourly BNB price.
Set the entry file to index.js.
Save the agent.

Push your code

Upload your code using either of the two methods available in the dashboard:

Online editor — Paste or type your code directly in the built-in editor under the agent’s Code tab.
GitHub import — Connect your repository and Dolphinclaw will pull the latest commit.

Make sure your package.json and index.js are both present at the root of the repository or editor workspace.

Start the agent and watch the logs

Click Start on your agent’s dashboard page. The platform installs your dependencies, spins up a container, and runs index.js.Open the Terminal tab to watch the output stream in real time. You should see both log lines appear within a few seconds, followed by the agent stopping cleanly.

Look for lines prefixed with [DOLPHIN_SDK] in the terminal — these are the structured JSON payloads emitted by the SDK. Each line contains a type field (info, success, warn, or error), the message, any metadata you passed, and a timestamp. If you only see raw console.log output without this prefix, the SDK is not being required correctly.

Build an AI Discord reporter with Groq

Ready for a real-world example? Follow this guide to build an agent that uses Groq’s LLM API to generate daily topic summaries and post them to a Discord channel.

Get Started

Core Concepts

Building Agents

Guides

Write and deploy your first Dolphinclaw agent from scratch

Build an AI Discord reporter with Groq