Feynman is an open source AI research agent that ships with its own Node.js runtime. When you run the one-line installer, you get a standalone native bundle that includes everything it needs to execute. No npm install, no version conflicts, no “works on my machine” debugging.
This architectural choice is uncommon for CLI tools but common for desktop apps. It trades disk space for isolation. For agent tools that need to run reliably across heterogeneous environments, that trade-off makes sense.
Why Bundle a Runtime
Most CLI tools assume Node.js is already installed. Feynman does not. The installer fetches a platform-specific bundle with an embedded runtime. This solves three problems:
- Version drift. System Node.js might be v16, v18, or v22. The agent was tested on v20. Bundling guarantees the runtime version.
- Permission boundaries. Installing global npm packages requires elevated privileges or nvm. A standalone bundle can live in user space.
- Dependency isolation. Agent tools often need specific versions of libraries. Sharing a global
node_modulescreates conflicts.
The downside is disk usage. Each installation carries its own runtime, even if the host already has Node.js. For a research agent that runs long-running tasks, the extra 50-100 MB is acceptable.
Installation and Upgrade Paths
Feynman offers two installation modes: full app and skills-only.
Full App Install
The full installer downloads a launcher and runtime bundle:
curl -fsSL https://feynman.is/install | bashOn macOS, this places the launcher in /usr/local/bin/feynman and the runtime bundle in ~/.feynman/runtime. On Windows, the PowerShell installer uses %LOCALAPPDATA%\Feynman.
You can pin a version:
curl -fsSL https://feynman.is/install | bash -s -- 0.2.35To upgrade the runtime bundle, rerun the installer. The feynman update command only refreshes Pi packages (Feynman’s internal plugin system). It does not replace the standalone runtime.
This split creates two upgrade paths:
- Runtime upgrade: Rerun the installer script.
- Package upgrade: Run
feynman update.
The installer script is stateless. It fetches the latest release from GitHub, extracts the bundle, and overwrites the existing installation. No migration logic, no version checks. If you want to roll back, you pin an older version and reinstall.
Skills-Only Install
The skills-only installer puts research capabilities into ~/.codex/skills/feynman without the full terminal app:
curl -fsSL https://feynman.is/install-skills | bashThis mode is for users who already have Codex (another agent runtime) and want to add Feynman’s research skills. The skill library is a set of JavaScript modules that Codex can invoke. No standalone runtime is bundled.
This separation reveals a design pattern: agent capabilities can be packaged independently from execution environments. The full app bundles both. The skills-only mode assumes the host provides the runtime.
Dependency Management
Feynman’s dependency model has three layers:
- Bundled runtime: Node.js and core libraries, managed by the installer.
- Pi packages: Feynman’s plugin system, managed by
feynman update. - User settings: Configuration and session state, stored in
~/.feynman.
Uninstalling requires removing all three:
- Remove the launcher and runtime bundle (platform-specific paths).
- Optionally remove
~/.feynmanto delete settings and sessions. - Optionally remove
~/.ahubto delete alphaXiv login state.
The installer does not provide an uninstall script. You delete the files manually. This is simpler than maintaining uninstall logic but harder to discover.
Local Model Integration
Feynman supports local models through a baseUrl configuration. During setup, you choose a provider:
- LM Studio: Default endpoint is
http://localhost:1234/v1. - LiteLLM Proxy: Default endpoint is
http://localhost:4000/v1. - Ollama or vLLM: Custom provider with
openai-completionsprotocol.
The setup flow writes the baseUrl and API key to ~/.feynman/config.json. The agent runtime reads this file at startup.
This design decouples the agent from the model provider. You can swap LM Studio for Ollama without changing the agent code. The trade-off is that the agent assumes an OpenAI-compatible API. If your local model uses a different protocol, you need a proxy layer.
Security and Patching
Bundling a runtime creates a security obligation. If Node.js releases a CVE patch, the Feynman maintainers must rebuild the bundle and cut a new release. Users must rerun the installer to get the patch.
This is slower than system package managers. On Ubuntu, apt upgrade patches Node.js for all tools at once. With Feynman, you wait for a new release and reinstall manually.
The installer script does not check for updates automatically. You must monitor the GitHub releases page or subscribe to notifications. There is no built-in update checker in the CLI.
For agent tools that handle sensitive data (research notes, API keys, session state), this patching delay is a risk. The isolation benefit of a standalone runtime comes with a maintenance cost.
Deployment Trade-Offs
| Aspect | Standalone Runtime | System Dependency |
|---|---|---|
| Disk usage | 50-100 MB per install | Shared across tools |
| Version control | Guaranteed by bundle | Varies by host |
| Security patching | Requires new release + manual reinstall | Handled by package manager |
| Permission model | User-space install | Often requires sudo or nvm |
| Dependency conflicts | Isolated | Shared global node_modules |
| Upgrade complexity | Two-path (runtime + packages) | Single npm update |
The standalone runtime model works best when:
- The tool runs in heterogeneous environments (different OS, Node versions).
- Users are not expected to have Node.js installed.
- The tool’s release cadence is fast enough to keep the bundled runtime patched.
It works poorly when:
- Disk space is constrained (edge devices, CI containers).
- Security patching must happen within hours, not days.
- The tool is one of many Node.js CLIs on the same machine.
Technical Verdict
Feynman’s standalone runtime is a pragmatic choice for a research agent that needs to run reliably across macOS, Linux, and Windows without assuming a pre-installed Node.js environment. The isolation benefit outweighs the disk cost for most users.
Use this pattern when you are shipping an agent tool to non-technical users or environments where you cannot control the system dependencies. Avoid it when you are building for developers who already manage their Node.js versions and prefer lightweight installs.
The skills-only mode shows how to decouple agent capabilities from execution environments. If you are building a plugin system for an existing agent runtime, ship the skills separately and let the host provide the runtime.
The two-path upgrade model (installer for runtime, CLI command for packages) is confusing. Document it clearly. Consider adding an update checker to the CLI that prompts users to rerun the installer when a new runtime is available.