How to Access the Feynman Science Workbench: CLI and Programmatic Guide

Run feynman serve in your terminal to launch the Feynman science workbench as a local web application at http://localhost:3000, or use the --no-auth flag for local testing without authentication.

The Feynman science workbench is a full-stack research environment that runs locally via the Feynman CLI. According to the advaitpaliwal/feynman source code, you can access this web-based interface either through command-line invocation or programmatically via the Node.js API, enabling project navigation, Pi-driven chat, notebooks, and compute resources.

Architecture Overview

The workbench follows a layered architecture that connects the CLI to a local web server and Pi-driven research session.

1. CLI Entry Point: The feynman serve command is parsed in src/cli.ts, which invokes the serveWorkbench function to initialize the server.

2. Server Initialization: In src/workbench/server.ts, an Express-like HTTP server is created to serve static UI assets, register API routes, and establish the Pi session.

3. Pi Session: The WorkbenchPiRpcClient class defined in src/workbench/pi-session.ts instantiates the research agent that powers chat interactions and tool execution.

4. Runtime Bridge: Communication between the UI and Pi agent flows through src/workbench/chat-runtime.ts, which abstracts the RPC layer.

5. Frontend: The React-based UI is built using the Vite configuration in workbench.vite.config.ts and served as static files.

Launching the Workbench from the CLI

The simplest way to access the Feynman science workbench is via the command-line interface implemented in src/cli.ts.

To start the workbench with default settings and authentication enabled:

feynman serve

Once started, the CLI outputs the local URL (typically http://localhost:3000). Opening this address in your browser provides access to projects, Pi-driven chat, notebooks, compute resources, artifact previews, provenance tracking, and settings.

Local Testing Without Authentication

For trusted local environments where authentication is unnecessary, pass the --no-auth flag:

feynman serve --no-auth

This mode disables OAuth and OpenRouter authentication, binding the workbench to a plain HTTP URL suitable for isolated development or testing scenarios.

Programmatic Access

You can embed the workbench launch within custom Node.js scripts by importing the internal server functions directly from the advaitpaliwal/feynman codebase.

Basic Server Launch

The following example demonstrates starting the server on a custom port without authentication:

// launch-workbench.ts
import { serveWorkbench } from "./src/workbench/server.js";

(async () => {
  // Launch on port 4000, skipping authentication
  await serveWorkbench({ port: 4000, auth: false });
  console.log("Workbench is running at http://localhost:4000");
})();

Execute this script using Node.js or ts-node.

Advanced Configuration

To replicate the CLI's port parsing logic while maintaining programmatic control:

import { serveWorkbench } from "./src/workbench/server.js";
import { parseWorkbenchPort } from "./src/cli.js";

async function launchWorkbench() {
  const port = parseWorkbenchPort(undefined, 3000); // Defaults to 3000
  await serveWorkbench({ port, auth: true });       // Enable authentication
}

launchWorkbench().catch(console.error);

This pattern mirrors the CLI implementation in src/cli.ts, allowing you to specify ports and authentication behavior dynamically.

Key Source Files

Understanding the following files is essential for troubleshooting or extending workbench access:

• src/cli.ts: Parses the serve subcommand and invokes the server initialization. This is the primary entry point for the feynman serve command.

• src/workbench/server.ts: Contains the serveWorkbench function that creates the HTTP server, configures static asset serving, establishes API routes, and instantiates the Pi session.

• src/workbench/pi-session.ts: Defines WorkbenchPiRpcClient, the Pi-based research agent that handles chat interactions, tool execution, and background job processing.

• src/workbench/chat-runtime.ts: Implements the RPC client bridge that connects frontend chat actions to the Pi agent runtime.

• workbench.vite.config.ts: Configures the Vite build pipeline for the React frontend, ensuring the UI bundle is properly compiled and served.

Summary

• Primary command: Use feynman serve to start the workbench locally at http://localhost:3000.
• Authentication bypass: Append --no-auth for local testing without OAuth requirements.
• Programmatic control: Import serveWorkbench from src/workbench/server.js and parseWorkbenchPort from src/cli.js to embed the workbench in Node.js applications.
• Core architecture: CLI → serveWorkbench → HTTP server → Pi session (WorkbenchPiRpcClient) → React UI.
• Key files: src/cli.ts, src/workbench/server.ts, and src/workbench/pi-session.ts orchestrate the launch sequence.

Frequently Asked Questions

What port does the Feynman science workbench use by default?

The workbench defaults to port 3000. You can override this programmatically via the port parameter in the serveWorkbench function, or by modifying the CLI invocation logic in src/cli.ts.

Can I run the workbench without internet authentication?

Yes. Running feynman serve --no-auth disables the default OAuth and OpenRouter authentication flows. This creates an unauthenticated local instance accessible at http://localhost:<port>, intended for trusted local development environments only.

How do I access the workbench programmatically from another Node.js script?

Import the serveWorkbench function from src/workbench/server.js and call it with an options object specifying the port and authentication settings. For CLI-compatible port parsing, also import parseWorkbenchPort from src/cli.js as implemented in the source code.

What technology powers the chat and research features in the workbench?

The workbench utilizes a Pi-based research agent implemented as WorkbenchPiRpcClient in src/workbench/pi-session.ts. This client manages chat interactions, tool execution, and background jobs, communicating with the UI through the RPC bridge defined in src/workbench/chat-runtime.ts.

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