How-To Guide
Fix API-key paste issues in Hermes Agent
Blank key input may be intentional. Check the terminal, select the right Hermes profile, store the key privately and verify a small provider request.
Quick answer
At an active hidden credential prompt, paste once and press Enter. If setup accepts it, verify a small request. If input genuinely fails, open the owning profile's .env in a trusted local editor rather than putting the key in an echo or export command. A rejected request needs provider authentication troubleshooting, not repeated pasting.
A blank credential prompt does not tell you whether paste worked. Hidden input protects the secret, but terminal clipboard problems can also happen. Check which case you have before changing a working key or exposing it in a shell command.
$49/mo or $39/mo billed yearly · AI included · 14‑day guarantee
Before you start:
- ☑An authorized provider key or the provider's supported OAuth flow; do not use a key sent by someone claiming to be support.
- ☑Access to the host and operating-system user that run Hermes.
- ☑The actual profile name and a private terminal or local editor; stop screen sharing before handling secrets.
Steps
- 1
Confirm which input prompt is active
Open the supported interactive setup with
hermes model, or the credential-pool flow withhermes auth add. For a named profile usehermes -p work model, replacing work with its actual name. Only paste the secret after the credential prompt appears; pasting into a normal shell or chat is an exposure, not a paste test. - 2
Paste once, then judge the result
Hidden input may show no characters or cursor movement. Paste once and press Enter. Judge the next prompt or validation result instead of repeatedly pasting the key. Repeated paste can concatenate the secret and create an invalid value. Invisible input alone cannot establish whether the clipboard delivered anything.
- 3
Test the clipboard with harmless text
If the prompt receives nothing, cancel it first. Paste an ordinary word into a trusted scratch editor to test the terminal or remote-console clipboard. On WSL, Termux and browser consoles, use that application's supported paste shortcut or clipboard permission. Never reveal the real key to diagnose clipboard behavior.
- 4
Locate the correct secret file
Run
hermes config env-path, orhermes -p work config env-pathfor the named profile. Open the returned file with a trusted local editor. Add the provider's documented variable and key there; do not assume every service uses ~/.hermes/.env. The API-key setup guide explains storage, and the profiles guide explains separate profile state. - 5
Copy the credential exactly
Copy the original value from the provider dashboard, not a masked display, URL or screenshot. Preserve its characters exactly. Do not decode % sequences, repair punctuation or infer a missing prefix. If the provider copy action includes surrounding whitespace, recopy the original rather than guessing which characters belong to the secret. Check the variable name against the official provider reference.
- 6
Verify the intended route
Restart a CLI session after saving; safely reload a long-running service only when its active work can be interrupted. Run
hermes -p work chat -q "Reply with exactly: provider ok. Do not use tools."under the owning profile. This can incur usage charges. Confirm the actual provider route and, if a gateway was affected, verify one reply in the original channel. The provider costs guide separates authentication from billing and quota errors.
Pro Tips
- 💡Do not place a real key in echo, export, command-line flags, screenshots, Git or a chat prompt. Shell history and process inspection can retain command arguments.
- 💡Keep editor backups and synchronization destinations private too. Do not save a credential file inside the website or another public repository.
- 💡If a secret was exposed, revoke it at the provider, replace it in the authorized runtime and verify recovery. Removing a screenshot or shell-history entry does not revoke the key.
- 💡If runtime maintenance is the obstacle, compare managed Hermes hosting. Hosted plans still have credential, access and usage boundaries; they are not a repair for an unknown rejected key.
Troubleshooting
❌ The prompt is blank
✅ That may be hidden input. Paste once and press Enter at the active credential prompt. Only the subsequent validation or request establishes whether the key was accepted.
❌ Clipboard works, but the provider returns 401
✅ Stop testing paste. Confirm the endpoint, credential source, host and profile using authentication troubleshooting. A revoked key, wrong route or old service environment needs a different repair.
❌ The file was edited but the gateway still fails
✅ Compare the gateway's profile and operating-system user with the file path you edited. The service may also retain older process state. Do not overwrite credentials in every profile.
❌ The key was pasted into a shell or shared chat
✅ Treat the secret as exposed. Revoke it through the provider and replace it privately. Do not rely on deleting the visible text.
FAQ
Does blank API-key input mean paste failed?
No. Hidden input may show nothing, but clipboard failure is also possible. Paste once at the active credential prompt, press Enter, and verify the resulting request.
Can I use an echo command to add the key?
Avoid placing the real secret in a shell command or argument. Use the interactive auth flow or a trusted local editor for the file returned by hermes config env-path.
Should I change percent signs or add a missing key prefix?
No. Preserve the credential exactly as the provider issued it. Recopy the original value instead of decoding or repairing it by guesswork.
Why does the key work locally but fail in a gateway?
The gateway can run on a different host, under a different operating-system user or Hermes profile, or with older process state. Verify the credential source in the process that failed.