18 KiB
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/apiand/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. Docker image commonly soulter/astrbot:latest.
What real AstrBot exposes
Transport and base URLs
- Default container/WebUI port: 6185 (
compose.ymlmaps6185:6185, DockerfileEXPOSE 6185). - API surface is FastAPI / ASGI, not a custom Desktop Gateway.
- Two parallel API styles coexist:
- v1 OpenAPI-style routes: prefix
/api/v1(API_V1_PREFIX). - Legacy Dashboard routes: prefixes like
/api/auth,/api/chat,/api/session, etc.
- v1 OpenAPI-style routes: prefix
- Interactive docs (when running):
http://<host>:6185/api/v1/docs - OpenAPI schema:
http://<host>:6185/api/v1/openapi.json
Authentication (two valid modes)
| Mode | How presented | Intended use | Notes |
|---|---|---|---|
| Dashboard JWT | Authorization: Bearer <jwt> 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 <key>, 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:
{ "status": "ok|error", "message": "...", "data": {} }
Login success data includes at least:
{
"token": "<jwt>",
"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 |
| 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)
{
"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:
- plain string
- message-segment array, e.g.
{ "type": "plain", "text": "..." }plus attachment segments (image/record/file/videowithattachment_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 Desktopsystem.heartbeatevent objects) - Payload types observed in stream path include:
session_iduser_message_savedrun_snapshotagent_statsattachment_savedmessage_savederror- plus intermediate chunk payloads whose
typecan be message-chain types such asplain/ attachment types and end markers from the internal queue
This is not the Desktop provisional event set:
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:
configimpliesbot+provider.- Docs state developer keys do not currently expose some management scopes as first-class developer scopes (
tool,kb,data,systemcalled 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+ observedserver_instance_idsubstitute + 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
AstrBotAdapter(Rust) that translates:- Desktop normalized commands → AstrBot REST/SSE/WS
- AstrBot stream frames → Desktop
GatewayEvent(best-effort mapping)
- Auth strategies:
- Strategy A: Dashboard username/password → JWT (short-lived session model, re-login on expiry)
- Strategy B: API Key with scopes
chat(+fileif attachments; carefully limited admin scopes)
- Stream manager redesign:
- Not one eternal server push bus
- Per send-stream + optional run re-attach + future WS for duplex
- Server identity substitute decision (open item)
- 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 expect stock AstrBot to emit Desktop
Do not do
- Rewrite Desktop core to call random AstrBot internal Python APIs
- Claim
/desktop/v1is 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):
- Base URL, e.g.
http://192.168.x.x:6185 - Auth mode: dashboard password or API Key (
abk_...) - Whether LLM provider is already configured (chat may stream errors without a model)
- Network reachability from this Windows desktop host
Minimum probe sequence (no secrets logged in full):
GET /or WebUI reachabilityGET /api/v1/openapi.json(schema presence/version markers)- Auth:
- login
POST /api/v1/auth/loginor - API key header against
GET /api/v1/chat/sessions?username=...
- login
- Create/send chat:
POST /api/v1/chatwith small plain message and capture first SSE frames
- Confirm session list returns the session
- Optional: WS
/api/v1/chat/wssmoke - 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.jsondocs/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:
{
"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:
{"type":"session_id","data":null,"session_id":"..."}{"type":"user_message_saved","data":{"id":N,"created_at":"...","llm_checkpoint_id":"..."}}- Comment heartbeats:
: heartbeat - Streamed assistant tokens:
{"type":"plain","data":"Hello","streaming":true,"chain_type":null,"message_id":"..."}
message_idis stable across one assistant generation- Client may close after idle heartbeats; server can keep heartbeating after partial generation
- Terminal
message_saved/endframes were not always observed before client idle-close in this probe; adapter must tolerate incomplete terminal markers and reconstruct final text from accumulatedplainframes + 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/wsnot tested - Re-attach
GET /api/v1/chat/runs/{run_id}/streamnot tested - No durable
serverInstanceIddiscovery 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