How to Set Up Feynman for the First Time: Complete Installation Guide

Run curl -fsSL https://feynman.is/install | bash to download the native bundle, then execute feynman setup to configure your model provider and API keys through the guided wizard.

Feynman is an open-source AI research assistant that integrates a multi-agent runtime with academic paper analysis capabilities. This guide walks you through the complete first-time setup process using the official installer scripts from the advaitpaliwal/feynman repository.

What Is Feynman?

Feynman operates as a stand-alone native bundle built on three core components. Pi serves as the multi-agent runtime powering sub-agents, package loading, and skill execution. alphaXiv provides the paper-search and analysis backend for fetching citations and full-text content. The Feynman CLI and Workbench provide a command-line interface and browser-based UI for managing research notebooks, artifact previews, and provenance tracking.

Installing the Native Bundle

The official installer handles binary download, SHA-256 checksum verification, and extraction automatically.

macOS and Linux

Execute the one-line installer to fetch the latest tagged release:

curl -fsSL https://feynman.is/install | bash

This script, defined in scripts/install/install.sh, downloads the bundled Node.js runtime together with the Feynman binary and places the executable on your system $PATH.

Windows

For Windows environments, use the PowerShell equivalent:

irm https://feynman.is/install.ps1 | iex

Running the First-Time Setup Wizard

After installation completes, launch the guided configuration wizard:

feynman setup

The setup wizard, referenced in the README.md (lines 166-170), prompts you to select a model provider such as LM Studio, LiteLLM, or Ollama. It securely stores required API keys and configuration files under the ~/.feynman directory.

Alternative Installation Methods

Skills-Only Installation

If you require only the research skill stack without the browser-based workbench UI, use the skills-only installer. This drops the skill tree into ~/.codex/skills/feynman (or a local .agents/skills/feynman directory) without installing the native binary wrapper:

# macOS / Linux

curl -fsSL https://feynman.is/install-skills | bash

# Windows PowerShell

irm https://feynman.is/install-skills.ps1 | iex

The skills-only installer is defined in scripts/install/install-skills.sh and leverages the same Pi runtime workspace preparation found in scripts/prepare-runtime-workspace.mjs.

Verifying Your Installation

Confirm the installation and check the bundled version information:

feynman version

To refresh the bundled Pi packages without reinstalling the binary:

feynman update

All artifacts, sessions, and the SQLite provenance ledger (feynman-workbench.db) are stored under ~/.feynman. To upgrade the native application later, simply rerun the original installer script.

Launching the Workbench UI

Start the browser-based research environment:

feynman serve

This opens http://localhost:3000 by default, loading the React application entry point at workbench-web/src/main.tsx. For trusted local testing without authentication, use:

feynman serve --no-auth

Understanding the Architecture

When you invoke feynman commands, the CLI boots the embedded Pi runtime defined in the package configuration (package.json), loads the core Pi packages (coding-agent, extensions, skills), and initializes the alphaXiv agents. Each sub-agent—documented in AGENTS.md—runs in isolation and communicates via Pi’s RPC layer. Research artifacts are indexed in the SQLite ledger for reproducibility and provenance tracking.

Summary

• Download the native bundle using the official installer script (scripts/install/install.sh) which handles checksum verification automatically.
• Configure your environment by running feynman setup to set model providers and API keys in ~/.feynman.
• Alternative installations allow deploying only the skill library via install-skills.sh for headless research workflows.
• Verify installation health with feynman version and update Pi packages using feynman update.
• Launch the workbench UI with feynman serve to access the full React-based interface at workbench-web/src/main.tsx.

Frequently Asked Questions

What operating systems does Feynman support?

Feynman provides native installers for macOS, Linux, and Windows. The macOS and Linux installer uses a bash script (install.sh), while Windows users execute a PowerShell script (install.ps1). Both platforms receive the same bundled Node.js runtime and Feynman binary.

Where does Feynman store configuration and data?

All configuration files, API keys, and session data reside in the ~/.feynman directory. The workbench UI maintains a SQLite ledger named feynman-workbench.db within this directory to track provenance and research artifacts. Skills installed via the skills-only method populate ~/.codex/skills/feynman.

How do I update Feynman to the latest version?

Refresh bundled Pi packages by running feynman update. To upgrade the native binary itself, rerun the original installation command (curl -fsSL https://feynman.is/install | bash), which downloads the latest tagged release and replaces the existing executable while preserving your ~/.feynman configuration.

Can I use Feynman without the browser-based UI?

Yes, use the skills-only installation method to deploy research capabilities as command-line tools without the React frontend. This installs the Pi runtime and agent skills defined in AGENTS.md (researcher, reviewer, writer, verifier) while omitting the workbench web interface entry point at workbench-web/src/main.tsx.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}