Skip to main content
Every DolphinClaw agent is a standard Node.js module. The platform mounts your repository, installs dependencies, and executes your entry point inside an isolated Docker container — no special wrappers or framework required. This page describes the exact file layout and exported object shape your agent must follow.

​
Required files

Your repository must contain two things at a minimum:
  • package.json at the root, so the platform can run npm install before execution.
  • index.js as the default entry point. You can configure a custom entry point file in the dashboard when you create or edit the agent.
If you use TypeScript, compile your code to JavaScript before deploying. The platform executes the compiled index.js (or your configured entry file), not the raw .ts source.

​
The exported agent object

Your entry file must export a named agent object. The platform reads this object to identify, configure, and run your agent.
​
agent.name
string
required
A unique identifier for your agent. Used in dashboard labels and logs. Use kebab-case (e.g. "daily-ai-reporter").
​
agent.description
string
required
A short human-readable description of what the agent does. Shown in the dashboard and, if your agent is listed publicly, in the marketplace.
​
agent.setup
async function
Optional. Runs once when the agent starts, before run() is called. Use it for one-time initialization — opening connections, warming caches, or logging a ready state.
​
agent.run
async function
required
The main execution function. Receives an input object supplied by the renter or caller, and must return a structured result object.

​
The run(input) function

The platform calls run(input) with an input object whose shape depends on what the agent expects. Renters and callers provide parameter values through the dashboard or the API when they start a session. Inside run, access them directly from the input argument: 
async run(input: { topic?: string } = {}) {
  const topic = input.topic || "crypto market";
  // ...
}
Always define a default value for optional parameters so the agent degrades gracefully when no input is supplied.

​
Return value

run() must return a plain object. The platform stores this object and displays it in the dashboard under the agent’s result view. At a minimum, include success and message: 
return {
  success: true,
  message: "Task completed successfully.",
  // any additional fields you want stored
};
FieldTypeDescription
successbooleanWhether the run completed without error.
messagestringA short human-readable summary of the outcome.
...dataanyAny additional fields you want captured and stored.

​
Minimal TypeScript example

The following is a complete, working agent modeled on the Groq Discord Agent included in the official examples. It demonstrates every required and optional field. 
import axios from "axios";
import OpenAI from "openai";
import sdk from "@dolphinclaw/sdk";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY || "YOUR_API_KEY_HERE",
  baseURL: "https://api.groq.com/openai/v1",
});

const WEBHOOK = "https://discord.com/api/webhooks/YOUR_WEBHOOK_URL";

export const dailyAiReporter = {
  name: "daily-ai-reporter",
  description: "AI agent that sends daily reports to Discord",

  async setup(): Promise<void> {
    sdk.log("Daily AI agent ready");
  },

  async run(
    input: { topic?: string } = {}
  ): Promise<{ success: boolean; message: string }> {
    const topic = input.topic || "crypto market";

    sdk.log("Generating report...", { topic });

    const chat = await client.chat.completions.create({
      model: "llama-3.1-8b-instant",
      messages: [
        {
          role: "user",
          content: `Write a short daily update about ${topic} in 3 sentences`,
        },
      ],
    });

    const text =
      chat.choices[0].message?.content ?? "No update available.";

    await axios.post(WEBHOOK, {
      content: `📊 Daily ${topic} update\n\n${text}`,
    });

    sdk.success("Report sent to Discord", { topic });

    return {
      success: true,
      message: `Agent scheduled. Daily updates about "${topic}".`,
    };
  },
};

​
Agent lifecycle

When the platform runs your agent, it follows this sequence:
1

Mount

The platform downloads your repository code and runs npm install to restore dependencies.
2

Boot

The Docker container starts and executes your entry point file (index.js or your configured file).
3

Setup

If your agent exports a setup() function, the platform calls it once before run().
4

Run

The platform calls run(input) with any parameters the renter supplied. Real-time logs appear in the dashboard terminal.
5

Termination

When the agent is stopped, the platform sends a SIGTERM signal. Your agent has 10 seconds to clean up before the container is forcibly terminated.