# AstrBot Real Protocol Review (vs Desktop provisional contract) - Date: 2026-07-20 - Status: research complete; live container probe pending user-provided instance - Conclusion: **do not claim compatibility** with `/desktop/v1`. Real AstrBot exposes Dashboard JWT + developer OpenAPI on `/api` and `/api/v1`. A desktop adapter layer is required. ## Sources | Source | Path / URL | Role | | --- | --- | --- | | Local upstream clone | `C:\Users\Administrator\Documents\Codex\refs\AstrBot` | Code authority (no GitHub Apps used) | | Package version | `pyproject.toml` → `4.26.7` | Observed clone version | | Official OpenAPI docs | `docs/zh/dev/openapi.md`, `docs/en/dev/openapi.md` | Public developer API contract | | Dashboard API code | `astrbot/dashboard/api/*`, `services/chat_service.py`, `services/auth_service.py` | Auth, SSE, WS, scopes | | Compose defaults | `compose.yml` | Port `6185` WebUI/API | | Desktop provisional contract | `docs/protocol/v1/*`, `docs/01_Architecture_Design.md`, PD-0009 | Current client assumption | Upstream repo identity: [AstrBotDevs/AstrBot](https://github.com/AstrBotDevs/AstrBot). Docker image commonly `soulter/astrbot:latest`. ## What real AstrBot exposes ### Transport and base URLs - Default container/WebUI port: **6185** (`compose.yml` maps `6185:6185`, Dockerfile `EXPOSE 6185`). - API surface is **FastAPI / ASGI**, not a custom Desktop Gateway. - Two parallel API styles coexist: 1. **v1 OpenAPI-style routes**: prefix `/api/v1` (`API_V1_PREFIX`). 2. **Legacy Dashboard routes**: prefixes like `/api/auth`, `/api/chat`, `/api/session`, etc. - Interactive docs (when running): `http://:6185/api/v1/docs` - OpenAPI schema: `http://:6185/api/v1/openapi.json` ### Authentication (two valid modes) | Mode | How presented | Intended use | Notes | | --- | --- | --- | --- | | Dashboard JWT | `Authorization: Bearer ` or cookie `astrbot_dashboard_jwt` | WebUI / dashboard-user flows | Login via `POST /api/v1/auth/login` or legacy `POST /api/auth/login` with username/password (+ optional TOTP). JWT payload: `{ username, exp }` HS256, default **7 days**. **No refresh-token endpoint found** in current code. | | Developer API Key | Official docs show `Authorization: Bearer abk_xxx` or `X-API-Key: abk_xxx`; code also accepts `ApiKey `, query `api_key`/`key` | Machine integration | Scope-gated. Prefer header auth; avoid putting keys in query strings in Desktop. | Response envelope for most JSON APIs: ```json { "status": "ok|error", "message": "...", "data": {} } ``` Login success data includes at least: ```json { "token": "", "username": "...", "change_pwd_hint": false, "md5_pwd_hint": false, "password_upgrade_required": false } ``` Fresh installs may print a random strong dashboard password in startup logs (default password policy changed). ### Chat / streaming (the critical path for Desktop text chat) | Capability | Real AstrBot | Desktop provisional (`/desktop/v1`) | | --- | --- | --- | | Send message | `POST /api/v1/chat` (OpenAPI, SSE) or legacy `POST /api/chat/send` | `POST /desktop/v1/messages` | | Session list | `GET /api/v1/chat/sessions` (API key path requires `username`) | Not modeled the same way | | New session | Dashboard: `GET /api/v1/chat/sessions/new` / legacy `GET /api/chat/new_session` | Implicit/local | | Streaming transport | **Request-scoped SSE** from chat send; also run attach `GET /api/v1/chat/runs/{run_id}/stream` | **Long-lived** `GET /desktop/v1/events/stream` with `Last-Event-ID` | | Optional duplex | `WS /api/v1/chat/ws` (OpenAPI) and live-chat WS endpoints | Deferred WS for voice/game only | | Event ACK | Not present as Desktop-style `POST /events/{id}/ack` | Required in provisional contract | | Health / server-info / capabilities | **No** `/desktop/v1/health|server-info|capabilities` | Required discovery endpoints | | Auth refresh | **No** refresh token pair found | `POST /desktop/v1/auth/refresh` | | Tool proposal from server to desktop | **Not** present as `tool.proposal` | Core operations model | | Local-action result callbacks | **Not** present as `/local-actions/*` | Required for ops tools | #### OpenAPI chat request shape (`OpenApiChatRequest`) ```json { "message": "Hello" , "session_id": "uuid-or-omit", "conversation_id": "alias-of-session_id", "username": "required-for-api-key-mode", "config_id": "optional", "config_name": "optional", "platform_id": "optional", "enable_streaming": true, "flags": {} } ``` `message` may be: 1. plain string 2. message-segment array, e.g. `{ "type": "plain", "text": "..." }` plus attachment segments (`image`/`record`/`file`/`video` with `attachment_id`) #### Observed SSE frame style (from `chat_service.py`) - Media type: `text/event-stream` - Frames are mostly `data: {json}\n\n` - Heartbeat is **comment-style**: `: heartbeat\n\n` (not Desktop `system.heartbeat` event objects) - Payload types observed in stream path include: - `session_id` - `user_message_saved` - `run_snapshot` - `agent_stats` - `attachment_saved` - `message_saved` - `error` - plus intermediate chunk payloads whose `type` can be message-chain types such as `plain` / attachment types and end markers from the internal queue This is **not** the Desktop provisional event set: ```text system.heartbeat message.delta message.completed message.proactive agent.status tool.proposal capabilities.changed error ``` ### Developer API Key scopes Supported scopes in code/docs: `bot`, `provider`, `persona`, `im`, `config`, `chat`, `file`, `plugin`, `mcp`, `skill`. Important: - `config` implies `bot` + `provider`. - Docs state developer keys do **not** currently expose some management scopes as first-class developer scopes (`tool`, `kb`, `data`, `system` called out as unsupported developer scopes in docs). - Desktop “operations tool proposal” is **not** an AstrBot OpenAPI scope; it is a Desktop-local safety model. ### Dual-instance implications AstrBot itself is one server process/instance with multi-session WebChat identities (`username` + `session_id` / platform session keys). Desktop dual slots (`companion` / `operations`) remain a **client-side** concept: - Two Desktop Profiles can point at the **same** AstrBot base URL with different roles/policies. - Or two Profiles can point at two containers. - Real server does not natively understand Desktop slot roles. - Isolation keys on Desktop must still include local `profile_id` + observed `server_instance_id` substitute + conversation/session id. There is **no first-class** `serverInstanceId` discovery endpoint equivalent to Desktop `server-info`. A safe substitute must be designed (e.g., hash of base URL + dashboard instance markers + TLS cert fingerprint + optional user-confirmed label). This is still an open protocol decision. ## Gap table (Desktop provisional vs real AstrBot) | Area | Desktop design | Real AstrBot today | Risk if ignored | Can implement now? | | --- | --- | --- | --- | --- | | Base path | `/desktop/v1/*` | `/api/v1/*` + legacy `/api/*` | 100% connection failure | Adapter required | | Auth model | access + refresh tokens | JWT (7d) and/or API Key; no refresh pair found | Refresh logic dead code / false security assumptions | Adapter: store JWT or API Key in Credential Manager | | Credentials in React | forbidden | N/A | policy violation if mirrored | Keep Rust-only secret store | | Health discovery | `/health` | not equivalent | mock-only health checks | Map to lightweight authenticated probe or WebUI reachability | | Server identity | `/server-info.serverInstanceId` | missing | silent cross-instance mixups | Need substitute identity + user confirmation | | Capabilities | `/capabilities` | partial via configs/plugins/bots lists; not Desktop schema | capability UI wrong | Map subset later | | Chat send | REST message post | `POST /api/v1/chat` SSE | wrong client shape | Implement adapter | | Event stream | long-lived SSE + Last-Event-ID | per-request SSE (+ optional run stream / WS) | reconnect/dedupe model invalid | Redesign stream manager | | Event names | Desktop enum | different types | parser rejects everything | Map/normalize in adapter | | ACK | required | absent | useless calls / noise | Make ACK optional/no-op for AstrBot backend | | Proactive messages | `message.proactive` over long SSE | IM proactive API exists (`POST /api/v1/im/message`) but not Desktop push bus | wrong product assumption | Separate design | | Ops tool.proposal | server pushes proposals | **not present** | operations panel cannot be driven by AstrBot core alone | Keep Desktop-local proposal engine / future plugin contract | | Local-action callbacks | `/local-actions/*` | absent | cannot close tool loop to AstrBot | Local audit only, or future plugin | | TLS / pinning | required by Desktop security model | container often HTTP on LAN | may force HTTP exception path | Prefer HTTPS reverse proxy; never disable TLS validation globally | | Dual SSE slots | two long-lived streams | two chat runs / two API keys / two containers | architecture mismatch | Keep dual client slots; adapt transport | ## Architecture impact (important: not a total rewrite) ### Keep (still valid) - Tauri + React + Rust boundary - Dual Profile / dual slot isolation - Credential Manager storage - Mock Gateway for deterministic tests - Local diagnostics / NAS transfer security pipeline (client-side) - Provisional Desktop protocol as **internal normalized model** ### Must add 1. **`AstrBotAdapter` (Rust)** that translates: - Desktop normalized commands → AstrBot REST/SSE/WS - AstrBot stream frames → Desktop `GatewayEvent` (best-effort mapping) 2. **Auth strategies**: - Strategy A: Dashboard username/password → JWT (short-lived session model, re-login on expiry) - Strategy B: API Key with scopes `chat` (+ `file` if attachments; carefully limited admin scopes) 3. **Stream manager redesign**: - Not one eternal server push bus - Per send-stream + optional run re-attach + future WS for duplex 4. **Server identity substitute** decision (open item) 5. **Operations path**: - Do **not** expect stock AstrBot to emit Desktop `tool.proposal` - Either local-only ops tools, or a future explicit AstrBot plugin/contract ### Do **not** do - Rewrite Desktop core to call random AstrBot internal Python APIs - Claim `/desktop/v1` is real AstrBot - Put API keys/JWT into React, SQLite plain fields, logs, or URL query strings - Disable TLS validation to “make container work” - Implement arbitrary shell execution because ops tools are missing server-side ## Live container probe plan (when you provide the instance) Please provide (redact secrets in chat if needed; better paste into a local file path I can read, or supply a temporary throwaway password/API key): 1. Base URL, e.g. `http://192.168.x.x:6185` 2. Auth mode: dashboard password **or** API Key (`abk_...`) 3. Whether LLM provider is already configured (chat may stream errors without a model) 4. Network reachability from this Windows desktop host Minimum probe sequence (no secrets logged in full): 1. `GET /` or WebUI reachability 2. `GET /api/v1/openapi.json` (schema presence/version markers) 3. Auth: - login `POST /api/v1/auth/login` **or** - API key header against `GET /api/v1/chat/sessions?username=...` 4. Create/send chat: - `POST /api/v1/chat` with small plain message and capture first SSE frames 5. Confirm session list returns the session 6. Optional: WS `/api/v1/chat/ws` smoke 7. Record actual event type sequence into this report appendix Success criteria for “connection is implementable”: - Auth succeeds without Dashboard browser cookies as the only path - One chat message produces parseable SSE frames - Session id is stable enough to store under a Desktop Profile - Dual Profiles can open two independent sessions without cross-talk Failure that would force design pause: - Only cookie-auth works and API key/JWT blocked - Chat stream format unstable / undocumented and unusable - No way to distinguish two server instances safely for dual-slot ops - Requirement to modify AstrBot core for basic text chat ## Decision recommendation | Decision | Recommendation | | --- | --- | | Is Desktop mock protocol wrong? | It is a **valid internal contract**, not a real server contract. | | Should we throw away Desktop work? | **No.** Keep Mock + normalized events; add adapter. | | First live integration target | Text chat via `POST /api/v1/chat` SSE + session APIs | | Preferred auth for automation tests | API Key with minimal scopes (`chat`, maybe `file`) | | Preferred auth for user login UX | Dashboard login → JWT in Credential Manager, re-login on 401/expiry | | Operations tools MVP | Remain Desktop-local; do not depend on AstrBot emitting proposals yet | | Protocol docs | Update PD-0009 / add ADR after first successful container probe | ## Can implement now / needs container / blocked | Item | Status | | --- | --- | | Protocol research + gap table | **Done** (this document) | | Adapter design sketch | **Ready** | | Live endpoint/version confirmation against your container | **Needs container** | | Real chat SSE fixture capture | **Needs container + model provider** | | Dual-instance identity substitute finalization | **Needs probe + product decision** | | Claiming production compatibility | **Blocked** until probe passes | | Rewriting whole Desktop architecture | **Not required** based on current evidence | ## Next action Provide the test AstrBot container endpoint and auth material. I will run a non-destructive probe, capture redacted SSE samples, and only then propose the minimal adapter implementation plan (likely ADR + protocol mapping tables, without expanding product scope). ## Live container probe (2026-07-20) - Target: `http://192.168.31.210:26285` - Auth: developer API Key (`abk_…`, redacted) - Mode: non-destructive chat/session/config probes only - Artifacts: - `docs/reports/astrbot-live-probe-summary.json` - `docs/reports/astrbot-live-probe-sse.raw.txt` (secrets redacted) - `docs/reports/run-live-probe.ps1` (requires env key; no embedded secret) ### Connectivity results | Check | Result | | --- | --- | | TCP `192.168.31.210:26285` | Reachable | | `GET /` WebUI HTML | 200 | | `GET /api/auth/setup-status` (no auth) | 200; `setup_required=false` | | API Key on `GET /api/v1/chat/sessions?username=...` | 200 | | Auth styles accepted | `Authorization: Bearer abk_…`, `X-API-Key`, `Authorization: ApiKey …`, query `api_key` (prefer headers only in Desktop) | | `GET /api/v1/configs` | 200; one config `default` | | `GET /api/v1/im/bots` | 200; `bot_ids=["napcat3"]` | | `GET /api/v1/openapi.json` / `/docs` / several management routes | Often SPA-style HTML 404 page even when authenticated; **do not rely on OpenAPI UI path on this deployment** | | Dashboard JWT login | Not exercised in this probe (API key path is sufficient for automation) | ### Chat SSE (authoritative live sample) `POST /api/v1/chat` with: ```json { "message": "desktop-probe ...", "username": "desktop-companion|desktop-operations", "session_id": "desktop-*-s1", "enable_streaming": true } ``` Observed response: - HTTP 200 - `Content-Type: text/event-stream` - Initial frames: 1. `{"type":"session_id","data":null,"session_id":"..."}` 2. `{"type":"user_message_saved","data":{"id":N,"created_at":"...","llm_checkpoint_id":"..."}}` 3. Comment heartbeats: `: heartbeat` 4. Streamed assistant tokens: `{"type":"plain","data":"Hello","streaming":true,"chain_type":null,"message_id":"..."}` - `message_id` is stable across one assistant generation - Client may close after idle heartbeats; server can keep heartbeating after partial generation - Terminal `message_saved` / `end` frames were **not always observed** before client idle-close in this probe; adapter must tolerate incomplete terminal markers and reconstruct final text from accumulated `plain` frames + later session history fetch if needed ### Dual-slot isolation evidence | Desktop-like identity | `username` | `session_id` | Session list total | | --- | --- | --- | --- | | Companion | `desktop-companion` | `desktop-companion-s1` | 1 | | Operations | `desktop-operations` | `desktop-operations-s1` | 1 | Session list responses were fully isolated by `username`. Same API key can drive both slots if Desktop binds different local usernames/session ids per Profile. Prefer separate API keys later for least privilege, but not required for MVP connectivity. ### Mapping recommendation (internal Desktop events) | AstrBot live frame | Desktop normalized event | | --- | --- | | comment `: heartbeat` | local connection liveness only (optional `system.heartbeat`) | | `session_id` | bind conversation/session identity | | `user_message_saved` | local user message ack / persistence metadata | | `plain` + `streaming=true` | `message.delta` (append `data`) | | accumulated plain until idle/end | `message.completed` (client synthesized if server omits terminal frame) | | `error` | `error` | | no `tool.proposal` observed | keep operations tools Desktop-local for now | ### Implementability verdict | Goal | Verdict | | --- | --- | | Text chat against real AstrBot | **Implementable now** via adapter | | Dual companion/operations chat panels on one server | **Implementable** with per-slot `username` + `session_id` | | Direct use of provisional `/desktop/v1` against this server | **Not possible** | | Long-lived server push bus + ACK | **Not available**; redesign stream manager | | Server-driven local tool proposals | **Not available** on stock API | | Need to rewrite whole Desktop app | **No** | ### Remaining probe gaps (non-blocking for chat MVP) - Dashboard password login / JWT expiry behavior not live-tested - File upload (`POST /api/v1/file`) not tested - WebSocket `/api/v1/chat/ws` not tested - Re-attach `GET /api/v1/chat/runs/{run_id}/stream` not tested - No durable `serverInstanceId` discovery endpoint; still needs identity substitute design - This deployment returns SPA 404 HTML for some documented OpenAPI paths; adapter should feature-detect actual routes rather than assume full OpenAPI UI availability ### Security notes from probe - API key worked and must stay in Windows Credential Manager only - Never log full key; sample captures store `abk_[REDACTED]` - Prefer header auth, not query-string key - Target is plain HTTP on LAN; TLS pinning decision remains open for production Profiles