Local DeepLynx install¶
The platform stores agent artifacts in DeepLynx. Instead of a shared DeepLynx server, you can run one next to the platform, either from the published images (the quickest way) or built from the DeepLynx source.
With the platform, from the published images¶
DeepLynx publishes its server and web UI as images under
ghcr.io/idaholab/deeplynx/. With LOCAL_DEEPLYNX=true the platform starts
them alongside everything else (docker-compose.deeplynx.yml) and configures
itself to use them, so there is nothing to build or click through. The first
make up asks "Run DeepLynx locally (LOCAL_DEEPLYNX)?" in a terminal, until
.env has the line: Enter answers yes. Or set the line in .env yourself, and
start the platform:
cd platform
# in .env: LOCAL_DEEPLYNX=true
make up
Before the rest of the platform starts, every start target (make up,
make restart, ...) runs make deeplynx-setup, which
- starts DeepLynx's database, server and web UI and waits until they're up,
- creates a project named "Prometheus" in the default organization and an API key for it, through the DeepLynx API, and
- saves them in
.env:DEEPLYNX_BASE_URL=http://deeplynx-server:5000/api/v1(the server on the platform's network),DEEPLYNX_KEY,DEEPLYNX_SECRET,DEEPLYNX_ORG_IDandDEEPLYNX_PROJECT_ID. Any DeepLynx settings already in.envare replaced.
Once that key works it is kept, so later starts change nothing. make down-v
deletes DeepLynx's data along with the platform's, and the next start sets it
up again.
The web UI is at http://localhost:3000 and the API at
http://localhost:5000/api/v1. Both run with authentication disabled, as the
"Local Developer" user, so this is for local use only: both ports are published
on 127.0.0.1, so only your own machine reaches them, not other devices on
your network. DEEPLYNX_UI_PORT and
DEEPLYNX_SERVER_PORT move them to other host ports, but the UI only works
with the API on port 5000: the browser's API address is built into the UI
image. The images don't include DeepLynx's optional document ingestion
service (Insight).
The image tag is pinned in docker-compose.deeplynx.yml. The images are built
from DeepLynx releases by the build-images workflow in the DeepLynx
repository.
On its own, built from source¶
To run DeepLynx separately from the platform, for example to work on DeepLynx itself, build it from its repository and set the platform up by hand.
Clone the DeepLynx repository¶
git clone https://github.com/idaholab/DeepLynx.git
Build the docker containers¶
cd DeepLynx
cp .env_sample .env
docker compose build
Start DeepLynx¶
docker compose up
This starts two services: the web UI (admin GUI) at http://localhost:3000/, which you use for the setup steps below, and the API at http://localhost:5000/api/v1, which the Prometheus platform talks to.
Set up a project¶
When you open DeepLynx you are greeted with a quick tour. Take it or skip it.

Next you must select an organization from the top left drop down menu. Choose "INL - default organization".

This organization is still completely empty, click on the "+ Project" button to create a project (think of it as a fenced-off database that you will utilize for the Prometheus Platform).

Give the project a name (any name will do).

Take or skip the quick tour. Note that the URL of the page now shows localhost:3000/project/1. 1 is the project ID of the project you just created (you can create more projects, note how they will all have different IDs).

Next, in the bottom left click on the person icon and in the pop up menu under Local Developer click "Settings" (important, do not confuse this with the organization settings in the far left bar).

On the Settings page scroll down to the "API Keys" section and click "+ Generate New".

A popup will appear with a key and a secret — copy both now. This is the only time you will be able to see the secret!
Configure the platform to use the local DeepLynx¶
As noted above, the API (not the web UI on port 3000) is exposed on the host at http://localhost:5000/api/v1, on the loopback interface only. From inside the Prometheus platform containers that host is available as prometheus.host.internal (mapped to Docker's host gateway). On Docker Desktop (macOS, Windows) that reaches the loopback port. On Docker Engine for Linux the host gateway is the bridge address, so it may be refused; use the make up setup with LOCAL_DEEPLYNX=true instead (it reaches deeplynx-server by name), or publish the port on that address yourself in docker-compose.override.yml. Set
DEEPLYNX_KEY=...
DEEPLYNX_SECRET=...
DEEPLYNX_BASE_URL=http://prometheus.host.internal:5000/api/v1/
DEEPLYNX_ORG_ID=1
DEEPLYNX_PROJECT_ID=1
and fill in the key and secret you just generated (and adjust the project ID if you created multiple projects and want to use a specific project).