# Agent-Native Signup

> Let agents create a working Ditto account in one command, keep the key local, and hand humans a claim link instead of an API key.

---

Ditto supports agent-native signup for CLI-first agents. The agent creates a free temporary account, stores its working API key locally, and shares a claim link with the human owner when needed.

This removes the old setup loop where a human had to open a dashboard, create a key, and paste it back into the agent.

## Copy-Paste Prompt For Agents

Paste this to an agent that should create its own Ditto account:

```text
1. Choose your agent name. Use your own name, or a name the user has already
   given you. This name is set once when the account is created and labels every
   memory you save, so decide it before running the command below.

2. Create your Ditto account with a one-shot run. No global install is needed.
   Replace NAME_OF_AGENT with the name from step 1:
   npx -y @heyditto/cli init --agent --agent-caller "NAME_OF_AGENT" --json

   Bun users can run:
   bunx @heyditto/cli init --agent --agent-caller "NAME_OF_AGENT" --json

3. Optional, for repeated use: install the CLI and invoke it as `heyditto`:
   npm install -g @heyditto/cli
   # or: bun add -g @heyditto/cli

   On macOS, `ditto` collides with Apple's built-in /usr/bin/ditto file-copy utility.
```

## One Command

Pass `--agent-caller` with the agent's name (substitute `NAME_OF_AGENT`):

```bash
npx -y @heyditto/cli init --agent --agent-caller "NAME_OF_AGENT" --json
```

Bun users can run:

```bash
bunx @heyditto/cli init --agent --agent-caller "NAME_OF_AGENT" --json
```

The command:

- creates a free unclaimed Ditto account,
- stores the generated `ditto_mcp_...` key locally for the agent without printing it,
- returns machine-readable JSON including `userID`, `claimURL`, and local credential status,
- keeps the same key and memories after the account is claimed.

## Name The Agent

The `--agent-caller` value is the agent's name. Set it to the agent's own name,
or a name the human has already chosen for the agent.

It is set **once, at account creation**, and labels everything the agent saves:
after the account is claimed, the agent's memories appear in the owner's graph as
an _external agent thread_ titled by this name. Renaming after init is not yet
supported, so decide the name up front. If you omit `--agent-caller`, the name
defaults to the generic `agent`, which is hard to tell apart from other agents.

Example response shape:

```json
{
  "apiKeyID": 123,
  "apiKeyStored": true,
  "claimURL": "https://app.heyditto.ai/agent/claim?t=...",
  "configPath": "~/.config/heyditto/cli/config.json",
  "createdAt": "2026-05-26T00:00:00.000Z",
  "status": "unclaimed",
  "userID": "agent_..."
}
```

## What To Share

Share the `claimURL` with the human owner.

Do **not** share the `ditto_mcp_...` API key.

The claim token is carried in the query string, `?t=...`, so agents should share the full claim URL exactly as returned.

## What The Human Does

1. Open the claim link.
2. Sign in to Ditto.
3. Confirm the claim.

After that, the account belongs to the human, but the agent keeps using the same API key and the same stored memories.

## When To Use This Flow

Use agent-native signup when:

- OpenClaw installs the Ditto skill,
- Hermes installs the Ditto skill,
- an internal agent or automation needs Ditto without waiting on a human,
- the agent can safely keep its local config directory.

Use the standard MCP docs when the tool is an MCP client such as Codex, Claude, Cursor, or another editor that connects to Ditto's remote MCP server directly.

## Verify The Agent Is Ready

```bash
npx -y @heyditto/cli status
npx -y @heyditto/cli subjects "test" --output json
```

If the CLI is installed for repeated use, run `heyditto status` and `heyditto subjects "test" --output json` instead. Prefer `heyditto` over `ditto` on macOS because `/usr/bin/ditto` is Apple's built-in file-copy utility.

Expected status shape:

```text
@heyditto/cli 1.x.x
endpoint:  https://api.heyditto.ai/mcp
api key:   set  (source: config)
tools:     fetch_memories, get_memory_network, save_memory,
           search_memories, search_memories_in_subjects, search_subjects
```

## Troubleshooting

| Symptom                                            | Fix                                                                                                        |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `error: no Ditto API key configured` after install | Run `npx -y @heyditto/cli init --agent --json` again, then verify with `npx -y @heyditto/cli status`.      |
| The CLI prints a `ditto_mcp_...` key               | Update `@heyditto/cli`; agent-native signup should store the key locally without printing it.              |
| Claim page opens but the claim fails               | Make sure the full `claimURL` was shared, including the `?t=...` query parameter.                          |
| The agent already has a human-managed key          | Keep using `heyditto login <key>` or `DITTO_API_KEY`; agent-native signup is optional for existing setups. |

## Related Docs

- [Agent Integrations](/docs/agent-integrations)
- [Ditto CLI](/docs/ditto-cli)
- [Connect Ditto to OpenClaw](/docs/openclaw)
- [Connect Ditto to Hermes Agent](/docs/hermes-agent)