5. Cloud & headless deployment

LatticeMind is designed to run on cloud platforms, HPC login nodes, and notebook services such as qBraid and JupyterHub.

5.1. Running the Web UI on a server

Serve the web console without opening a local browser, and reach it through the platform’s proxy:

latticemind-web --port 7865 --no-open

The equivalent environment configuration:

export LATTICEMIND_CLOUD_MODE=1
export LATTICEMIND_WEB_PORT=7865
export LATTICEMIND_WEB_OPEN_BROWSER=0
export LATTICEMIND_ARTIFACTS_DIR=/persistent/latticemind_outputs
latticemind-web

By default the project is the folder you start LatticeMind in (or the folder you choose on the browser’s setup card). LATTICEMIND_ARTIFACTS_DIR overrides that, which is useful when only one volume survives a container restart.

5.2. Cloud checklist

Concern	Recommendation
Secrets	Prefer real environment variables or your platform’s secret store over a committed `.env`.
Persistent results	Start LatticeMind in a folder on a persistent volume, or set `LATTICEMIND_ARTIFACTS_DIR` to one, so projects survive container restarts.
No browser	Nothing to change: `latticemind` starts the conversation in the terminal. If you do have a browser, `latticemind-web` opens the web console instead.
Behind a proxy	The UI uses relative asset and API URLs by default, so most proxies work as-is (see below).

5.3. qBraid / Jupyter proxy quickstart

Set credentials in a notebook cell or terminal:

export OPENAI_API_KEY=...
export LATTICEMIND_CLOUD_MODE=1

Start the web console:
```
latticemind-web --port 7865 --no-open
```
Open the proxied URL for port 7865. Use the form <notebook-base>/proxy/7865/ — the trailing slash is required so that relative paths like static/styles.css and api/config resolve under the proxy prefix.

If HTML loads but CSS or live updates do not, the proxy needs an explicit base path:

export LATTICEMIND_WEB_BASE_PATH=/proxy/7865
latticemind-web --port 7865 --no-open

5.4. Working inside an existing folder

On cloud and notebook platforms you usually already have a working directory. Change into the folder you want the work to live in and start LatticeMind there: that folder is the project, and everything it writes stays inside it.

cd my-silicon-study
latticemind

/whereami shows the project folder, the model and who answers launch requests. On a container whose home directory is not persistent, set LATTICEMIND_ARTIFACTS_DIR to a persistent volume.

5.5. Choosing where calculations run

Small validation runs are fine in the notebook container. For anything expensive — dense k/q grids, relaxations, DFPT, phonons, optics — run on an HPC cluster via a remote profile (see Remote & HPC execution). /remote lists your profiles and + adds one; choose it with /remote <profile>. The conversation stays in the notebook, and the permission question before each launch names that host and its remote directory, so you can see where the work is going before it goes.

5.6. A safe first cloud calculation

Type the request:

Do a simple SCF and band structure calculation for silicon.

LatticeMind builds the structure, writes the inputs and validates them, then shows exactly what it will run and where and asks:

1. yes   2. yes, always   3. no

Answer with a number or in words — yes, go ahead, or no, cancel. Nothing reaches the solver until you do. To look the inputs over first, ask for that:

Prepare the inputs for this but do not run anything yet.

Then, when they look right:

Run the SCF and band structure and plot the bands.

/report then writes the evidence report under results/.