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

> Discover where Feynman stores settings, auth tokens, and session state. Learn about auth.json, the .feynman directory, and encrypted references for sensitive data.

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

---

**Feynman stores user API credentials in [`auth.json`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/.feynman/oauth-tokens.json) within the working directory. The [`src/workbench/oauth-store.ts`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/.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`](https://github.com/advaitpaliwal/feynman/blob/main/src/workbench/session-archives.ts) module writes persistent session data to files under `.feynman/session-archives/`, such as [`sessions.json`](https://github.com/advaitpaliwal/feynman/blob/main/sessions.json) and [`chat-archive.json`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/.feynman/settings.json). The [`src/workbench/settings-store.ts`](https://github.com/advaitpaliwal/feynman/blob/main/src/workbench/settings-store.ts) module reads this file to populate the `WorkbenchSettings` interface.

Unlike credential files, [`settings.json`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/auth.json):

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

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

```typescript
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`](https://github.com/advaitpaliwal/feynman/blob/main/auth.json) at the workspace root, parsed by [`src/workbench/secret-ledgers.ts`](https://github.com/advaitpaliwal/feynman/blob/main/src/workbench/secret-ledgers.ts) using `readAuthCredentials`.
- **OAuth tokens** are stored in [`.feynman/oauth-tokens.json`](https://github.com/advaitpaliwal/feynman/blob/main/.feynman/oauth-tokens.json) and [`.feynman/oauth-pending.json`](https://github.com/advaitpaliwal/feynman/blob/main/.feynman/oauth-pending.json), managed by [`src/workbench/oauth-store.ts`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/src/workbench/session-archives.ts) for crash recovery.
- **UI settings** live in [`.feynman/settings.json`](https://github.com/advaitpaliwal/feynman/blob/main/.feynman/settings.json) and are loaded by [`src/workbench/settings-store.ts`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/.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`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/src/workbench/session-archives.ts) module automatically persists chat threads, notebook cells, and plan versions to `.feynman/session-archives/` (e.g., [`sessions.json`](https://github.com/advaitpaliwal/feynman/blob/main/sessions.json) and [`chat-archive.json`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/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.