Skip to content

About

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.

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Serendipity Web UI

⚠️ 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.

Serendipity

Features

  • 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

Tech Stack

  • Backend: FastAPI (Python)
  • Frontend: Vanilla JavaScript (ES Modules), TailwindCSS
  • Templating: Jinja2
  • Authentication: Bitcoin WIF key signing
  • Real-time: WebSocket for streaming responses

Prerequisites

  • Python 3.12+ (for local development)
  • Docker (for containerized deployment)
  • A running Serendipity backend server

Quick Start

Using Docker (Recommended)

# Build the image
docker build -t serendipity-webui .

# Run the container
docker run -p 8080:8080 serendipity-webui

Access the application at http://localhost:8080

Note: The container entrypoint binds Uvicorn to 0.0.0.0 by default (the bare-metal app.main default of 127.0.0.1 is overridden inside the container), so docker run -p 8080:8080 serendipity-webui works as-is. To keep the UI loopback-only inside the container, set SERENDIPITY_WEBUI_HOST=127.0.0.1. Because a wildcard bind leaves the startup TTS allow-list empty, operators exposing the container should also set SERENDIPITY_WEBUI_ALLOWED_ORIGINS explicitly (e.g. docker run -e SERENDIPITY_WEBUI_ALLOWED_ORIGINS=http://localhost:8080 -p 8080:8080 serendipity-webui).

Local Development

# 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 8080

Configuration

On first launch, you'll be prompted to configure:

  1. Server Connection

    • Server Address (default: localhost)
    • Server Port (default: 42069)
    • WebSocket Port (default: 8765)
  2. 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.

Environment configuration

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 .env
  • SERENDIPITY_WEBUI_HOST — host address the web UI binds to. When running bare-metal or via python -m app.main the default is 127.0.0.1 (set to 0.0.0.0 to expose the UI on all interfaces); inside the container the entrypoint.sh default is 0.0.0.0 (set 127.0.0.1 to keep it loopback-only).
  • SERENDIPITY_WEBUI_PORT — port the web UI listens on (default 8080).
  • 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. When SERENDIPITY_WEBUI_HOST is a wildcard bind address (0.0.0.0 or ::), the startup default is left unset on purpose (because http://0.0.0.0:PORT is not a browser-reachable origin) and same-origin requests are instead derived per request from the request's scheme and Host header — but only when the parsed host is an IP literal (IPv4/IPv6) or localhost/127.0.0.1/::1; a DNS hostname in the Host header is rejected in this fallback (to prevent DNS rebinding), so deployments reachable via a real DNS hostname should set SERENDIPITY_WEBUI_ALLOWED_ORIGINS explicitly to the real origin(s). Behind a TLS-terminating reverse proxy the app sees http while the browser sends an https Origin, so the per-request same-origin fallback accepts both http://<host> and https://<host> for the request's own host; set SERENDIPITY_WEBUI_ALLOWED_ORIGINS explicitly to the real https:// origin(s) for the most explicit configuration, and/or set SERENDIPITY_WEBUI_TRUST_FORWARDED_PROTO=1 when the app is only reachable through a proxy that sets X-Forwarded-Proto (never enable it when clients can reach the app directly).
  • SERENDIPITY_WEBUI_TRUST_FORWARDED_PROTO — opt-in (default off; truthy values 1/true/yes/on) that makes the per-request same-origin fallback honour the X-Forwarded-Proto header (first value only, must be http/https) when deriving the request's own origin scheme. Only enable it when the app is reachable exclusively through a proxy that overwrites/strips X-Forwarded-Proto; it never changes the host, only the scheme of the self-origin.

.env is gitignored; commit only .env.example.

HTTPS / TLS

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.

TTS proxy security

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 server parameter defaults to primary; an unknown selector returns HTTP 400 ({"error": "Unknown TTS server"}) and never falls back to an arbitrary URL.
  • SERENDIPITY_TTS_SERVERS must 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"}): the Origin header is compared against the server-side allow-list SERENDIPITY_WEBUI_ALLOWED_ORIGINS (a comma-separated list of full origins such as http://127.0.0.1:8080), matched exactly against scheme + netloc. When SERENDIPITY_WEBUI_ALLOWED_ORIGINS is unset or blank the allow-list defaults to the server's own origin (populated at startup from http://{host}:{port}, and derived from the request's scheme + Host header as a fallback when the list is empty — but only when the parsed host is an IP literal (IPv4/IPv6) or localhost/127.0.0.1/::1; a DNS name or an unparsable Host is rejected, so it cannot be rebound to 127.0.0.1 by an attacker); with a wildcard bind host (0.0.0.0/::) the startup allow-list is deliberately left empty so the request-time scheme + Host fallback applies (avoiding an unreachable http://0.0.0.0:PORT entry), so same-origin requests that carry an Origin header are allowed by default and only cross-origin requests are refused. The request-time fallback accepts both the http and https forms 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 or localhost/127.0.0.1/::1, and X-Forwarded-Proto is only honoured when explicitly trusted via SERENDIPITY_WEBUI_TRUST_FORWARDED_PROTO. The Referer header is no longer used for the decision, and the request Host header is never trusted (it is only used to derive the request's own origin in the empty-list fallback, never to match a foreign Origin). When Origin is absent the decision is based on Sec-Fetch-Site: Sec-Fetch-Site: same-origin is allowed (browsers omit Origin on same-origin GETs), while any other value (same-site, cross-site, none) is rejected. A request with no Sec-Fetch-Site and no Sec-Fetch-Mode is treated as a non-browser client and allowed; Sec-Fetch-Mode is 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-server still returns the configured URL to non-browser clients. Correctness does not depend on this check.
  • Origin: null is a serialized opaque origin: browsers send the literal value null when the requesting context cannot name its origin — a sandboxed iframe without allow-same-origin, a document loaded from file://, a data:/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 the null origin is shared by every opaque-origin context, allow-listing the literal string null in SERENDIPITY_WEBUI_ALLOWED_ORIGINS is all-or-nothing: it grants access to any sandboxed iframe on any site, any local file:// page, and any data:/blob: document — a much broader grant than a named origin. Only add null deliberately, when the deployment genuinely serves the UI from such a context (e.g. the UI is opened as a local file:// page, or embedded in a sandboxed iframe without allow-same-origin); otherwise prefer a normal named origin, or add allow-same-origin to sandboxed embeds and use the real origin where possible.
  • The upstream Content-Type header 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 below 0x20 or DEL 0x7f, e.g. CR/LF) is rejected with HTTP 502 ("TTS server returned invalid content type"), blocking header-injection / response-splitting. A value that is not audio/* returns HTTP 502 ("TTS server returned non-audio content"), and a non-allow-listed audio/* sub-type safely falls back to audio/wav instead 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-front Content-Length check 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 no Content-Length header.
  • 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-server endpoint returns the resolved default server URL ({"url": ...}, or null when 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).

Template-to-JavaScript interpolation

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).

HTML escaping in templates

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.

Project Structure

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

Pages

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)

API Integration

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.

Development

Rebuilding CSS

If you modify TailwindCSS classes:

./build-css.sh

Adding New Pages

  1. Create a new template in app/templates/
  2. Add a route in app/main.py
  3. Extend base.html for consistent navigation

Testing

Tests live in unittests/ and are run with pytest:

# Run the test suite
pytest

# Run with coverage
pytest --cov=app

The 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.

Docker Details

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 uvicorn in the foreground as PID 1 via exec in entrypoint.sh, so the server receives SIGTERM/SIGINT for 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-metal app.main default of 127.0.0.1) so docker run -p 8080:8080 is reachable out of the box; set SERENDIPITY_WEBUI_HOST=127.0.0.1 for loopback-only. Because a wildcard bind leaves the startup TTS allow-list empty, operators exposing the container should set SERENDIPITY_WEBUI_ALLOWED_ORIGINS explicitly (the empty-list fallback only accepts an IP-literal or localhost Host; a DNS hostname is rejected).

License

This project is licensed under the MIT License - see the LICENSE file for details.

About

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.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages