From 56ceb24ce315d13c1c9a9fcfb12b4c85398c6415 Mon Sep 17 00:00:00 2001
From: Ben Browning <56071+bbrowning@users.noreply.github.com>
Date: Tue, 29 Sep 2026 13:41:37 -0400
Subject: [PATCH] Document storing paude tokens in the desktop keyring

Show how to keep PAUDE_GITHUB_TOKEN and CLAUDE_CODE_OAUTH_TOKEN in
the Linux keyring via secret-tool and inject them only into paude
with a shell wrapper, instead of exporting plaintext tokens from a
shell profile where file-scraping malware and security scanners
find them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 README.md             | 29 +++++++++++++++++++++++++++++
 docs/CONFIGURATION.md |  3 +++
 2 files changed, 32 insertions(+)

diff --git a/README.md b/README.md
index be8e0a5..d87f6f3 100644
--- a/README.md
+++ b/README.md
@@ -227,6 +227,35 @@ agent login  # or set CURSOR_API_KEY=your-api-key
 
 </details>
 
+<details>
+<summary><strong>Keeping tokens out of plaintext files</strong> (Linux keyring)</summary>
+
+paude reads credentials from its environment, but they don't need to be
+exported from `~/.bashrc`. Store each one in your desktop keyring once
+(`secret-tool` prompts for the value, keeping it out of shell history):
+
+```bash
+secret-tool store --label="paude GitHub PAT" service paude key PAUDE_GITHUB_TOKEN
+secret-tool store --label="paude Claude OAuth" service paude key CLAUDE_CODE_OAUTH_TOKEN
+```
+
+Then add a wrapper to `~/.bashrc` that injects them only into `paude` itself:
+
+```bash
+paude() {
+  PAUDE_GITHUB_TOKEN="$(secret-tool lookup service paude key PAUDE_GITHUB_TOKEN)" \
+  CLAUDE_CODE_OAUTH_TOKEN="$(secret-tool lookup service paude key CLAUDE_CODE_OAUTH_TOKEN)" \
+    command paude "$@"
+}
+```
+
+This keeps tokens off disk in plaintext and out of every other process's
+environment, but any process running as your user can still query the
+unlocked keyring. On macOS, use `security find-generic-password -w -s <name>`
+in the wrapper instead.
+
+</details>
+
 ### Install
 
 ```bash
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
index 572ec85..75ee102 100644
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -307,6 +307,9 @@ paude start my-project
 # Inside the container, gh is authenticated automatically
 ```
 
+To avoid keeping the token in a plaintext shell profile, see "Keeping tokens
+out of plaintext files" in the [README](../README.md).
+
 The token is never handed to the agent's own container:
 - `PAUDE_GITHUB_TOKEN` is read on the host and stored only on the network-filtering proxy sidecar. See [Remote Hosts & Docker Backend](REMOTE.md) for how storage differs between the Podman and Docker backends
 - The agent container's own `GH_TOKEN` environment variable is always a non-functional placeholder; the proxy transparently attaches the real token to requests it forwards to GitHub's API