Docker Compose¶

demo/docker/compose/demo.yml uses published images for the demo API, Files API, and UIs. The coding-agent service builds locally:

just demo/compose

The command starts the gateway first, then the LGOS services, including Chainlit and DBHub, which assume it is running. It syncs metadata into the selected gateway, then starts Open WebUI. Services remain running in the background. Compose owns dependency order and readiness; just only sequences the repeatable sync jobs.

Set DEMO_IMAGE_TAG in demo/.env to select one release tag for the published project-owned demo images. To add the published OTEL overlay, use just demo/compose --otel.

Apply the explicit development model from the LGOS repository checkout. The demo API, coding-agent API, Files API, and Chainlit services build locally from their Dockerfiles and lockfiles; Open WebUI remains the pinned upstream image. Both graph API images install the parent LGOS checkout as an editable package:

just demo/compose --dev

To add the OTEL overlay while building the current checkout, use just demo/compose --dev --otel.

The development overlay bind-mounts the Python application sources and the parent LGOS package read-only. Restart or recreate the affected service after source edits. Dependency metadata and lockfile changes require an image rebuild.

just demo/compose --dev --chainlit-utils

For immediate local feedback without containers, use uv's temporary editable overlay:

just demo/test --editable

This tests all five projects without changing their dependency declarations or lockfiles. Chainlit and Open WebUI remain standalone clients and exercise whichever API their OpenAI base URL targets.

just demo/up lgos-postgres-mcp --wait

Once the demo API and Chainlit are healthy and have created their tables, the one-shot lgos-mcp-db-setup job creates or updates the dedicated lgos_mcp login and four curated views over live Chainlit users/conversations and pending LGOS interrupts. The role can read only those views. The pinned DBHub service then exposes six fixed reports only inside the Compose network; it publishes no host port. Starting either bundled gateway starts these dependencies, including Chainlit, automatically. Replace LGOS_MCP_DB_PASSWORD and LGOS_MCP_AUTH_TOKEN before startup. See PostgreSQL Through Native MCP for the complete client and security flow.

just demo/up lgos-demo-api
just demo/up lgos-api-coding-agent

Run each attached service in a separate terminal. Compose starts the shared PostgreSQL dependency automatically.

• lgos-demo-api: http://localhost:3004/v1
• lgos-api-coding-agent: gateway access via lgos/coding-agent

For an independently deployed LiteLLM API, run the shared one-shot model-sync job after the deployment's health check.

The worker is an optional Compose profile. Configure a native HATCHET_CLIENT_TOKEN, enable background execution, and add the profile alongside the selected gateway:

# Choose litellm or bifrost.
OPENAI_GATEWAY_TYPE=litellm
COMPOSE_PROFILES=${OPENAI_GATEWAY_TYPE},background
LGOS_BACKGROUND=hatchet
HATCHET_CLIENT_TOKEN=...

Then start the ordered UI stack or only the worker and PostgreSQL:

just demo/compose --dev
# Or: just demo/up lgos-background-worker

The lgos-background-worker process uses explicit Hatchet slots and the same PostgreSQL checkpointer, coordinator, and graph code as the APIs. It publishes no port; Compose checks Hatchet's worker health endpoint on port 8001 inside the container. The API triggers the Hatchet task and reads its status and Response from Hatchet. See Background Mock.

just demo/up lgos-files-api

The independently packaged service connects directly to its configured S3-compatible store. It neither starts PostgreSQL nor imports LGOS.

• central Files API: http://localhost:3006/v1

just demo/compose

The UIs use native /openai/v1/responses, normal /v1 Files routing, the aggregate /mcp endpoint, and native /v1/models metadata. Compose writes zero-priced graph rows and synchronizes descriptions, features, and client settings automatically. Use --dev to build this checkout. The named PostgreSQL Virtual MCP remains available at http://localhost:3000/mcp/lgos-postgres. See Bifrost Gateway for endpoints, routing, and the shared SDK verification command.

Set these values in demo/.env to reuse an existing LiteLLM gateway:

OPENAI_GATEWAY_TYPE=litellm
COMPOSE_PROFILES=
OPENAI_GATEWAY_BASE_URL=https://litellm.example.com
DEMO_GATEWAY_HOST_URL=https://litellm.example.com
OPENAI_GATEWAY_API_KEY=TO_BE_FILLED

Use the gateway root without /v1. Both UIs share the gateway type, base URL, and OPENAI_GATEWAY_API_KEY, or send each user's token with the SSO overlay. An external LiteLLM uses the same Responses, Files, and catalog routes as bundled LiteLLM.

Both UIs derive their MCP endpoint from the same gateway root and use the same credential as Responses and Files. To use mcp-postgres, also adapt the checked-in mcp_servers.lgos_postgres entry and LGOS_MCP_AUTH_TOKEN for the external gateway, just as the Files configuration is adapted below. The external gateway URL must be reachable from both UI containers and from the graph API, worker, and coding-agent containers, which call their models through it. Set DEMO_API_OPENAI_CHAT_COMPLETIONS_MODEL, DEMO_API_OPENAI_RESPONSES_MODEL, DEMO_API_OPENAI_EMBEDDING_MODEL, and the DEMO_AUDIO_* models to IDs that gateway registers. On another host, expose DBHub only on a private address reachable by that gateway.

just demo/compose (or the same command with --dev) starts the demo APIs, Files service, Chainlit, and DBHub, syncs both catalogs to the external LiteLLM, then starts Open WebUI. An empty COMPOSE_PROFILES disables both bundled gateways; the template normally selects one through COMPOSE_PROFILES=${OPENAI_GATEWAY_TYPE}. The external gateway and its administrator credentials must be reachable by the model-sync job.

Enable LiteLLM's native database model storage. For Files, adapt the files_settings in docker/configs/litellm/config.yaml to the shared Files service.

On the same Docker host, attach the existing LiteLLM service to the demo's network through its own Compose deployment, alongside its current networks:

services:
  litellm:
    networks:
      # Retain the service's existing networks here too.
      - lgos

networks:
  lgos:
    external: true
    name: lgos-network

Create the network by starting the demo backends first, for example with just demo/up lgos-demo-api, just demo/up lgos-api-coding-agent, and just demo/up lgos-files-api in separate terminals, then just demo/up lgos-postgres-mcp --wait. The existing gateway can then resolve lgos-demo-api, lgos-api-coding-agent, lgos-files-api, and lgos-postgres-mcp using the bundled sync, Files, and MCP configuration examples. For another host, replace those upstream URLs with addresses reachable from that gateway.

The external deployment continues to own its database, TLS, credentials, and Admin UI SSO. The selected credentials must allow the LGOS models, the DEMO_API_OPENAI_* model IDs the graphs call, Files operations, the configured MCP tools, and native /model/info. Chainlit can enable delegated OAuth; it then sends each user's token instead of the shared static key, MCP included. If the gateway already configures litellm_proxy Files, reconcile that provider with the demo's shared Files namespace. Then run the LiteLLM SDK checks against the external URL.

just demo/up lgos-litellm

LiteLLM is one of the two first-class UI entry points. After startup, sync all graph catalogs. The UIs use:

• model metadata: http://localhost:3000/model/info
• managed Files: http://localhost:3000/v1
• managed routing: http://localhost:3000/v1
• native MCP: http://localhost:3000/mcp
• LiteLLM Admin UI: http://localhost:3000/ui/

The bundled configuration uses API-key authentication. Chainlit can still use OAuth for browser login with that key. OAuth token forwarding additionally requires a gateway configured to validate delegated access tokens through its trusted SSO ingress; enabling forwarding in Chainlit alone does not configure LiteLLM. See Chainlit OAuth.

Chainlit and Open WebUI send Responses and Files to managed routing and read descriptions, capabilities, and settings from model_info.lgos. Each graph uses LiteLLM's model_name unchanged for inference. The proxy retains normal model routing while each API remains the source of its descriptions and LGOS capability metadata and the Files service remains the owner of file bytes. Neither UI connects to an upstream service directly. OPENAI_GATEWAY_API_KEY protects these routes in the default setup; replace its demo-only default in any shared deployment. For the local Admin UI, sign in as admin; unless UI_PASSWORD is set separately, the password is the value of OPENAI_GATEWAY_API_KEY from demo/.env.

The MCP configuration reaches DBHub with the separate internal LGOS_MCP_AUTH_TOKEN, allowlists the six fixed PostgreSQL reports, and permits authenticated gateway keys to use them. Native clients still opt in by connecting to /mcp; the graph API receives only ordinary OpenAI function definitions and results.

The managed-routing surface uses concrete database-backed models and LiteLLM's native Responses endpoint. Select an API with a provider-qualified model, such as lgos/custom-input-output-context. The shared demo PostgreSQL service keeps LiteLLM's Admin UI and gateway-management records in its own litellm schema; graph execution state remains owned by LGOS. LiteLLM's standard files_settings route uses provider=litellm_proxy to isolate upload, retrieval, content, and deletion from the graph deployments.

The LGOS-owned sync reads each API's model list and detail, then registers routing and model_info.lgos through LiteLLM's native management API. New deployments set model_info.supports_native_streaming: true. The default public homeserver-litellm image preserves native Responses streaming and polling-only background lifecycles. Compose reads its tag and digest from DEMO_LITELLM_IMAGE in demo/.env. Normal demo commands use this image without a local build or an image override.

To use another compatible image, set DEMO_LITELLM_IMAGE in demo/.env or supply it on the command line:

DEMO_LITELLM_IMAGE='registry.example.com/team/litellm:tag' \
  just demo/compose --dev --otel

Keep the override set for subsequent Compose commands. To restore the default, copy the image value from demo/.env.example. An alternative image must preserve native Responses streaming and background IDs, authenticated /model/info with custom metadata, managed Files routing, and the Admin UI migration runtime.

Managed routing also passes the tested Files lifecycle, file-ID input, and function continuation, while its rewritten standard error metadata remains a strict expected failure. The bundled image records successful managed Responses requests in LiteLLM's spend logs, including streaming requests. Token and spend values reflect usage and pricing supplied for the selected graph model.

With the service healthy, run the focused OpenAI SDK check from the repository root. It tests managed routing, the catalog-to-inference flow, and native streaming fidelity against the direct LGOS test endpoints:

just demo/test-litellm --editable

With the gateway and its backends running:

just demo/up lgos-chainlit

Chainlit: http://localhost:3002

This command starts Chainlit and PostgreSQL. Use just demo/compose to start the complete stack with the gateway selected by COMPOSE_PROFILES.

Configure its signing secret as described in the Chainlit client.

just demo/up lgos-openwebui --wait

Open WebUI: http://localhost:3003

Compose runs the pinned homeserver-open-webui image. Its startup installs the bundled Functions, and its model list reads each graph's description and settings from the gateway; see the Open WebUI setup. The image keeps chat uploads raw, as described under Open WebUI file input.