Quickstart

Get FermiLink running in 5 minutes. By the end of this page you will have launched your first autonomous simulation with FermiLink.

Note

Prefer a guided walkthrough? Just run fermilink with no arguments after installing. An interactive setup wizard walks you through everything.

2. Set up an AI agent

FermiLink needs an AI agent provider to do the reasoning. Pick one and authenticate:

# Pick one provider:
fermilink agent codex       # OpenAI Codex
fermilink agent claude      # Anthropic Claude
fermilink agent gemini      # Google Gemini
fermilink agent opencode    # OpenCode provider/model profiles

See Choosing an AI Agent for a comparison of providers.

3. Install a scientific package knowledge base

FermiLink ships with 150+ built-in scientific package knowledge bases. Install one relevant to your work:

fermilink install meep           # photonics
fermilink install lammps         # molecular dynamics
fermilink install pyscf          # quantum chemistry
fermilink install openfoam       # CFD

Browse the full package list for all available package knowledge bases.

4. Write your goal.md

Create a file called goal.md in your working directory. This is FermiLink’s primary interface – a plain markdown file describing what you want to compute:

# Goal: Photonic crystal band structure

Simulate the band structure of a 2D triangular lattice of dielectric
rods (r=0.2a, epsilon=12) in air using MEEP/MPB.

## What to compute
- TM and TE band diagrams along Gamma->M->K->Gamma
- Extract the band gap ratio (Delta_omega/omega_mid) for the first gap

## Success criteria
- At least 8 bands converged with resolution >= 32
- Band gap ratio within 5% of published values
- Save final band diagram as `bands.png`

The goal.md tells FermiLink what you want. FermiLink figures out how.

For detailed guidance on writing effective goals, see Writing a goal.md.

5. Run

fermilink loop goal.md

FermiLink then reads your goal, picks the right tools, generates input files, runs simulations, checks results, and iterates until the goal is met.

Choosing the right command

FermiLink offers several commands depending on your workflow:

Command

Best for

Duration

Environment

exec

Quick one-off simulations

Minutes

Laptop / workstation

chat

Interactive conversation with the agent

Hours

Laptop / workstation

loop

Iterative jobs with PID/SLURM monitoring

Hours to days

Workstation / HPC

reproduce

Multi-task paper-scale reproduction

Days to weeks

HPC clusters

research

Multi-task paper-scale research

Days to weeks

HPC clusters

optimize

Code performance tuning (beta)

Hours

Any

If you are not sure how to use FermiLink for your specific needs, simply ask a coding agent:

cp myproject/
fermilink init
codex        # or claude, gemini, opencode

Then ask your coding agent what you want to do. fermilink init will provide all context of FermiLink for agent reasoning.

Next steps