Where Are Feynman Settings, Auth Tokens, and Session State Stored?

Feynman stores user API credentials in auth.json at the workspace root, while OAuth tokens, session archives, and UI configuration reside in the .feynman/ directory within the working directory, with sensitive values stored as encrypted references rather than plain text.

The open-source Feynman workbench persists runtime state and authentication data across server restarts using a structured JSON file system. Understanding exactly where Feynman settings, auth tokens, and session state are stored is essential for backup strategies, security auditing, and multi-user deployment scenarios.

Authentication Credentials and API Keys

Feynman separates user-provided credentials from other configuration data by storing them in a dedicated file at the workspace root.

User-Provided API Keys (auth.json)

The auth.json file lives in the workspace root—the folder passed to feynman serve or feynman run. According to the Feynman source code in src/workbench/secret-ledgers.ts, the readAuthCredentials function parses this file and transforms each entry into a secret row with the source type auth-storage.

These secret rows are then exposed to the workbench as part of the user-secrets ledger. When you supply credentials for providers like Anthropic or OpenAI, they are stored here before being converted to encrypted references.

OAuth Access and Refresh Tokens (oauth-tokens.json)

Completed OAuth flows result in tokens stored in .feynman/oauth-tokens.json within the working directory. The src/workbench/oauth-store.ts module manages this file using the migratedSensitiveStorePath helper to determine the correct storage location.

The oauthTokenForConnector function retrieves these entries, returning token objects where the encryptedAccessToken field contains reference strings like feynman-oauth-ref:lab-oauth:access rather than the actual token value.

Pending OAuth State (oauth-pending.json)

During active OAuth flows, temporary state is cached in .feynman/oauth-pending.json. This prevents loss of the authorization request context if the server restarts mid-flow, ensuring the handshake can complete successfully.

Session Archives and Persistent State

Chat history, notebook cells, and plan versions survive server restarts through the session archiving system.

Session Archives Directory

The src/workbench/session-archives.ts module writes persistent session data to files under .feynman/session-archives/, such as sessions.json and chat-archive.json. The sessionArchivePath helper generates the correct file path based on the working directory.

When the Feynman server restarts, these archives are read back into memory, allowing users to resume work exactly where they left off. The system treats these as plain JSON stores for structured data like message threads and cell outputs.

Workbench Configuration (settings.json)

Non-sensitive UI preferences—including themes, custom connector definitions, and layout settings—are stored in .feynman/settings.json. The src/workbench/settings-store.ts module reads this file to populate the WorkbenchSettings interface.

Unlike credential files, settings.json contains only UI-related configuration and never stores secret values, making it safe to version control in team environments.

Security Model: Encrypted References vs. Plain Text

Feynman does not store actual secret values in clear text within these JSON files. Instead, the codebase implements a reference-based encryption layer.

When a secret is recorded, the file contains reference strings such as feynman-auth-storage-ref:auth:anthropic or feynman-oauth-ref:lab-oauth:access. The actual credentials are encrypted or maintained behind this reference layer and are only decrypted when the runtime needs to make an authenticated API request.

This architecture ensures that raw API keys and OAuth tokens are never exposed in plain JSON files, even if an attacker gains filesystem access to the .feynman/ directory.

Code Examples

The following examples demonstrate how to interact with these storage locations programmatically using the internal Feynman APIs.

Reading user-provided API keys from auth.json:

import { readAuthCredentials } from "./secret-ledgers.js";

const authPath = "/my/workspace/auth.json";
const credentials = readAuthCredentials(authPath);
// => [{ provider: "anthropic", credential: { type: "api_key", key: "…"} }, …]

Retrieving an OAuth token reference for a specific connector:

import { oauthTokenForConnector } from "./oauth-store.js";

const token = oauthTokenForConnector("/my/workspace", "lab-oauth");
// token?.encryptedAccessToken === "feynman-oauth-ref:lab-oauth:access"

Persisting a chat session to the archives:

import { writeFileSync } from "fs";
import { sessionArchivePath } from "./session-archives.js";

const archive = { chatId: "c123", messages: [...] };
writeFileSync(sessionArchivePath("/my/workspace"), JSON.stringify(archive));

Summary

• Authentication credentials reside in auth.json at the workspace root, parsed by src/workbench/secret-ledgers.ts using readAuthCredentials.
• OAuth tokens are stored in .feynman/oauth-tokens.json and .feynman/oauth-pending.json, managed by src/workbench/oauth-store.ts with reference strings like feynman-oauth-ref:lab-oauth:access.
• Session archives including chat history persist in .feynman/session-archives/, handled by src/workbench/session-archives.ts for crash recovery.
• UI settings live in .feynman/settings.json and are loaded by src/workbench/settings-store.ts into the WorkbenchSettings interface.
• Security: All sensitive values use encrypted reference strings rather than plain text, ensuring credentials remain protected even if JSON storage files are compromised.

Frequently Asked Questions

Where is the auth.json file located in a Feynman project?

The auth.json file is located at the workspace root—the directory passed to the feynman serve or feynman run commands. This placement keeps user-provided API keys separate from the runtime state stored in the hidden .feynman/ directory.

How does Feynman secure OAuth tokens on disk?

Feynman stores OAuth tokens in .feynman/oauth-tokens.json, but the actual token values are replaced with encrypted reference strings such as feynman-oauth-ref:lab-oauth:access. The oauthTokenForConnector function in src/workbench/oauth-store.ts retrieves these references, which are only decrypted when making authenticated requests, preventing exposure of raw credentials in the filesystem.

Can session history survive a Feynman server restart?

Yes. The src/workbench/session-archives.ts module automatically persists chat threads, notebook cells, and plan versions to .feynman/session-archives/ (e.g., sessions.json and chat-archive.json). When the server restarts, these files are read back, allowing users to resume their exact previous state.

What is stored in the .feynman/settings.json file?

The settings.json file contains only UI-related configuration such as themes, custom connector definitions, and workbench layout preferences. Loaded by src/workbench/settings-store.ts into the WorkbenchSettings interface, this file explicitly excludes sensitive data and is safe to share or version control unlike the credential files.

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