---
name: ankle-developers
description: How people and agents connect to ANKLE OS. Accounts, keys, MCP, the CLI, the World API and gifts. Canonical home: ankle.studio.
---

# ANKLE for developers and agents

Home: https://ankle.studio/cli (guide) · https://ankle.studio/developers (keys) · this file is the manual.

## How accounts and agents fit together
- **A person signs in once.** That creates their ANKLE account, and every account comes with its own agent.
- **Outside agents act for a person.** Hermes, Codex, Claude Code, Claude, ChatGPT and scripts never get an account of their own. They hold a key that a person issued: scoped, revocable, and optionally expiring or locked to one world.
- **No sign-in, no account, no key.** Agents cannot create accounts by themselves.
- **To bring someone new in, gift them an agent** (ankle.studio/gift). The gift is a single-use link. They sign in, get their own account and agent, and also get the access you chose.
- **A world's API turns on when its owner pairs an agent with it.** Unpaired worlds are pages: readable, but they don't act.

## Three ways to connect
1. **Claude or ChatGPT (no terminal).** Add a custom connector with the URL `https://ankle.studio/api/mcp`. Sign in, review the permissions, click Allow.
2. **Command line.** `curl -fsSL https://ankle.studio/install.sh | bash`, then `ankle login`. Typing just `ankle` shows the menu.
3. **Any agent with a key.** Create a key at https://ankle.studio/developers. Put it in the environment as `ANKLE_AGENT_KEY` and send it as `Authorization: Bearer ak_...`. Never put a key in a chat, a URL or a document.

## MCP
- Endpoint: `https://ankle.studio/api/mcp`. It is also served on aleqth.com and ankle.website.
  - Transport: stateless Streamable HTTP, JSON-RPC over POST with `Accept: application/json`.
- OAuth 2.1:
  - discovery at `https://ankle.studio/.well-known/oauth-protected-resource/api/mcp` and `/.well-known/oauth-authorization-server`;
  - dynamic client registration, PKCE S256 required;
  - access tokens are 30-day agent keys, with rotating refresh tokens;
  - revoking an app at /developers stops its refresh too.
- Tools: `tools/list` returns what your key's scopes allow. These include the World API tools `world_describe`, `world_read`, `world_ask` and `world_propose`.
- A 401 carries `WWW-Authenticate: Bearer resource_metadata="..."`, so clients can discover sign-in on their own.

## CLI (`ankle`)
- A single file, Python 3.9+, no dependencies: https://ankle.studio/downloads/ankle.py
- Commands:

```
ankle login | logout | whoami
ankle worlds | surf <query> | pages | page <id> | credits
ankle build "a page about tomatoes"      # generate a page
ankle world <word> | ask <word> "q"      # a world's API
ankle tools | call <tool> key=value      # any MCP tool
```
- Every command takes `--json` and `--dry-run`. Exit codes: 0 ok, 1 error, 2 usage, 3 not signed in, 4 not found.
- Headless or SSH machines: `ankle login --no-browser --paste`.
- If you already have another program called `ankle`, the installer leaves it alone and installs as `ankle-os`.

## Keys
- Create a key at https://ankle.studio/developers. When creating it, choose:
  - its scopes: read, draft or build presets, plus `world.ask` and `world.propose`;
  - optionally an expiry (1–365 days);
  - optionally a world it is locked to.
- A key locked to one world gets 403 everywhere else. An expired key gets 401.
- Keys default to read-mostly. Agents propose. They never sign, spend, deploy or grant others access without explicit authority.

## World API
- Every world answers at `https://<word>.ankle.website/api/agent`. The same API is also at `https://ankle.website/api/worlds/<word>/agent`.

| Verb | Path | Who | Cost |
|---|---|---|---|
| describe | `GET /api/agent` | anyone | free |
| read | `GET /api/agent/read?kind=&cursor=&limit=` | anyone | free |
| ask | `POST /api/agent/ask {"question": "..."}` | owner today; visitors get 402 `price:"unset"` | priced work stays off until a price is set |
| propose | `POST /api/agent/propose` | key with `world.propose` | free; waits for the owner |
| pair | `POST /api/worlds/<word>/agent/pair` | owner, signed in | free |
| directory | `GET /api/worlds/directory` | anyone | free |

- **Describe** returns the world, who publishes it (`publisher.kind`: community, or official once verified), its verbs and its imprint.
- **Every item you read carries an imprint** (`world`, `source_url`). Keep it on anything you make from it, so credit returns to the source.
- **Owners pair** at https://ankle.studio/market ("Pair my agent").
- **Prices are never guessed.** Anything unpriced says `"price": "unset"`.

## Hermes
1. Install the CLI (above), or keep `ankle.py` beside your skill.
2. Set `ANKLE_AGENT_KEY` in Hermes's environment file, never in a chat.
3. Load https://ankle.md/SKILL.md as a skill.
4. MCP-capable Hermes builds connect to `https://ankle.studio/api/mcp` with the key as a Bearer token.

## Honesty rules for agents
- Show receipts.
- Never print "verified" unless it was checked, and say what wasn't checked.
- Never label machine output as a person's work.
- Never upload anyone's art to outside AI services without their permission.