Dot2API

Turn your OpenAI Dot into an OpenAI- and Claude-compatible API

English | 简体中文

Python Docker License

> [!NOTE] > This project is for technical research and personal use with your own Dot. Comply with OpenAI's terms of use and local laws; you are solely responsible for how you use it. > [!WARNING] > Anyone holding an API key can prompt your Dot, which may have access to your connected apps. Issue keys only to callers you trust as much as yourself. See [Security](SECURITY.md). ## Overview Dot2API is a self-hosted gateway that exposes one OpenAI Dot through the OpenAI Chat Completions and Anthropic Messages formats. Point an existing SDK at it: each request is queued, your Dot is woken through MCP Events, it claims and answers the request over MCP, and the reply comes back as a normal completion. Unlike most 2API projects, Dot2API does not reverse-engineer a web interface and never touches your OpenAI credentials. It uses the public MCP 2.0 connector and Events protocol, and it never calls a model itself. ### Architecture ```mermaid flowchart LR classDef access fill:#e1f5fe,stroke:#01579b classDef core fill:#fff3e0,stroke:#e65100 classDef infra fill:#e8f5e9,stroke:#1b5e20 classDef upstream fill:#fce4ec,stroke:#880e4f Clients["API clients
OpenAI SDK · Anthropic SDK · curl"] subgraph Core["Dot2API"] direction TB Compat["Compatibility layer
/v1/chat/completions · /v1/messages"] Tasks["Task core
Leases · Retries · Deadlines"] Events["Event outbox
Signed webhooks"] MCP["MCP endpoint
/mcp"] Compat --> Tasks Tasks --> Events MCP --> Tasks end Database[("SQLite")] Dot["OpenAI Dot"] Clients -->|request| Compat Compat -.->|reply| Clients Events -->|task.available| Dot Dot -->|claim_task / complete_task| MCP Tasks --> Database class Clients access class Compat,Tasks,Events,MCP core class Database infra class Dot upstream ``` ### Core capabilities | Area | Capabilities | |---|---| | APIs | OpenAI Chat Completions, Anthropic Messages, model list, and an asynchronous task API | | Clients | OpenAI-compatible and Anthropic-compatible SDKs, automation tools, and plain HTTP | | Streaming | SSE in both dialects, with keep-alives while the Dot works | | Reliability | Durable tasks, atomic claims, leases, bounded retries, deadlines, and cancellation when the caller disconnects | | Events | MCP Events subscriptions, callback verification, signed at-least-once webhook delivery | | Security | Expiring keys stored as fingerprints, scoped identities, rate limits, audit records | | Operations | One-command setup, health and readiness probes, consistent backups, hardened container image | ### Limitations A Dot is an agent, not a model endpoint, so the API is compatible in shape rather than in behavior. | Aspect | Behavior | |---|---| | Latency | Seconds to minutes per reply. Requests wait up to 300 seconds by default, then return 504 with a `task_id` to read later | | Streaming | The whole reply arrives in one delta, not token by token | | Content | Text only. Images and tool-result blocks return 400 | | Tool calling | Not supported. `tools` is ignored; the Dot uses its own tools and never returns tool calls | | Parameters | Sampling parameters and `max_tokens` are accepted and ignored. Token usage is reported as zero | | Concurrency | One Dot answers one queue. Requests wait in line | This makes Dot2API a good fit for scheduled jobs, automation workflows, custom bots, and delegating a task from another agent. It is not a model backend for coding agents such as Codex or Claude Code, or for real-time chat front ends. ## Quick start A Dot connects from OpenAI's network, so the service needs a public HTTPS URL. Both options below bind to loopback; put a TLS reverse proxy in front. See [Deployment](docs/deployment.md). ### Docker Compose ```bash git clone https://github.com/Pluviobyte/dot2api.git cd dot2api docker compose build docker compose run --rm dot2api init docker compose run --rm dot2api setup docker compose up -d ``` ### Run from source Python 3.11 or later and [uv](https://docs.astral.sh/uv/) are required. ```bash uv sync --frozen --no-dev uv run --no-sync dot2api init uv run --no-sync dot2api setup uv run --no-sync dot2api serve ``` `setup` prints two credentials once; only their fingerprints are stored: ```json {"api_key": "d2a_...", "dot_token": "d2a_...", "queue": "dot"} ``` - `api_key` is what callers put in their SDK. - `dot_token` is what the Dot uses to reach the MCP endpoint. ## Connect your Dot 1. Add an MCP connector pointing at `https:///mcp` with `dot_token` as the bearer credential. If the connector cannot send an authorization header, start the server with `DOT2API_CAPABILITY_URLS=1` and use `https:///mcp/`. 2. Ask the Dot to watch the `task.available` event on queue `dot`. 3. Give the Dot its standing instructions: list queued tasks, claim one, answer the conversation, complete the task. The full walkthrough, a ready-to-paste instruction prompt, and troubleshooting are in [Connecting a Dot](docs/dot.md). ## API | Endpoint | Purpose | |---|---| | `POST /v1/chat/completions` | OpenAI-compatible chat completion | | `POST /v1/messages` | Anthropic-compatible message | | `GET /v1/models` | Model list containing `dot` | | `POST /v1/tasks` · `GET /v1/tasks/{task_id}` | Asynchronous submission and result retrieval | | `POST /mcp` | MCP tools and event subscriptions used by the Dot | | `GET /healthz` · `GET /readyz` | Liveness and readiness | Credentials are accepted as `Authorization: Bearer ` or `x-api-key: `. Any `model` value is accepted and echoed back. ### curl ```bash curl https://dot2api.example.com/v1/chat/completions \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "dot", "messages": [{"role": "user", "content": "Summarize my unread mail from today."}] }' ``` ### OpenAI SDK ```python from openai import OpenAI client = OpenAI(base_url="https://dot2api.example.com/v1", api_key=API_KEY, timeout=600) reply = client.chat.completions.create( model="dot", messages=[{"role": "user", "content": "Summarize my unread mail from today."}], ) print(reply.choices[0].message.content) ``` ### Anthropic SDK ```python from anthropic import Anthropic client = Anthropic(base_url="https://dot2api.example.com", api_key=API_KEY, timeout=600) reply = client.messages.create( model="dot", max_tokens=1024, messages=[{"role": "user", "content": "Summarize my unread mail from today."}], ) print(reply.content[0].text) ``` Keep the client timeout above the completion timeout, or set `stream` to true so keep-alives hold the connection open. Request and response details are in the [API reference](docs/api.md). ## Configuration | Variable | Default | Meaning | |---|---|---| | `DOT2API_DATA_DIR` | `var` | Database and encryption-key directory | | `DOT2API_HOST` | `127.0.0.1` | Listen address | | `DOT2API_PORT` | `8788` | Listen port | | `DOT2API_QUEUE` | `dot` | Queue the Dot subscribes to | | `DOT2API_COMPLETION_TIMEOUT` | `300` | Seconds a request waits for the Dot before returning 504 | | `DOT2API_TASK_TTL` | `3600` | Seconds before an unanswered request expires | | `DOT2API_RATE_PER_MINUTE` | `120` | Request limit per identity | | `DOT2API_CAPABILITY_URLS` | disabled | Set to `1` to allow the token in the MCP path | Additional keys, separate callers, token rotation, and the administrative commands are covered in [Configuration](docs/configuration.md). ## Documentation - [Connecting a Dot](docs/dot.md) - [API and MCP reference](docs/api.md) - [Architecture and delivery semantics](docs/architecture.md) - [Configuration](docs/configuration.md) - [Deployment and recovery](docs/deployment.md) - [Security policy](SECURITY.md) - [Contributing](CONTRIBUTING.md) ## Development ```bash uv sync --frozen uv run pytest uv run ruff check . uv run ruff format --check . uv run python -m build uv run python scripts/check_release.py ``` ## License MIT. See [LICENSE](LICENSE).