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

# Dolphinclaw agents: structure, code, and private storage

> Agents are self-contained Node.js scripts with a defined structure — name, description, setup, run, and return — stored in a private Git repository.

A Dolphinclaw agent is a self-contained Node.js script that the platform downloads, installs, and executes on your behalf. You define the logic; Dolphinclaw handles the infrastructure, sandboxing, and billing. Each agent lives in its own private Git repository, so your source code is never exposed to renters or other users.

## Agent structure

Every agent is a JavaScript or TypeScript. The platform reads these fields to identify, describe, and execute your agent.

| Field          | Required | Description                                                                      |
| :------------- | :------- | :------------------------------------------------------------------------------- |
| `package.json` | Yes      | package.json at the root of the project for the server to set up the environment |
| `index.js`     | Yes      | index file or another entry point chosen in the project settings                 |

## Minimal agent example

The example below shows the smallest valid agent structure. You can extend it with a `setup()` function and richer return data as your logic grows.

```typescript theme={null}
const sdk = require('@dolphinclaw/sdk');

// Logic starts immediately upon execution
sdk.log("info", "Ping-bot started. Checking infrastructure...");

// Simple ping-pong logic
setTimeout(() => {
  // Use success() to report a completed task to the dashboard
  sdk.success("Pong! Infrastructure check complete.", {
    timestamp: Date.now(),
    ping: "pong"
  });
  
  // Exit gracefully after the task is done
  process.exit(0);
}, 2000);
```

## Private Git storage

Every agent you create on Dolphinclaw is backed by a dedicated private Git repository. Your source code is encrypted and never shared with renters or other platform users. The platform reconstructs your code internally at runtime — the person renting your agent only sees its name, description, and output.

The repository also supports internal versioning, so you can manage commit history and branches directly from the dashboard without needing a local Git setup.

## Pushing code to your agent

You have two options for getting code into your agent's repository:

<CardGroup cols={2}>
  <Card title="Online editor" icon="code">
    Use the built-in **DolphinClaw Deployed Tools** editor in the dashboard to write and commit code directly in your browser. No local environment required.
  </Card>

  <Card title="GitHub import" icon="github">
    Import an existing repository from GitHub. Dolphinclaw pulls in your code and stores it in your agent's private repository.
  </Card>
</CardGroup>