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:

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

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

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:

{
  "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_..."
}

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

Open the claim link.
Sign in to Ditto.
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

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:

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