Web Chat

The Starnion web UI provides a real-time chat interface based on WebSocket. You can converse with the AI agent directly in your browser without installing any additional app, with support for image, audio, and document file transfers and streaming responses.

Overview

With the web chat channel you can:

Real-time streaming: AI responses appear as they are generated, without waiting for a complete answer
File transfer: Attach and send images, audio files, and documents in the chat window
Tool call visibility: See in real time which tools the AI uses when accessing external services
Conversation management: Create multiple conversations (threads) and view previous conversation history
Multi-channel: Connected to the same AI agent as Telegram, sharing conversation history

Key Features

Real-time Streaming Responses

Through the WebSocket connection, AI responses are transmitted in real time token by token. Even long answers feel faster because you see the generation process from the start.

Tool Execution Display

When the AI uses tools such as weather lookup, web search, or Google Calendar, the chat window shows which tool was executed.

[Tool call: weather] Looking up current weather in Seoul...
[Tool result: weather] Seoul: clear, 22°C

File Attachment and Analysis

You can attach and send images, audio, PDF, and document files in the chat window. The AI analyzes the file contents and responds accordingly.

File Type	Supported Formats	Features
Image	JPG, PNG, GIF, WebP	Image analysis, description, text extraction
Audio	MP3, WAV, OGG	Speech-to-text conversion, content analysis
Document	PDF, DOCX, TXT	Content summary, question answering

Generated File Gallery

Images or audio files generated by the AI are automatically saved to the gallery. You can view them any time under Settings → Gallery.

Setup

Web chat is available immediately after installing Starnion with no additional configuration. Just confirm the following.

Server Access

Open your browser and navigate to the Starnion server address.
```
http://localhost:3893
```
(Use your actual domain in a production environment.)
Create an account or log in.
You can start chatting immediately in the chat area on the left side of the web UI.

WebSocket Connection Check

The web UI automatically connects to the WebSocket server when the page loads. You can verify the connection status in the browser developer tools (F12) → Network tab → WS filter.

Connection URL: ws://yourdomain.com/ws
Authentication: Bearer token (Authorization header or ?token query parameter)

Reverse Proxy Configuration (WebSocket)

If you are using a reverse proxy such as Nginx or Caddy, you must configure the WebSocket upgrade headers.

Nginx example:

location /ws {
    proxy_pass http://localhost:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 180s;
}

Caddy example:

reverse_proxy /ws localhost:8080 {
    transport http {
        versions 1.1
    }
}

How to Use

Start a New Conversation

Click the + New Conversation button in the left sidebar.
Type a message in the chat input box and press Enter or click the send button.
The AI’s response streams in real time.

Send a File

Click the Attach icon next to the chat input box or drag a file into the chat window.
Once the file is uploaded, send it along with your message.
The AI analyzes the file contents and responds.

Select an AI Model

You can select the AI model to use for the conversation at the top of the chat window. Only models for which you have registered an API key in Settings will appear.

View Previous Conversations

Check the previous conversation list in the left sidebar and click any entry to navigate to that conversation.

Example Conversations

General Conversation

Me: How do I create an async function in Python?
Bot: In Python, async functions use the `async def` keyword.

    ```python
    import asyncio

    async def fetch_data(url: str) -> str:
        await asyncio.sleep(1)  # Simulate async operation
        return f"Data from {url}"

    async def main():
        result = await fetch_data("https://example.com")
        print(result)

    asyncio.run(main())
    ```

    `await` waits for a coroutine to complete, during which the event loop can process other tasks.

Sending and Analyzing an Image

(attach a receipt image)
Me: Organize this receipt for me

Bot: Here are the receipt analysis results.
    - Store: OO Mart
    - Date: 2026-03-08
    - Total: 35,600 won

    Items:
    - Milk (2,800 won)
    - Bread (4,200 won)
    - Eggs (6,000 won)
    - Chicken breast (12,800 won)
    - Snacks (9,800 won)

    Shall I record this in your expense tracker?

Conversation with Tool Calls

Me: Tell me the current weather in Seoul

[Tool call: weather] Looking up Seoul weather...
[Tool result: weather] Done

Bot: Here is the current weather in Seoul.
    - Condition: Clear
    - Temperature: 18°C (feels like 16°C)
    - Humidity: 45%
    - A few more clouds in the afternoon, but no rain expected.

Web UI and Telegram Integration

[In the web UI]
Me: Next week's reading goal: read chapters 1–5 of Clean Code

[In Telegram later]
Me: What was my reading goal?
Bot: Next week's reading goal: read chapters 1–5 of Clean Code.
    Let me know if you have any progress to report!

WebSocket Protocol (Developer Reference)

Web chat uses the Gateway’s WebSocket endpoint (GET /ws). The communication format between client and server is as follows.

Connection

GET /ws
Authorization: Bearer <jwt-token>

Or authenticate via query parameter:

GET /ws?token=<jwt-token>

Client → Server (InFrame)

{
  "id": "req-001",
  "method": "chat",
  "params": {
    "message": "Hello",
    "model": "gemini-2.0-flash",
    "thread_id": "uuid-of-conversation"
  }
}

Field	Description
`id`	Request identifier (included as-is in the response)
`method`	Currently only `chat` is supported
`params.message`	User message (required)
`params.model`	AI model to use (optional)
`params.thread_id`	Conversation thread UUID (optional; omit to start a new conversation)

Server → Client (OutFrame)

AI responses are streamed as multiple event frames.

Text streaming:

{
  "type": "event",
  "id": "req-001",
  "event": "text",
  "payload": { "text": "Hello! " }
}

Tool execution:

{
  "type": "event",
  "id": "req-001",
  "event": "tool_call",
  "payload": { "tool": "weather", "text": "Looking up Seoul weather..." }
}

File response (image/audio):

{
  "type": "event",
  "id": "req-001",
  "event": "file",
  "payload": {
    "name": "generated_image.png",
    "mime": "image/png",
    "url": "https://storage.example.com/...",
    "size": 102400
  }
}

Done:

{
  "type": "event",
  "id": "req-001",
  "event": "done"
}

Event type summary:

Event	Description
`text`	AI response text chunk
`tool_call`	Tool call initiated
`tool_result`	Tool execution result
`file`	Generated file (image, audio, etc.)
`error`	An error occurred
`done`	Response complete

Important Notes

Concurrent Connections

If the same account is connected from multiple browser tabs or devices simultaneously, the most recent connection becomes the active one. Previous connections are closed automatically.

Message Size Limit

The maximum WebSocket message size is 64 KB. File uploads are processed via the REST API (/api/v1/upload) and are not subject to this limit.

Keep-Alive (Ping/Pong)

The server sends a WebSocket Ping message every 50 seconds. If there is no response for 60 seconds, the connection is terminated. Browsers respond with Pong automatically, so no additional handling is required.

HTTPS/WSS Recommended

In production environments, always use HTTPS and WSS (WebSocket Secure). HTTP/WS can expose JWT tokens on the network.

Troubleshooting

No Response in Chat

Check the browser console (F12) for any WebSocket connection errors.
Verify that the server address and port are correct.
If using a reverse proxy, confirm that the WebSocket upgrade headers are configured.

Connection Drops Frequently

Try increasing the reverse proxy’s proxy_read_timeout or timeout setting to 180 seconds or more.
Check that your network firewall is not blocking WebSocket connections.

“agent service unavailable” Error

This occurs when the Agent service (Python) is not running or the gRPC connection to the Gateway has been lost.

# Check service status in a Docker Compose environment
docker compose ps

# Check Agent service logs
docker compose logs agent

Uploaded Files Not Displaying Images

If MinIO object storage is not configured, file storage is disabled. Check that the MinIO service is running in your Docker Compose configuration.

FAQ

Q: Can I view conversations from the web UI in Telegram? A: Yes, the web UI and Telegram connect to the same AI agent. Anything recorded in either channel can be retrieved from the other.

Q: Can multiple people use the same server? A: Yes, Starnion supports multiple users. Each user creates an account and maintains independent conversations and settings.

Q: How long is conversation history stored on the server? A: Conversation history is stored in the PostgreSQL database. Without a separate deletion policy, it is stored permanently. You can delete individual conversations in Settings.

Q: Can it be used without an internet connection? A: If the Starnion server is running locally and you use a local LLM such as Ollama, it can be used without an internet connection. However, features that use external APIs — such as weather lookup, web search, and Google integration — require internet access.

Q: Can it be used on a mobile browser? A: Yes, the Starnion web UI is designed responsively and works in mobile browsers. However, for convenient use on a smartphone, the Telegram channel is recommended.