Skip to content

Self-Contained Demo Stack

The demo/ directory is a portable example distribution built around langgraph-openai-serve. It contains independently locked applications, client integrations, gateway configuration, and a complete Compose stack.

Watch the demo showcase

Watch the complete demo showcase to see the demo stack in action.

Package and demo have different owners

The PyPI package provides the OpenAI-compatible server integration. It contains no built-in graph, UI, gateway, database, or runnable application. Everything described in this section belongs to demo/ and can be copied or operated independently of the package source checkout with published images. The development Compose override intentionally uses the parent checkout as an editable API dependency.

  • Run the API

    Start PostgreSQL and call the example graphs through an OpenAI client.

    Run the API

  • Run the Files API

    Start the independent OpenAI Files service backed by S3-compatible storage.

    Run the Files API

  • Understand the architecture

    See service ownership, request routing, and persistence boundaries.

    Demo architecture

  • Explore the graphs

    Compare schema adapters, RAG, citations, stream-event filtering, file output, subgraphs, HITL, and polling-only background execution.

    Example graphs

  • Run the complete stack

    Use published images or build the demo applications with an editable LGOS checkout.

    Docker Compose

  • Use Chainlit

    Responses, model discovery, Chat Settings, persistence, login, and HITL.

    Use Chainlit

  • Use Open WebUI

    A Responses manifold Pipe with each graph's description and settings form.

    Use Open WebUI

  • Route through Bifrost

    Select the native UI inference path and inspect its pinned compatibility boundary.

    Bifrost gateway

  • :material-gateway:{ .lg .middle } Use the LiteLLM edge

    Select the managed UI inference route, native model metadata, and compatibility tests.

    LiteLLM in Compose

  • Observe the stack

    Add the optional Collector overlay without changing the LGOS package. For the surrounding self-hosted infrastructure, use the separate reference page.

    OpenTelemetry overlay

    Self-hosted service references

Components

Component Demo-owned responsibility Distribution
Demo APIs Two FastAPI graph services that may expose different graph sets One independent uv project; Compose runs the lgos-demo-api image twice
Background worker Runs Hatchet background tasks outside the API process with a fixed slot count Optional background Compose profile using the demo API image and Hatchet
Files API Shared OpenAI file namespace and S3 persistence Independent uv project and lgos-files-api image
Chainlit Persistent Responses client, native MCP sessions, login, settings UI, file display, HITL UI, dictation, and read-aloud Independent uv project and lgos-chainlit image
Open WebUI Responses manifold, runtime model info and settings forms, native MCP tools, and native voice The pinned homeserver-open-webui image with a mounted app factory that installs the Functions at startup
Bifrost Shared model catalog plus provider-selected native OpenAI routing Compose configuration with the official image
LiteLLM Managed UI inference and native /model/info metadata Pinned public homeserver-litellm image and Compose configuration
DBHub Six fixed read-only reports over curated live-data PostgreSQL views Pinned official image and demo-owned TOML configuration
PostgreSQL Thread-scoped graph data, pending interrupts, cross-worker interrupt coordination, and Chainlit persistence Official image with a demo-owned bind directory
S3-compatible storage Files API objects and separate Chainlit element bodies External endpoint with independently configured buckets

Only the graph API project imports langgraph-openai-serve. The Files API implements its independent OpenAI Files contract without importing LGOS. Chainlit and Open WebUI exercise the graph API's OpenAI wire contract without importing the package. OPENAI_GATEWAY_TYPE=litellm|bifrost selects their shared edge. Responses and Files use its normal managed/native routes. LiteLLM metadata comes from /model/info after model sync; Bifrost uses native /v1/models after catalog sync.

Pinned managed-routing limitations

The bundled Bifrost native Responses route preserves phase, commentary, file-input, continuation, store: false, and upstream error metadata; normalized model detail remains a strict expected failure. The bundled homeserver-litellm image preserves native streaming and commentary. Standard error metadata remains rewritten. Direct LGOS remains the protocol reference. The UIs use the selected gateway's normal inference route and accept that route's documented limitations; see Docker Compose and Bifrost Gateway for the precise boundaries.

Both bundled gateways support polling-only background work through their normal Responses paths. Hatchet stores each run's status and Response. See the background guide.

Client Capabilities

Demo client File input MCP Runtime settings Interrupts Background UI feedback Citations
Chainlit Uploads attachments to the central Files API Per-session trusted native Streamable HTTP connection Renders supported discovered fields Native choices and free-text input with a durable continuation record Capability-gated switch and polling Native status and persisted image elements Markdown content
Open WebUI Uploads attachments to the central Files API One Compose-configured gateway connection selected from discovered mcp_tools metadata Renders supported discovered fields as Chat Variables Persisted native ask_user card with LGOS continuation Capability-gated Chat Variable and polling Native status and persisted file events Native source events and Markdown

Both clients still expose limited-functionality models when LGOS metadata is missing; see their client-specific guides for that behavior.

Ordinary graph conversations work through an OpenAI SDK without a demo adapter. An interrupt uses standard Responses function calls, but a client application must recognize lgos_interrupt, collect human answers, and return each call ID in a function_call_output item with previous_response_id. The Chainlit and Open WebUI adapters show that client behavior without importing LGOS. See OpenAI Clients.

Persistence Boundary

The UI owns chat history. LGOS stores resumable interrupt state and explicit thread-scoped application data, not the transcript; Hatchet stores background runs. PostgreSQL provides the checkpointer, LangGraph store, and cross-worker interrupt coordination, with no Redis service. See Persistent Plot Agent for Store and UI ownership, Interruptible Human Review for the server lifecycle, Background Mock for the separately deployed worker, and OpenAI Compatibility for the normative continuation and retention contract.

Chainlit persists the paused Response ID and exact interrupt calls in a pending interrupt record with a documented crash window. Open WebUI persists its native ask_user card, which carries the paused Response ID and interrupt call IDs, on the assistant message. Their exact recovery boundaries are documented on the Chainlit and Open WebUI pages.

For exact commands and environment ownership, use Demo Settings and Commands. To build your own application, get started with the package.