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 Laptop Tutorial for a practical tutorial on using FermiLink on local machines.

  • HPC users, please also check out the HPC Tutorial for step-by-step instructions on running FermiLink on HPC systems.

Fast path

# 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 Command Line Tools, Web UI, and Chat 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)

# 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:

# Codex
codex login
# Claude
claude
# Gemini
gemini

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.

# 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.

# 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:

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