Installation
============

The following instructions will guide you through the installation of FermiLink, a framework for autonomous scientific simulation and research.

- Laptop and workstation users, check out the :doc:`tutorial_laptop` for a practical tutorial on using FermiLink on local machines.
- HPC users, please also check out the :doc:`tutorial_hpc` for step-by-step instructions on running FermiLink on HPC systems.

Fast path 
------------

.. code-block:: bash

   # 1. Install FermiLink 
   pip install fermilink

   # 2. Start the guided beginner entrypoint
   fermilink

   # 3. Or, follow the manual setup path below:
   # Install and authenticate one supported agent provider CLI (Codex/Claude/Gemini)
   # For example, Codex option:
   npm i -g @openai/codex   # Use ``brew install codex`` for Mac
   codex login

   # 4. Install at least one scientific package
   fermilink install meep

   # 5.1. Command line execution (most powerful)
   fermilink exec/loop/research/reproduce "..."

   # 5.2. Start the web UI for chatgpt-like experience (laptops and workstations)
   fermilink start

   # 5.3. Connect to Telegram chatbot (suitable for HPC with no sudo access)
   export FERMILINK_GATEWAY_TELEGRAM_TOKEN="<token-from-@BotFather>"
   export FERMILINK_GATEWAY_TELEGRAM_ALLOW_FROM="<numeric-id-from-@get_telegram_id_smppcenter_bot>"
   fermilink gateway

See also :doc:`usage`, :doc:`usage_web_ui`, and :doc:`usage_chatting_apps` for more details about the three user interfaces.


Complete installation guide
-----------------------------

Below are **more detailed instructions for each step**, as well as some optional configurations for users with specific needs.

Prerequisites
~~~~~~~~~~~~~~~~

FermiLink assumes a standard local developer environment:

- Python ``>= 3.11``
- ``git`` on ``PATH`` (workspaces are git repos)
- Node.js + ``npm`` (commonly used for local agent provider CLIs) or ``homebrew`` installed for Mac
- Supported provider CLI on ``PATH``: Codex (``codex``) or Claude (``claude``) or Gemini (``gemini``)

.. note::

   For HPC users without sudo access, you need to install Node.js and ``npm`` locally first.

Install provider CLI (Codex or Claude or Gemini)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   # Codex option
   npm i -g @openai/codex  # Use ``brew install codex`` for Mac
   # install Claude / Gemini CLI from its official distribution

Provider authentication
~~~~~~~~~~~~~~~~~~~~~~~~~

Authenticate the provider you selected **before** starting web UI services or running
``fermilink exec/chat/loop/research/reproduce``.

Example login commands:

.. code-block:: bash

   # Codex
   codex login
   # Claude
   claude
   # Gemini
   gemini

Install FermiLink
~~~~~~~~~~~~~~~~~~

You can install FermiLink with pip:

.. code-block:: bash

   pip install fermilink



Install your first scientific package knowledge base
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Before an agent run, FermiLink selects a scientific package into
the workspace (default path: ``~/.fermilink/scientific_packages/``) based on user's request. This requires to install at least one package first.

.. code-block:: bash

   # discover packages in the default curated channel (https://github.com/orgs/skilled-scipkg/repositories)
   fermilink avail meep

   # install one or more packages
   fermilink install meep --activate
   fermilink install lammps

   # verify locally installed packages
   fermilink list

``--activate`` sets the default package for new sessions. You can switch later
with ``fermilink activate <package_id>``. 

Note that ``fermilink install`` only downloads 
the package knowledge base (source code tree + agent skills) to ``FERMILINK_SCIPKG_ROOT`` (default path: ``~/.fermilink/scientific_packages/``) but 
**does not really install the package for execution**. 

It is always recommended that the users have already installed the packages
in their machines, but agents can install the packages by themselves if they find the relavent package is not installed or cannot run.

Agent runtime policy
~~~~~~~~~~~~~~~~~~~~~~~

By default, FermiLink agents run in a sandbox mode where they can only execute code in a local directory and cannot access the external file system or network. This is to prevent potential security risks from executing arbitrary code generated by AI agents. 

However, some scientific simulations may require access to external files, network resources, or MPI runs on local machines. In such cases, users can **bypass the sandbox mode** using the command line tool. Note that bypassing sandbox mode may expose the local system to **potential security risks**, although FermiLink has implemented safety measures to mitigate these risks.

.. code-block:: bash

   # show current policy
   fermilink agent --json

   # enforce sandbox mode (default), codex provider
   fermilink agent codex --sandbox --model gpt-5.3-codex --reasoning-effort xhigh

   # bypass sandbox (which might be needed for local MPI jobs)
   fermilink agent codex --bypass-sandbox --model gpt-5.3-codex --reasoning-effort xhigh

   # bypass sandbox for claude
   fermilink agent claude --bypass-sandbox --model sonnet --reasoning-effort high

.. warning::

   When ``fermilink agent --bypass-sandbox`` is needed for maximal functionality, **NEVER run it as a root user.** 


Developer mode
-------------------

Users can install FermiLink in the developer mode to modify the source code and test the changes locally. This is recommended for users who want to contribute to the project or customize the framework for their own use cases. 

To install FermiLink in the developer mode, run the following command:

.. code-block:: bash

   git clone git@github.com:TaoELi/FermiLink.git
   cd FermiLink
   pip install -e ".[dev]"