⚠️ Note: The Serendipity backend server has not been publicly released yet. This repository contains only the web UI frontend, which requires the backend to function. Please check back later for updates on the full release.
A standalone web interface for the Serendipity AI agent platform. This application provides a modern, responsive UI for managing AI agents, conversations, workflows, and system configurations.
- Agent Management - Select, configure, and customize AI agents
- Conversations - Real-time chat with AI agents via WebSocket streaming
- Workflows - Create and execute automated workflows
- Voice Support - Voice recording, transcription, and TTS playback
- File Handling - Upload and stage files for conversation context
- LLM Configuration - Configure multiple LLM providers (OpenAI, Anthropic, Groq, Ollama, vLLM, etc.)
- MCP Servers - Manage Model Context Protocol server connections
- Toolsets - Create collections of tools from MCP servers
- Dark/Light Mode - Toggle between themes
- Bitcoin Authentication - Secure API requests with Bitcoin message signing
- Session Unlock - Decrypted WIF is held in per-tab sessionStorage with a Lock button, avoiding repeated password prompts within a tab
- Backend: FastAPI (Python)
- Frontend: Vanilla JavaScript (ES Modules), TailwindCSS
- Templating: Jinja2
- Authentication: Bitcoin WIF key signing
- Real-time: WebSocket for streaming responses
- Python 3.12+ (for local development)
- Docker (for containerized deployment)
- A running Serendipity backend server
# Build the image
docker build -t serendipity-webui .
# Run the container
docker run -p 8080:8080 serendipity-webuiAccess the application at http://localhost:8080
Note: The container entrypoint binds Uvicorn to
0.0.0.0by default (the bare-metalapp.maindefault of127.0.0.1is overridden inside the container), sodocker run -p 8080:8080 serendipity-webuiworks as-is. To keep the UI loopback-only inside the container, setSERENDIPITY_WEBUI_HOST=127.0.0.1. Because a wildcard bind leaves the startup TTS allow-list empty, operators exposing the container should also setSERENDIPITY_WEBUI_ALLOWED_ORIGINSexplicitly (e.g.docker run -e SERENDIPITY_WEBUI_ALLOWED_ORIGINS=http://localhost:8080 -p 8080:8080 serendipity-webui).
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# or, as an editable install (pyproject.toml declares the same runtime dependencies,
# including python-dotenv, which app/main.py needs to load .env at startup):
pip install -e .
# Run the development server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8080On first launch, you'll be prompted to configure:
-
Server Connection
- Server Address (default:
localhost) - Server Port (default:
42069) - WebSocket Port (default:
8765)
- Server Address (default:
-
WIF Key
- Enter an existing WIF key or generate a new one
- A password is required; the WIF key is always stored encrypted in localStorage (never in plaintext). The encrypted blob uses PBKDF2-HMAC-SHA256 (600,000 iterations) with ChaCha20 + HMAC-SHA256 (encrypt-then-MAC) in pure JavaScript; the iteration count is stored in a self-describing blob header, and older stored blobs remain decryptable
- Because key derivation at 600,000 PBKDF2 iterations takes a moment, the unlock, setup "Save & Continue", and change-key "Save" buttons show a brief "Unlocking…"/"Encrypting…" busy state (and are disabled) while the key is derived, so the UI does not appear frozen.
- The decrypted key is held in per-tab sessionStorage, so you unlock once per tab session and page navigations within that tab no longer re-prompt for the password
- The decrypted key is cleared when the tab closes and is never written to disk; use the sidebar Lock button to forget the unlocked key for the current session
- When the key is unlocked, the Settings page shows a fixed
(key loaded — hidden)placeholder for the key field rather than any part of the key — the WIF private key is never echoed into the page DOM (only the derived address is shown). - If a corrupted or non-JSON WIF entry is found in localStorage on startup (e.g. from manual edits or an interrupted write), the stored value is discarded with a console warning and the encrypted-key entry is cleared, so the setup/unlock flow starts cleanly instead of failing to load.
All settings are stored in your browser's localStorage.
Server-side settings are read from environment variables. These can be provided via a .env file in the project root, which is loaded automatically at startup (python-dotenv). Copy the template and adjust the values:
cp .env.example .envSERENDIPITY_WEBUI_HOST— host address the web UI binds to. When running bare-metal or viapython -m app.mainthe default is127.0.0.1(set to0.0.0.0to expose the UI on all interfaces); inside the container theentrypoint.shdefault is0.0.0.0(set127.0.0.1to keep it loopback-only).SERENDIPITY_WEBUI_PORT— port the web UI listens on (default8080).SERENDIPITY_TTS_SERVERS— JSON object mapping opaque selector keys to trusted TTS server base URLs (see TTS proxy security).SERENDIPITY_WEBUI_ALLOWED_ORIGINS— comma-separated list of allowed origins (scheme + netloc) for cross-origin protection on the TTS endpoints (see TTS proxy security). When unset or blank it defaults to the server's own origin (http://{host}:{port}), so the default configuration permits same-origin requests while still rejecting cross-origin ones. WhenSERENDIPITY_WEBUI_HOSTis a wildcard bind address (0.0.0.0or::), the startup default is left unset on purpose (becausehttp://0.0.0.0:PORTis not a browser-reachable origin) and same-origin requests are instead derived per request from the request's scheme andHostheader — but only when the parsed host is an IP literal (IPv4/IPv6) orlocalhost/127.0.0.1/::1; a DNS hostname in theHostheader is rejected in this fallback (to prevent DNS rebinding), so deployments reachable via a real DNS hostname should setSERENDIPITY_WEBUI_ALLOWED_ORIGINSexplicitly to the real origin(s). Behind a TLS-terminating reverse proxy the app seeshttpwhile the browser sends anhttpsOrigin, so the per-request same-origin fallback accepts bothhttp://<host>andhttps://<host>for the request's own host; setSERENDIPITY_WEBUI_ALLOWED_ORIGINSexplicitly to the realhttps://origin(s) for the most explicit configuration, and/or setSERENDIPITY_WEBUI_TRUST_FORWARDED_PROTO=1when the app is only reachable through a proxy that setsX-Forwarded-Proto(never enable it when clients can reach the app directly).SERENDIPITY_WEBUI_TRUST_FORWARDED_PROTO— opt-in (default off; truthy values1/true/yes/on) that makes the per-request same-origin fallback honour theX-Forwarded-Protoheader (first value only, must behttp/https) when deriving the request's own origin scheme. Only enable it when the app is reachable exclusively through a proxy that overwrites/stripsX-Forwarded-Proto; it never changes the host, only the scheme of the self-origin.
.env is gitignored; commit only .env.example.
The UI derives the scheme of every backend request (HTTP API and WebSocket) from the current page protocol. When the Web UI is served over HTTPS, the frontend talks to the backend over https:///wss:// as well; if the backend API port is not also reachable over TLS, the browser will refuse the connection (mixed-content / WebSocket upgrade failures). When running the Web UI behind HTTPS, make sure the Serendipity backend API and WebSocket ports are served over TLS too.
The /api/tts-proxy endpoint does not accept a server URL from the client. The server query parameter is an opaque selector key resolved against the server-side SERENDIPITY_TTS_SERVERS configuration, and the outbound request URL is built solely from that configuration. Because no request-supplied value is ever used to build the fetch target, the endpoint cannot be driven to fetch an attacker-chosen address — the SSRF class is eliminated by design rather than by validation.
- The
serverparameter defaults toprimary; an unknown selector returns HTTP 400 ({"error": "Unknown TTS server"}) and never falls back to an arbitrary URL. SERENDIPITY_TTS_SERVERSmust be a JSON object mapping selector keys to base URLs (e.g.{"primary": "http://192.168.0.202:8000"}). When it is unset, empty, or invalid, no selector resolves and the proxy returns HTTP 400.- Cross-origin browser requests are rejected with HTTP 403 (
{"error": "Cross-origin TTS proxy request rejected"}): theOriginheader is compared against the server-side allow-listSERENDIPITY_WEBUI_ALLOWED_ORIGINS(a comma-separated list of full origins such ashttp://127.0.0.1:8080), matched exactly against scheme + netloc. WhenSERENDIPITY_WEBUI_ALLOWED_ORIGINSis unset or blank the allow-list defaults to the server's own origin (populated at startup fromhttp://{host}:{port}, and derived from the request's scheme +Hostheader as a fallback when the list is empty — but only when the parsed host is an IP literal (IPv4/IPv6) orlocalhost/127.0.0.1/::1; a DNS name or an unparsableHostis rejected, so it cannot be rebound to127.0.0.1by an attacker); with a wildcard bind host (0.0.0.0/::) the startup allow-list is deliberately left empty so the request-time scheme +Hostfallback applies (avoiding an unreachablehttp://0.0.0.0:PORTentry), so same-origin requests that carry anOriginheader are allowed by default and only cross-origin requests are refused. The request-time fallback accepts both thehttpandhttpsforms of the request's own host (so TLS-terminating reverse proxies work out of the box), but only when that host is an IP literal orlocalhost/127.0.0.1/::1, andX-Forwarded-Protois only honoured when explicitly trusted viaSERENDIPITY_WEBUI_TRUST_FORWARDED_PROTO. TheRefererheader is no longer used for the decision, and the requestHostheader is never trusted (it is only used to derive the request's own origin in the empty-list fallback, never to match a foreignOrigin). WhenOriginis absent the decision is based onSec-Fetch-Site:Sec-Fetch-Site: same-originis allowed (browsers omitOriginon same-origin GETs), while any other value (same-site,cross-site,none) is rejected. A request with noSec-Fetch-Siteand noSec-Fetch-Modeis treated as a non-browser client and allowed;Sec-Fetch-Modeis only a fallback browser detector, not a trust signal on its own. Trade-off: these fetch-metadata headers are client-supplied and spoofable, so this is defence-in-depth only for browsers that honour the spec; a non-browser client that omits them is still allowed, which is why/api/tts-serverstill returns the configured URL to non-browser clients. Correctness does not depend on this check. Origin: nullis a serialized opaque origin: browsers send the literal valuenullwhen the requesting context cannot name its origin — a sandboxed iframe withoutallow-same-origin, a document loaded fromfile://, adata:/blob:top-level document, or after a cross-origin redirect that taints the origin. It is a distinct, explicitly-sent value, not the absence of an origin. Because thenullorigin is shared by every opaque-origin context, allow-listing the literal stringnullinSERENDIPITY_WEBUI_ALLOWED_ORIGINSis all-or-nothing: it grants access to any sandboxed iframe on any site, any localfile://page, and anydata:/blob:document — a much broader grant than a named origin. Only addnulldeliberately, when the deployment genuinely serves the UI from such a context (e.g. the UI is opened as a localfile://page, or embedded in a sandboxed iframe withoutallow-same-origin); otherwise prefer a normal named origin, or addallow-same-originto sandboxed embeds and use the real origin where possible.- The upstream
Content-Typeheader is attacker-influenceable and is never echoed verbatim: it is sanitised before being returned. Parameters (anything after;) are stripped, and any value containing control characters (characters below0x20or DEL0x7f, e.g. CR/LF) is rejected with HTTP 502 ("TTS server returned invalid content type"), blocking header-injection / response-splitting. A value that is notaudio/*returns HTTP 502 ("TTS server returned non-audio content"), and a non-allow-listedaudio/*sub-type safely falls back toaudio/wavinstead of being echoed. - Responses larger than 25 MB return HTTP 502 (
"TTS response too large"); the cap is enforced incrementally while streaming the upstream body (in addition to the up-frontContent-Lengthcheck where present), so an oversized body is rejected with HTTP 502 before it is forwarded to the client, and peak memory stays bounded even for chunked responses with noContent-Lengthheader. - Unexpected proxy failures return HTTP 500 with a generic
"Internal TTS proxy error"message; details are logged server-side rather than returned to the client. - A read-only
GET /api/tts-serverendpoint returns the resolved default server URL ({"url": ...}, ornullwhen unconfigured) for UI actions that call the Serendipity backend directly (voice initialization); the proxy itself never uses a client-supplied URL.
Note: The endpoint streams the upstream fetch (enforcing the 25 MB cap while reading chunk-by-chunk) but still fully accumulates the size-bounded audio in memory before returning a single response to the client — it does not stream through to the client (the client consumes complete blobs for
<audio>playback, with streaming behaviour provided by the per-text-chunk prefetch queue).
Server-side values interpolated into JavaScript in Jinja2 templates (e.g. agent_name, workflow_id, node_id) are rendered using Jinja2's tojson filter so they are safely encoded as JSON, preventing a crafted value from breaking out of a JavaScript string literal (JS injection / XSS).
Dynamic values (e.g. agent names, descriptions, image URLs, message ids, sender names, tool/role/skill names) inserted into template innerHTML via JavaScript string interpolation are escaped with a shared escapeHtml helper covering &, <, >, \" and ', so values are safe in both element-text and quoted-attribute/inline-handler contexts. Inline onclick handlers that previously embedded untrusted values now use data-* attributes with addEventListener bindings. The TTS text-extraction helper (getTextOnlyContent in conversation.html) likewise sanitizes message content through sanitizeHtml (DOMPurify) before parsing it via innerHTML, so active markup is stripped as well as escaped. The same escapeHtml helper also guards the instruction/resource preview fallback in skills.html (updateInstructionsPreview and setResourceTab), which is used when the vendored marked library is unavailable, so unescaped content can no longer reach innerHTML. Rendered conversation message content (including thinking blocks) is likewise routed through sanitizeHtml via a shared renderMarkdownWithThinking() helper in conversation.html, so every fragment — thinking blocks included — is sanitized before reaching innerHTML, and collapse/expand buttons use data-thinking-toggle attributes with addEventListener (via bindThinkingToggles()) rather than inline onclick handlers, which the sanitizer strips.
serendipity-webui/
├── app/
│ ├── __init__.py
│ ├── main.py # FastAPI application & routes
│ ├── vulture_whitelist.py # Vulture false-positive whitelist (wired via [tool.vulture]; excluded from coverage)
│ └── templates/ # Jinja2 HTML templates
│ ├── base.html # Base template with sidebar
│ ├── agents.html # Agent selection page
│ ├── agent_home.html # Agent dashboard
│ ├── conversation.html # Chat interface
│ ├── conversations.html # Conversation list
│ ├── edit_agent.html # Agent configuration
│ ├── settings.html # App settings
│ ├── llms.html # LLM configuration
│ ├── mcps.html # MCP server config
│ ├── toolsets.html # Toolset management
│ ├── skills.html # Skills management
│ ├── scheduled_tasks.html # Scheduled tasks
│ └── workflows.html # Workflow editor
├── static/
│ ├── css/
│ │ ├── style.css # Custom styles
│ │ ├── tailwind.css # TailwindCSS source
│ │ ├── tailwind.output.css # Compiled CSS
│ │ └── github-dark.min.css
│ ├── images/
│ │ └── SERENDIPITY_icon.png
│ └── js/
│ ├── api.js # API client
│ ├── bitcoin.js # Bitcoin signing utilities
│ └── vendor/ # Third-party libraries
├── unittests/ # Pytest test suite
│ ├── conftest.py # Shared fixtures (FastAPI TestClient)
│ ├── vulture_whitelist.py # Vulture false-positive whitelist (wired via [tool.vulture]; excluded from coverage)
│ ├── test_pages.py # Page route tests
│ ├── test_dependency_manifests.py # pyproject.toml/requirements.txt dependency-parity tests
│ ├── test_main_entrypoint.py # __main__ entrypoint test
│ ├── test_entrypoint_script.py # entrypoint.sh bind-host/export regression tests
│ ├── test_template_js_interpolation.py # JS interpolation (tojson) security tests
│ ├── test_tts_proxy.py # /api/tts-proxy endpoint tests
│ ├── test_xss_sanitization.py # XSS sanitization tests
│ ├── test_session_wif.py # Session WIF unlock tests (QuickJS)
│ ├── test_wif_busy_state.py # withWifBusy() busy-state UI helper tests
│ ├── test_wif_encryption.py # WIF at-rest encryption tests (SCv2/SCv3/legacy, KAT, tamper)
│ ├── test_wif_validation.py # WIF parse/validation tests
│ ├── test_innerhtml_data_escaping.py # innerHTML/data-escaping regression tests
│ ├── test_thinking_block_sanitized.py # Thinking-block render sanitization / innerHTML injection regression tests
│ ├── test_api_json_error_handling.py # API client JSON/status error-handling tests
│ ├── test_load_wif_storage.py # loadWifStorage() corrupted/non-JSON localStorage recovery tests
│ ├── test_wif_unlock_guard.py # Locked-WIF guard (requireWif) regression tests
│ └── test_settings_wif_not_exposed.py # Settings page never echoes WIF key material tests
├── Dockerfile # Multi-stage Docker build
├── entrypoint.sh # Container entrypoint
├── requirements.txt # Python dependencies
├── tailwind.config.js # TailwindCSS configuration
└── build-css.sh # CSS build script
| Route | Description |
|---|---|
/ |
Agent selection |
/agent/{name} |
Agent dashboard |
/agent/{name}/conversations |
Conversation list |
/agent/{name}/conversation |
Chat interface |
/agent/{name}/edit |
Edit agent settings |
/agent/{name}/workflows |
Workflow editor |
/settings |
Application settings |
/llms |
LLM configurations |
/mcps |
MCP server configurations |
/toolsets |
Toolset management |
/skills |
Skills management |
/scheduled-tasks |
Scheduled tasks |
/api/tts-proxy |
TTS synthesis proxy endpoint (server-side selector; see TTS proxy security) |
/api/tts-server |
Read-only default TTS server URL (for voice initialization) |
The web UI connects to a Serendipity backend server. All POST requests are authenticated using Bitcoin message signing:
// Request format for authenticated endpoints
{
"message": "/sha256/{hash}",
"signature": "<bitcoin_signature>",
"address": "<bitcoin_address>",
"data": { /* request payload */ }
}The message field is a /sha256/{hash} over a canonical JSON serialisation of the payload: the backend verifies against Python's json.dumps(data, sort_keys=True, indent=2, ensure_ascii=False), and the client (jsonSortedEncode() in static/js/bitcoin.js) must produce a byte-identical string. Both sides therefore share one contract — sorted keys (by Unicode code point), two-space indentation, raw UTF-8 (no \uXXXX for non-ASCII), CPython float formatting, and undefined handled like JSON.stringify (object entries omitted, array elements rendered as null). The backend hashes the data it receives, so the client must sign exactly the JSON it POSTs: because JavaScript cannot distinguish an integer from an integral float (1 vs 1.0), an integral value is signed and sent as the bare integer 1 and must never be coerced to 1.0 on only one side of the wire.
Every API call routes its fetch response through a shared parseJsonResponse() helper (static/js/api.js), which checks the HTTP status and Content-Type before parsing. Failed (non-2xx) requests throw an Error carrying the server's JSON error/detail message when the body is application/json (falling back to the status/status text otherwise), and successful responses that are not application/json are reported clearly as a non-JSON response error rather than surfacing an unhelpful JSON parse failure.
If you modify TailwindCSS classes:
./build-css.sh- Create a new template in
app/templates/ - Add a route in
app/main.py - Extend
base.htmlfor consistent navigation
Tests live in unittests/ and are run with pytest:
# Run the test suite
pytest
# Run with coverage
pytest --cov=appThe pytest configuration in pyproject.toml sets testpaths = ["unittests"] and pythonpath = ["."]. Coverage is collected from the app package (source = ["app"]), with app/vulture_whitelist.py and unittests/vulture_whitelist.py omitted from coverage as vulture whitelist files of false positives, wired into vulture via the [tool.vulture] paths list in pyproject.toml.
The Dockerfile uses a multi-stage build for minimal image size:
- Stage 1 (builder): Installs Python dependencies into a virtual environment
- Stage 2 (runtime): Copies only the venv and application code
The container runs as a non-root user for security.
- ENTRYPOINT: Runs
uvicornin the foreground as PID 1 viaexecinentrypoint.sh, so the server receivesSIGTERM/SIGINTfor graceful shutdown and the container exits with the application's status code (allowing restart policies to detect crashes). - Bind address: The container entrypoint defaults the bind host to
0.0.0.0(overriding the bare-metalapp.maindefault of127.0.0.1) sodocker run -p 8080:8080is reachable out of the box; setSERENDIPITY_WEBUI_HOST=127.0.0.1for loopback-only. Because a wildcard bind leaves the startup TTS allow-list empty, operators exposing the container should setSERENDIPITY_WEBUI_ALLOWED_ORIGINSexplicitly (the empty-list fallback only accepts an IP-literal orlocalhostHost; a DNS hostname is rejected).
This project is licensed under the MIT License - see the LICENSE file for details.