chorus/API-KEY-SETUP.md

ECHO — API key setup (Windows & macOS)

The ECHO plugin authenticates to the vault with a bearer token. echo.py resolves it in this order — first hit wins:

1. ECHO_KEY environment variable ← recommended for workstations
2. ~/.echo-memory/credentials file (one key=… line, chmod 600)
3. a deprecated baked-in fallback (prints a warning on every call until you do #1 or #2)

You only need one of these. Pick the env var (below) or the credentials file (python3 echo.py write-key <token>, cross-platform, no shell config needed).

Replace <YOUR_ECHO_API_KEY> everywhere below with your actual token. Never paste the token into a vault note, a committed file, or a screen-share.

---

Option A — credentials file (simplest, cross-platform)

# from the plugin's scripts dir; works identically on Windows/macOS/Linux
python3 "<plugin>/skills/echo-memory/scripts/echo.py" write-key <YOUR_ECHO_API_KEY>

Writes ~/.echo-memory/credentials (mode 600 on Unix). Nothing else to configure. To rotate later, run it again with the new token.

---

Option B — environment variable

Windows

PowerShell — persistent (recommended). Sets it for your user account; open a new terminal afterward (the current session won't see it):

[Environment]::SetEnvironmentVariable("ECHO_KEY", "<YOUR_ECHO_API_KEY>", "User")

Command Prompt — persistent (alternative; note setx truncates values over 1024 chars, so the 64-char ECHO key is fine):

setx ECHO_KEY "<YOUR_ECHO_API_KEY>"

Current session only (not persistent):

$env:ECHO_KEY = "<YOUR_ECHO_API_KEY>"     # PowerShell

set ECHO_KEY=<YOUR_ECHO_API_KEY>           REM Command Prompt

GUI alternative: Start → "Edit the system environment variables" → Environment Variables… → under User variables click New… → Name ECHO_KEY, Value the token.

Verify (in a NEW terminal):

echo $env:ECHO_KEY        # PowerShell

echo %ECHO_KEY%           :: Command Prompt

macOS

Modern macOS uses zsh. Add the export to your shell profile, then reload it:

echo 'export ECHO_KEY="<YOUR_ECHO_API_KEY>"' >> ~/.zshrc
source ~/.zshrc

If you use bash instead:

echo 'export ECHO_KEY="<YOUR_ECHO_API_KEY>"' >> ~/.bash_profile
source ~/.bash_profile

For GUI apps (a desktop app that doesn't read your shell profile) you can also set it for the login session:

launchctl setenv ECHO_KEY "<YOUR_ECHO_API_KEY>"

(Not persistent across reboot on its own; the shell-profile export above covers terminal sessions, which is what the plugin uses.)

Verify (in a NEW terminal):

echo "$ECHO_KEY"

---

Confirm it works

python3 "<plugin>/skills/echo-memory/scripts/echo.py" doctor

doctor reports the Python version, vault reachability, auth, bootstrap/schema, and the API key source — it should say ECHO_KEY env or credentials file, not the deprecated baked-in fallback.

---

Security notes

• The token is a vault credential — treat it like a password. Don't commit it, don't store it in a vault note, rotate it if it leaks.
• ECHO_KEY (or ECHO_BASE) set in the environment always overrides the credentials file and the baked-in default, so it's safe for CI / one-off overrides: ECHO_KEY=… python3 echo.py ….
• Once you've set the key via Option A or B on every machine/agent that runs the plugin (terminal, CoWork, any scheduled run), the deprecated baked-in fallback can be removed from scripts/echo.py (DEFAULT_KEY) so no token lives in the source tree at all.