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

> Easily set up Feynman for the first time with our complete installation guide. Run a simple command and follow the guided wizard to configure your AI model provider and API keys.

- Repository: [Advait Paliwal/feynman](https://github.com/advaitpaliwal/feynman)
- Tags: getting-started
- Published: 2026-09-08

---

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

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

```

This script, defined in [`scripts/install/install.sh`](https://github.com/advaitpaliwal/feynman/blob/main/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:

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

```

## Running the First-Time Setup Wizard

After installation completes, launch the guided configuration wizard:

```bash
feynman setup

```

The setup wizard, referenced in the [`README.md`](https://github.com/advaitpaliwal/feynman/blob/main/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:

```bash

# 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`](https://github.com/advaitpaliwal/feynman/blob/main/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:

```bash
feynman version

```

To refresh the bundled Pi packages without reinstalling the binary:

```bash
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:

```bash
feynman serve

```

This opens `http://localhost:3000` by default, loading the React application entry point at [`workbench-web/src/main.tsx`](https://github.com/advaitpaliwal/feynman/blob/main/workbench-web/src/main.tsx). For trusted local testing without authentication, use:

```bash
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`](https://github.com/advaitpaliwal/feynman/blob/main/package.json)), loads the core Pi packages (coding-agent, extensions, skills), and initializes the alphaXiv agents. Each sub-agent—documented in [`AGENTS.md`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/AGENTS.md) (researcher, reviewer, writer, verifier) while omitting the workbench web interface entry point at [`workbench-web/src/main.tsx`](https://github.com/advaitpaliwal/feynman/blob/main/workbench-web/src/main.tsx).