Pluviobyte/dot2api

Dot2API

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

English | 简体中文

[!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.

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

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.

Docker Compose

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 are required.

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:

{"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/<dot_token>. 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.

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 <api_key> or x-api-key: <api_key>. Any model value is accepted and echoed back.

curl

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

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

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.

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.

Documentation

• Connecting a Dot
• API and MCP reference
• Architecture and delivery semantics
• Configuration
• Deployment and recovery
• Security policy
• Contributing

Development

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.