Web UI
======

Use the web interface for ChatGPT-style interaction in your local environment. 

The Web UI is built with `Chainlit <https://chainlit.io/>`_ and provides a user-friendly interface for chatting with your installed **FermiLink** packages.


Fast path (recommended)
-----------------------

If you have already completed :doc:`installation`, this is the only workflow you
need to get the Web UI running.

.. code-block:: bash

   fermilink start

Then your browser will automatically open the following webpage:

.. figure:: _static/img/web_ui_entry.png
   :alt: FermiLink web UI.
   :align: center
   :width: 95%

**Sign UP** with an account and then **Sign In**. You can then enjoy a ChatGPT-style interface with the same agent capabilities as the terminal, but with better interactivity and visualization support.

.. code-block:: text

   /package list

to check the locally installed packages for **FermiLink**. If you see installed packages in the list, you are ready to chat. If you did not install any packages yet, install one with:

.. code-block:: bash

   fermilink avail <package_id>
   fermilink install <package_id> --activate


What ``fermilink start`` launches
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``fermilink start`` launches two local processes:

- **runner**: FastAPI execution backend (default: ``http://127.0.0.1:8000``)
- **web**: Chainlit Web UI (default: ``http://127.0.0.1:7860``)

Service logs are written under ``$FERMILINK_RUNTIME_ROOT/logs/``.

Start, stop, and check web UI status
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you need to stop or restart the services, use the following commands:

.. code-block:: bash

   # start the local runner + web UI
   fermilink start

   # check status
   fermilink status

   # restart services
   fermilink restart

   # stop services
   fermilink stop


Where your work lives
~~~~~~~~~~~~~~~~~~~~~~~

In Web UI mode, each chat message runs inside a session workspace repo under::

  $FERMILINK_WORKSPACES_ROOT/<session_id>/repo

The default ``$FERMILINK_WORKSPACES_ROOT`` path is ``~/.fermilink/``.

Inside each chat thread, you can find:

- ``projects/memory.md``: unified short-term/long-term memory used across turns
- ``projects/``: place for simulation folders and reports

To find recent workspaces on disk:

.. code-block:: bash

   FERMILINK_WORKSPACES_ROOT=$HOME/.fermilink/workspaces
   ls -t "$FERMILINK_WORKSPACES_ROOT" | head

Then inspect one session:

.. code-block:: bash

   ls "$FERMILINK_WORKSPACES_ROOT/<session_id>/repo"

Troubleshooting (common first-run issues)
-----------------------------------------

- **Web UI shows no packages**:
  install at least one package and activate it::

    fermilink install <package_id> --activate

- **Runner fails with a provider error**:
  ensure the active provider CLI (``codex``, ``claude``, ``gemini``, or
  ``opencode``) is on ``PATH`` and authenticated, then restart.
  
  You can check or change provider
  selection with ``fermilink agent``::

    # check current provider and reasoning effort
    fermilink agent --json

    # switch to Codex with high reasoning effort
    fermilink agent codex --sandbox --model gpt-5.3-codex --reasoning-effort xhigh

    # switch to Claude with relaxed sandbox for better performance
    fermilink agent claude --bypass-sandbox --model sonnet --reasoning-effort high

    # switch to Gemini
    fermilink agent gemini --sandbox --model auto-gemini-3 --reasoning-effort high

    # switch to OpenCode with a configured provider/model profile
    fermilink agent opencode --bypass-sandbox --model openai/gpt-5.5 --reasoning-effort xhigh

    # restart the web UI service of FermiLink to apply the new provider settings
    fermilink restart

- **Ports already in use**:
  stop the conflicting process, or override the commands (see below).

Package selection inside the UI
-------------------------------

**FermiLink** routes each message to an installed package (keyword router + optional
second-guess preflight). You can also pin a package for the current chat.

Use ``/package help`` in the UI for the built-in command list. The most common
commands are:

.. code-block:: text

   /package list
   /package current
   /package use meep
   /package auto on
   /package auto off
   /package clear

Notes:

- Auto routing is per-chat; it can switch packages between turns when enabled.
- Manual ``/package use ...`` pins always take precedence until you clear them.
- If you see "no packages", install one with ``fermilink install <id> --activate``.
- Generated figures/documents are attached from either referenced paths in the
  assistant reply or detected created/updated files under the workspace artifact
  directories.

Advanced: override ports/hosts (optional)
-----------------------------------------

To override host/port without editing code, set command overrides:

.. code-block:: bash

   export FERMILINK_RUNNER_CMD="uvicorn fermilink.runner.app:app --host 127.0.0.1 --port 8000"
   export FERMILINK_WEB_CMD="chainlit run src/fermilink/web/app.py --host 127.0.0.1 --port 7860"

Then start normally:

.. code-block:: bash

   fermilink start


Advanced: accounts and signup
-----------------------------

The Web UI uses password authentication and supports multiple accounts. You can manage accounts with the following commands:

Common controls:

- ``FERMILINK_AUTH_SIGNUP_ENABLED``: allow self-signup (default: true)
- ``FERMILINK_AUTH_AUTO_REGISTER``: auto-create a user record on first login
  (default: false; convenient for single-user/local setups)
- ``FERMILINK_AUTH_MAX_USERS``: cap the number of accounts (``0`` means unlimited)
- ``FERMILINK_AUTH_MIN_PASSWORD_LEN``: minimum password length (default: 8)

To keep sessions stable across restarts, optionally set a persistent secret:

.. code-block:: bash

   export FERMILINK_CHAINLIT_AUTH_SECRET="<random-secret>"

Advanced: Host this web UI for your team or class
--------------------------------------------------

We have tested that this Web service can be hosted on a server and accessed remotely with a proper IP adress or domain name. This might be useful for teaching purposes or team collaboration.


See also
--------

- :doc:`installation` for full setup.
- :doc:`configuration` for runtime variables.
- :doc:`scientific_packages` for package install/compile/recompile workflows.
- :doc:`architecture` for request flow and streaming contracts.