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

> Access the Feynman science workbench locally via CLI with `feynman serve` or programmatically. Explore Feynman for scientific exploration and research.

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

---

**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`](https://github.com/advaitpaliwal/feynman/blob/main/src/cli.ts), which invokes the `serveWorkbench` function to initialize the server.

2. **Server Initialization**: In [`src/workbench/server.ts`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/src/cli.ts).

To start the workbench with default settings and authentication enabled:

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

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

```typescript
// 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:

```typescript
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`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/src/workbench/chat-runtime.ts)**: Implements the RPC client bridge that connects frontend chat actions to the Pi agent runtime.

- **[`workbench.vite.config.ts`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/src/workbench/server.js) and `parseWorkbenchPort` from [`src/cli.js`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/src/cli.ts), [`src/workbench/server.ts`](https://github.com/advaitpaliwal/feynman/blob/main/src/workbench/server.ts), and [`src/workbench/pi-session.ts`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/src/workbench/chat-runtime.ts).