Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt

Use this file to discover all available pages before exploring further.

Observatory ships as a set of containers you can bring up together. This guide is the fastest path from zero to a running platform you can point the SDK at.

​
Prerequisites

  • Docker 24+ and Docker Compose v2
  • 8 GB RAM available for containers
  • 20 GB disk available for PostgreSQL data
  • Network access to the upstream LLM providers you intend to use
The default Compose stack includes:
ServicePortPurpose
observatory-api8091FastAPI backend
observatory-web4900Angular dashboard
observatory-platform8092Platform service (organizations, RBAC, Kubernetes integration)
observatory-db5432PostgreSQL with pgvector
observatory-docs4903Bundled docs site
Observatory authenticates against an external FlowX identity provider (Keycloak) — it is not bundled in the Compose stack. Point SECURITY_OAUTH2_* / KEYCLOAK_* at your auth server.

​
Steps

1

Clone the repo

git clone --recurse-submodules git@github.com:flowx-ai/observatory2.0.git
cd observatory2.0
The submodules carry the API, web, platform, and SDK source. If you forgot --recurse-submodules, run:
git submodule update --init --recursive
2

Create the network

The platform expects an external Docker network shared with other FlowX services:
docker network create ai-services_node-network 2>/dev/null || true
3

Configure the .env file

Copy the example and edit the placeholders:
cp observatory-api/env.example observatory-api/.env
At minimum set OPENAI_API_KEY (or your provider equivalent), the SECURITY_OAUTH2_* values for your identity provider, and any custom LLM endpoints. See Environment variables for the full table.
4

Bring up the stack

docker compose up -d --build
First start takes a few minutes — the databases initialise and schemas are created.
docker compose ps shows all services in state Up or healthy.
5

Confirm the web UI

Open http://localhost:4900. You should see the login page. Sign in with credentials from your FlowX identity provider.
6

Confirm the API

curl http://localhost:8091/health
A {"status": "ok"} response means the API is reachable. The /docs endpoint serves the OpenAPI explorer.

​
Rebuilding after code changes

When you edit source code in a submodule, always rebuild — restarting alone won’t pick up the changes: 
docker compose up -d --build
docker compose restart does not rebuild images. Always use up -d --build after touching service code.

​
Persistence

The Compose stack persists:
  • pgdata volume — all telemetry, evidence, runs
  • hf_hub volume — cached model files
Both survive docker compose down. To wipe the platform back to factory state: 
docker compose down -v

​
Production deployment

The Compose stack is for development and evaluation. For production, see the Kubernetes manifests under deployment/ and the deployment guide in the repo. Notable production-only concerns:
  • Configure persistent volumes for the database
  • Set up TLS at the ingress layer
  • Point auth at your production identity provider

​
Troubleshooting

Most often a missing port name in the service definition. Confirm observatory-api is reachable on port 8091 from the observatory-web container with docker compose exec observatory-web curl http://observatory-api:8091/health.
The init script in init_dbs/multiple-databases.sh creates the companion databases on first start. If it didn’t run, your existing pgdata volume is from an older build. Wipe and start over: docker compose down -v && docker compose up -d --build.
FLOWX_OBSERVATORY_API_URL must be http://localhost:8091 for a host-machine app, not http://observatory-api:8091 (which only resolves inside the Docker network).

Environment variables

Full reference for every env var the platform reads.

Getting started

Once the platform is up, instrument your first agent.
Last modified on June 2, 2026