npm - better-dsh - Versions diffs - 0.2.5 → 0.3.0-c - Mend

better-dsh 0.2.5 → 0.3.0-c

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1002) hide show

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/guides/migrate-from-openclaw.md DELETED Viewed

@@ -1,252 +0,0 @@
----
-sidebar_position: 10
-title: "Migrate from OpenClaw"
-description: "Complete guide to migrating your OpenClaw / Clawdbot setup to Hermes Agent — what gets migrated, how config maps, and what to check after."
----
-# Migrate from OpenClaw
-`hermes claw migrate` imports your OpenClaw (or legacy Clawdbot/Moldbot) setup into Hermes. This guide covers exactly what gets migrated, the config key mappings, and what to verify after migration.
-:::note
-Coming from **Claude Code** or **OpenAI Codex CLI** instead? Use [`hermes import-agent`](../user-guide/import-from-other-agents.md).
-:::
-:::tip
-If your OpenClaw setup was multi-provider, `hermes setup --portal` collapses it to one OAuth — 300+ models plus the Tool Gateway in a single login. See [Nous Portal](/integrations/nous-portal).
-:::
-## Quick start
-```bash
-# Preview then migrate (always shows a preview first, then asks to confirm)
-hermes claw migrate
-# Preview only, no changes
-hermes claw migrate --dry-run
-# Full migration including API keys, skip confirmation
-hermes claw migrate --preset full --migrate-secrets --yes
-```
-The migration always shows a full preview of what will be imported before making any changes. Review the list, then confirm to proceed.
-Reads from `~/.openclaw/` by default. Legacy `~/.clawdbot/` or `~/.moltbot/` directories are detected automatically. Same for legacy config filenames (`clawdbot.json`, `moltbot.json`).
-## Options
-| Option | Description |
-|--------|-------------|
-| `--dry-run` | Preview only — stop after showing what would be migrated. |
-| `--preset <name>` | `full` (all compatible settings) or `user-data` (excludes infrastructure config). Neither preset imports secrets by default — pass `--migrate-secrets` explicitly. |
-| `--overwrite` | Overwrite existing Hermes files on conflicts (default: refuse to apply when the plan has conflicts). |
-| `--migrate-secrets` | Include API keys. Required even under `--preset full` — no preset imports secrets silently. |
-| `--no-backup` | Skip the pre-migration zip snapshot of `~/.hermes/` (by default a single restore-point archive is written before apply, under `~/.hermes/backups/pre-migration-*.zip`; restorable with `hermes import`). |
-| `--source <path>` | Custom OpenClaw directory. |
-| `--workspace-target <path>` | Where to place `AGENTS.md`. |
-| `--skill-conflict <mode>` | `skip` (default), `overwrite`, or `rename`. |
-| `--yes` | Skip the confirmation prompt after preview. |
-## What gets migrated
-### Persona, memory, and instructions
-| What | OpenClaw source | Hermes destination | Notes |
-|------|----------------|-------------------|-------|
-| Persona | `workspace/SOUL.md` | `~/.hermes/SOUL.md` | Direct copy |
-| Workspace instructions | `workspace/AGENTS.md` | `AGENTS.md` in `--workspace-target` | Requires `--workspace-target` flag |
-| Long-term memory | `workspace/MEMORY.md` | `~/.hermes/memories/MEMORY.md` | Parsed into entries, merged with existing, deduped. Uses `§` delimiter. |
-| User profile | `workspace/USER.md` | `~/.hermes/memories/USER.md` | Same entry-merge logic as memory. |
-| Daily memory files | `workspace/memory/*.md` | `~/.hermes/memories/MEMORY.md` | All daily files merged into main memory. |
-Workspace files are also checked at `workspace.default/` and `workspace-main/` as fallback paths (OpenClaw renamed `workspace/` to `workspace-main/` in recent versions, and uses `workspace-{agentId}` for multi-agent setups).
-### Skills (4 sources)
-| Source | OpenClaw location | Hermes destination |
-|--------|------------------|-------------------|
-| Workspace skills | `workspace/skills/` | `~/.hermes/skills/openclaw-imports/` |
-| Managed/shared skills | `~/.openclaw/skills/` | `~/.hermes/skills/openclaw-imports/` |
-| Personal cross-project | `~/.agents/skills/` | `~/.hermes/skills/openclaw-imports/` |
-| Project-level shared | `workspace/.agents/skills/` | `~/.hermes/skills/openclaw-imports/` |
-Skill conflicts are handled by `--skill-conflict`: `skip` leaves the existing Hermes skill, `overwrite` replaces it, `rename` creates a `-imported` copy.
-### Model and provider configuration
-| What | OpenClaw config path | Hermes destination | Notes |
-|------|---------------------|-------------------|-------|
-| Default model | `agents.defaults.model` | `config.yaml` → `model` | Can be a string or `{primary, fallbacks}` object |
-| Custom providers | `models.providers.*` | `config.yaml` → `custom_providers` (auto-migrated to the canonical `providers:` dict on the next `hermes update` config migration) | Maps `baseUrl`, `apiType`/`api` — handles both short ("openai", "anthropic") and hyphenated ("openai-completions", "anthropic-messages", "google-generative-ai") values |
-| Provider API keys | `models.providers.*.apiKey` | `~/.hermes/.env` | Requires `--migrate-secrets`. See [API key resolution](#api-key-resolution) below. |
-### Agent behavior
-| What | OpenClaw config path | Hermes config path | Mapping |
-|------|---------------------|-------------------|---------|
-| Max turns | `agents.defaults.timeoutSeconds` | `agent.max_turns` | `timeoutSeconds / 10`, capped at 200 |
-| Verbose mode | `agents.defaults.verboseDefault` | `agent.verbose` | "off" / "on" / "full" |
-| Reasoning effort | `agents.defaults.thinkingDefault` | `agent.reasoning_effort` | "always"/"high"/"xhigh" → "high", "auto"/"medium"/"adaptive" → "medium", "off"/"low"/"none"/"minimal" → "low" |
-| Compression | `agents.defaults.compaction.mode` | `compression.enabled` | "off" → false, anything else → true |
-| Compression model | `agents.defaults.compaction.model` | `compression.summary_model` | Direct string copy |
-| Human delay | `agents.defaults.humanDelay.mode` | `human_delay.mode` | "natural" / "custom" / "off" |
-| Human delay timing | `agents.defaults.humanDelay.minMs` / `.maxMs` | `human_delay.min_ms` / `.max_ms` | Direct copy |
-| Timezone | `agents.defaults.userTimezone` | `timezone` | Direct string copy |
-| Exec timeout | `tools.exec.timeoutSec` | `terminal.timeout` | Direct copy (field is `timeoutSec`, not `timeout`) |
-| Docker sandbox | `agents.defaults.sandbox.backend` | `terminal.backend` | "docker" → "docker" |
-| Docker image | `agents.defaults.sandbox.docker.image` | `terminal.docker_image` | Direct copy |
-### Session lifetime
-Idle and daily reset timers are not imported: Hermes conversations persist until an explicit `/new` or `/reset`. Advanced session settings (identity links, thread bindings, maintenance, scope and send policy) remain archived for reference.
-### MCP servers
-| OpenClaw field | Hermes field | Notes |
-|----------------|-------------|-------|
-| `mcp.servers.*.command` | `mcp_servers.*.command` | Stdio transport |
-| `mcp.servers.*.args` | `mcp_servers.*.args` | |
-| `mcp.servers.*.env` | `mcp_servers.*.env` | |
-| `mcp.servers.*.cwd` | `mcp_servers.*.cwd` | |
-| `mcp.servers.*.url` | `mcp_servers.*.url` | HTTP/SSE transport |
-| `mcp.servers.*.tools.include` | `mcp_servers.*.tools.include` | Tool filtering |
-| `mcp.servers.*.tools.exclude` | `mcp_servers.*.tools.exclude` | |
-### TTS (text-to-speech)
-TTS settings are read from **two** OpenClaw config locations with this priority:
-1. `messages.tts.providers.{provider}.*` (canonical location)
-2. Top-level `talk.providers.{provider}.*` (fallback)
-3. Legacy flat keys `messages.tts.{provider}.*` (oldest format)
-| What | Hermes destination |
-|------|-------------------|
-| Provider name | `config.yaml` → `tts.provider` |
-| ElevenLabs voice ID | `config.yaml` → `tts.elevenlabs.voice_id` |
-| ElevenLabs model ID | `config.yaml` → `tts.elevenlabs.model_id` |
-| OpenAI model | `config.yaml` → `tts.openai.model` |
-| OpenAI voice | `config.yaml` → `tts.openai.voice` |
-| Edge TTS voice | `config.yaml` → `tts.edge.voice` (OpenClaw renamed "edge" to "microsoft" — both are recognized) |
-| TTS assets | `~/.hermes/tts/` (file copy) |
-### Messaging platforms
-| Platform | OpenClaw config path | Hermes `.env` variable | Notes |
-|----------|---------------------|----------------------|-------|
-| Telegram | `channels.telegram.botToken` or `.accounts.default.botToken` | `TELEGRAM_BOT_TOKEN` | Token can be string or [SecretRef](#secretref-handling). Both flat and accounts layout supported. |
-| Telegram | `credentials/telegram-default-allowFrom.json` | `TELEGRAM_ALLOWED_USERS` | Comma-joined from `allowFrom[]` array |
-| Discord | `channels.discord.token` or `.accounts.default.token` | `DISCORD_BOT_TOKEN` | |
-| Discord | `channels.discord.allowFrom` or `.accounts.default.allowFrom` | `DISCORD_ALLOWED_USERS` | |
-| Slack | `channels.slack.botToken` or `.accounts.default.botToken` | `SLACK_BOT_TOKEN` | |
-| Slack | `channels.slack.appToken` or `.accounts.default.appToken` | `SLACK_APP_TOKEN` | |
-| Slack | `channels.slack.allowFrom` or `.accounts.default.allowFrom` | `SLACK_ALLOWED_USERS` | |
-| WhatsApp | `channels.whatsapp.allowFrom` or `.accounts.default.allowFrom` | `WHATSAPP_ALLOWED_USERS` | Auth via Baileys QR pairing — requires re-pairing after migration |
-| Signal | `channels.signal.account` or `.accounts.default.account` | `SIGNAL_ACCOUNT` | |
-| Signal | `channels.signal.httpUrl` or `.accounts.default.httpUrl` | `SIGNAL_HTTP_URL` | |
-| Signal | `channels.signal.allowFrom` or `.accounts.default.allowFrom` | `SIGNAL_ALLOWED_USERS` | |
-| Matrix | `channels.matrix.accessToken` or `.accounts.default.accessToken` | `MATRIX_ACCESS_TOKEN` | Uses `accessToken` (not `botToken`) |
-| Mattermost | `channels.mattermost.botToken` or `.accounts.default.botToken` | `MATTERMOST_BOT_TOKEN` | |
-### Other config
-| What | OpenClaw path | Hermes path | Notes |
-|------|-------------|-------------|-------|
-| Approval mode | `approvals.exec.mode` | `config.yaml` → `approvals.mode` | "auto"→"off", "always"→"manual", "smart"→"smart" |
-| Command allowlist | `exec-approvals.json` | `config.yaml` → `command_allowlist` | Patterns merged and deduped |
-| Browser CDP URL | `browser.cdpUrl` | `config.yaml` → `browser.cdp_url` | |
-| Browser headless | `browser.headless` | `config.yaml` → `browser.headless` | |
-| Brave search key | `tools.web.search.brave.apiKey` | `.env` → `BRAVE_API_KEY` | Requires `--migrate-secrets` |
-| Gateway auth token | `gateway.auth.token` | `.env` → `HERMES_GATEWAY_TOKEN` | Requires `--migrate-secrets` |
-| Working directory | `agents.defaults.workspace` | `config.yaml` → `terminal.cwd` | Legacy migrations may still emit `MESSAGING_CWD` as a compatibility fallback |
-### Archived (no direct Hermes equivalent)
-These are saved to `~/.hermes/migration/openclaw/<timestamp>/archive/` for manual review:
-| What | Archive file | How to recreate in Hermes |
-|------|-------------|--------------------------|
-| `IDENTITY.md` | `archive/workspace/IDENTITY.md` | Merge into `SOUL.md` |
-| `TOOLS.md` | `archive/workspace/TOOLS.md` | Hermes has built-in tool instructions |
-| `HEARTBEAT.md` | `archive/workspace/HEARTBEAT.md` | Use cron jobs for periodic tasks |
-| `BOOTSTRAP.md` | `archive/workspace/BOOTSTRAP.md` | Use context files or skills |
-| Cron jobs | `archive/cron-config.json` | Recreate with `hermes cron create` |
-| Plugins | `archive/plugins-config.json` | See [plugins guide](/user-guide/features/hooks) |
-| Hooks/webhooks | `archive/hooks-config.json` | Use `hermes webhook` or gateway hooks |
-| Memory backend | `archive/memory-backend-config.json` | Configure via `hermes honcho` |
-| Skills registry | `archive/skills-registry-config.json` | Use `hermes skills config` |
-| UI/identity | `archive/ui-identity-config.json` | Use `/skin` command |
-| Logging | `archive/logging-diagnostics-config.json` | Set in `config.yaml` logging section |
-| Multi-agent list | `archive/agents-list.json` | Use Hermes profiles |
-| Channel bindings | `archive/bindings.json` | Manual setup per platform |
-| Complex channels | `archive/channels-deep-config.json` | Manual platform config |
-## API key resolution
-When `--migrate-secrets` is enabled, API keys are collected from **four sources** in priority order:
-1. **Config values** — `models.providers.*.apiKey` and TTS provider keys in `openclaw.json`
-2. **Environment file** — `~/.openclaw/.env` (keys like `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`, etc.)
-3. **Config env sub-object** — `openclaw.json` → `"env"` or `"env"."vars"` (some setups store keys here instead of a separate `.env` file)
-4. **Auth profiles** — `~/.openclaw/agents/main/agent/auth-profiles.json` (per-agent credentials)
-Config values take priority. Each subsequent source fills any remaining gaps.
-### Supported key targets
-`OPENROUTER_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `DEEPSEEK_API_KEY`, `GEMINI_API_KEY`, `ZAI_API_KEY`, `MINIMAX_API_KEY`, `ELEVENLABS_API_KEY`, `TELEGRAM_BOT_TOKEN`, `VOICE_TOOLS_OPENAI_KEY`
-Keys not in this allowlist are never copied.
-## SecretRef handling
-OpenClaw config values for tokens and API keys can be in three formats:
-```json
-// Plain string
-"channels": { "telegram": { "botToken": "123456:ABC-DEF..." } }
-// Environment template
-"channels": { "telegram": { "botToken": "${TELEGRAM_BOT_TOKEN}" } }
-// SecretRef object
-"channels": { "telegram": { "botToken": { "source": "env", "id": "TELEGRAM_BOT_TOKEN" } } }
-```
-The migration resolves all three formats. For env templates and SecretRef objects with `source: "env"`, it looks up the value in `~/.openclaw/.env` and the `openclaw.json` env sub-object. SecretRef objects with `source: "file"` or `source: "exec"` can't be resolved automatically — the migration warns about these, and those values must be added to Hermes manually via `hermes config set`.
-## After migration
-1. **Check the migration report** — printed on completion with counts of migrated, skipped, and conflicting items.
-2. **Review archived files** — anything in `~/.hermes/migration/openclaw/<timestamp>/archive/` needs manual attention.
-3. **Start a new session** — imported skills and memory entries take effect in new sessions, not the current one.
-4. **Verify API keys** — run `hermes status` to check provider authentication.
-5. **Test messaging** — if you migrated platform tokens, restart the gateway: `systemctl --user restart hermes-gateway`
-6. **Check session archives** — review archived advanced settings; idle and daily reset timers are intentionally not imported.
-7. **Re-pair WhatsApp** — WhatsApp uses QR code pairing (Baileys), not token migration. Run `hermes whatsapp` to pair.
-8. **Archive cleanup** — after confirming everything works, run `hermes claw cleanup` to rename leftover OpenClaw directories to `.pre-migration/` (prevents state confusion).
-## Troubleshooting
-### "OpenClaw directory not found"
-The migration checks `~/.openclaw/`, then `~/.clawdbot/`, then `~/.moltbot/`. If your installation is elsewhere, use `--source /path/to/your/openclaw`.
-### "No provider API keys found"
-Keys might be stored in several places depending on your OpenClaw version: inline in `openclaw.json` under `models.providers.*.apiKey`, in `~/.openclaw/.env`, in the `openclaw.json` `"env"` sub-object, or in `agents/main/agent/auth-profiles.json`. The migration checks all four. If keys use `source: "file"` or `source: "exec"` SecretRefs, they can't be resolved automatically — add them via `hermes config set`.
-### Skills not appearing after migration
-Imported skills land in `~/.hermes/skills/openclaw-imports/`. Start a new session for them to take effect, or run `/skills` to verify they're loaded.
-### TTS voice not migrated
-OpenClaw stores TTS settings in two places: `messages.tts.providers.*` and the top-level `talk` config. The migration checks both. If your voice ID was set via the OpenClaw UI (stored in a different path), you may need to set it manually: `hermes config set tts.elevenlabs.voice_id YOUR_VOICE_ID`.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/guides/minimax-oauth.md DELETED Viewed

@@ -1,226 +0,0 @@
----
-sidebar_position: 15
-title: "MiniMax OAuth"
-description: "Log into MiniMax via browser OAuth and use MiniMax-M2.7 models in Hermes Agent — no API key required"
----
-# MiniMax OAuth
-Hermes Agent supports **MiniMax** through a browser-based OAuth login flow, using the same credentials as the [MiniMax portal](https://www.minimax.io). No API key or credit card is required — log in once and Hermes automatically refreshes your session.
-The transport reuses the `anthropic_messages` adapter (MiniMax exposes an Anthropic Messages-compatible endpoint at `/anthropic`), so all existing tool-calling, streaming, and context features work without any adapter changes.
-## Overview
-| Item | Value |
-|------|-------|
-| Provider ID | `minimax-oauth` |
-| Display name | MiniMax (OAuth) |
-| Auth type | Browser OAuth (PKCE redirect flow) |
-| Transport | Anthropic Messages-compatible (`anthropic_messages`) |
-| Models | `MiniMax-M2.7`, `MiniMax-M2.7-highspeed` |
-| Global endpoint | `https://api.minimax.io/anthropic` |
-| China endpoint | `https://api.minimaxi.com/anthropic` |
-| Requires env var | No (`MINIMAX_API_KEY` is **not** used for this provider) |
-## Prerequisites
-- Python 3.9+
-- Hermes Agent installed
-- A MiniMax account at [minimax.io](https://www.minimax.io) (global) or [minimaxi.com](https://www.minimaxi.com) (China)
-- A browser available on the local machine (or use `--no-browser` for remote sessions)
-## Quick Start
-```bash
-# Launch the provider and model picker
-hermes model
-# → Select "MiniMax (OAuth)" from the provider list
-# → Hermes opens your browser to the MiniMax authorization page
-# → Approve access in the browser
-# → Select a model (MiniMax-M2.7 or MiniMax-M2.7-highspeed)
-# → Start chatting
-hermes
-```
-After the first login, credentials are stored under `~/.hermes/auth.json` and are refreshed automatically before each session.
-## Logging In Manually
-You can trigger a login without going through the model picker:
-```bash
-hermes auth add minimax-oauth
-```
-### China region
-If your account is on the China platform (`minimaxi.com`), use the API-key-based `minimax-cn` provider instead — `minimax-cn` is registered with `auth_type="api_key"` only (no OAuth flow). Configure `MINIMAX_CN_API_KEY` (and optionally `MINIMAX_CN_BASE_URL`) directly:
-```bash
-echo 'MINIMAX_CN_API_KEY=your-key' >> ~/.hermes/.env
-```
-### Remote / headless sessions
-On servers or containers where no browser is available:
-```bash
-hermes auth add minimax-oauth --no-browser
-```
-Hermes will print the verification URL and user code — open the URL on any device and enter the code when prompted.
-## The OAuth Flow
-Hermes implements a PKCE browser OAuth flow against the MiniMax OAuth endpoints:
-1. Hermes generates a PKCE verifier / challenge pair and a random state value.
-2. It POSTs to `{base_url}/oauth/code` with the challenge and receives a `user_code` and `verification_uri`.
-3. Your browser opens `verification_uri`. If prompted, enter the `user_code`.
-4. Hermes polls `{base_url}/oauth/token` until the token arrives (or the deadline passes).
-5. Tokens (`access_token`, `refresh_token`, expiry) are saved to `~/.hermes/auth.json` under the `minimax-oauth` key.
-Token refresh (standard OAuth `refresh_token` grant) runs automatically at each session start when the access token is within 60 seconds of expiry.
-## Checking Login Status
-```bash
-hermes doctor
-```
-The `◆ Auth Providers` section will show:
-```
-✓ MiniMax OAuth  (logged in, region=global)
-```
-or, if not logged in:
-```
-⚠ MiniMax OAuth  (not logged in)
-```
-## Switching Models
-```bash
-hermes model
-# → Select "MiniMax (OAuth)"
-# → Pick from the model list
-```
-Or set the model directly:
-```bash
-hermes config set model.default MiniMax-M2.7
-hermes config set model.provider minimax-oauth
-```
-## Configuration Reference
-After login, `~/.hermes/config.yaml` will contain entries similar to:
-```yaml
-model:
-  default: MiniMax-M2.7
-  provider: minimax-oauth
-  base_url: https://api.minimax.io/anthropic
-```
-### Region endpoints
-| Provider id | Portal | Inference endpoint |
-|-------------|--------|-------------------|
-| `minimax-oauth` (global) | `https://api.minimax.io` | `https://api.minimax.io/anthropic` |
-| `minimax-cn` (China) | `https://api.minimaxi.com` | `https://api.minimaxi.com/anthropic` |
-### Provider aliases
-All of the following resolve to `minimax-oauth`:
-```bash
-hermes --provider minimax-oauth    # canonical
-hermes --provider minimax-portal   # alias
-hermes --provider minimax-global   # alias
-hermes --provider minimax_oauth    # alias (underscore form)
-```
-## Environment Variables
-The `minimax-oauth` provider does **not** use `MINIMAX_API_KEY` or `MINIMAX_BASE_URL`. Those variables are for the API-key-based `minimax` and `minimax-cn` providers only.
-| Variable | Effect |
-|----------|--------|
-| `MINIMAX_API_KEY` | Used by `minimax` provider only — ignored for `minimax-oauth` |
-| `MINIMAX_CN_API_KEY` | Used by `minimax-cn` provider only — ignored for `minimax-oauth` |
-To use `minimax-oauth` as the active provider, set `model.provider: minimax-oauth` in `config.yaml` (use `hermes setup` for the guided flow), or pass `--provider minimax-oauth` for a single invocation:
-```bash
-hermes --provider minimax-oauth
-```
-## Models
-| Model | Best for |
-|-------|----------|
-| `MiniMax-M2.7` | Long-context reasoning, complex tool-calling |
-| `MiniMax-M2.7-highspeed` | Lower latency, lighter tasks, auxiliary calls |
-Both models support up to 200,000 tokens of context.
-`MiniMax-M2.7` is also used automatically as the auxiliary model for vision and delegation tasks when `minimax-oauth` is the primary provider.
-## Troubleshooting
-### Token expired — not re-logging in automatically
-Hermes refreshes the token on every session start if it is within 60 seconds of expiry. If the access token is already expired (for example, after a long offline period), the refresh happens automatically on the next request. If refresh fails with `refresh_token_reused` or `invalid_grant`, Hermes marks the session as requiring re-login.
-When the refresh failure is terminal (HTTP 4xx, `invalid_grant`, revoked grant, etc.), Hermes marks the refresh token as dead and quarantines it locally so it doesn't keep replaying the doomed exchange. The agent surfaces a single "re-authentication required" message and stays out of the way until you log in again.
-**Fix:** run `hermes auth add minimax-oauth` again to start a fresh login. The quarantine clears on the next successful exchange.
-### Authorization timed out
-The device-code flow has a finite expiry window. If you don't approve the login in time, Hermes raises a timeout error.
-**Fix:** re-run `hermes auth add minimax-oauth` (or `hermes model`). The flow starts fresh.
-### State mismatch (possible CSRF)
-Hermes detected that the `state` value returned by the authorization server does not match what it sent.
-**Fix:** re-run the login. If it persists, check for a proxy or redirect that is modifying the OAuth response.
-### Logging in from a remote server
-If `hermes` cannot open a browser window, use `--no-browser`:
-```bash
-hermes auth add minimax-oauth --no-browser
-```
-Hermes prints the URL and code. Open the URL on any device and complete the flow there.
-### "Not logged into MiniMax OAuth" error at runtime
-The auth store has no credentials for `minimax-oauth`. You have not logged in yet, or the credential file was deleted.
-**Fix:** run `hermes model` and select MiniMax (OAuth), or run `hermes auth add minimax-oauth`.
-## Logging Out
-To remove stored MiniMax OAuth credentials:
-```bash
-hermes auth logout minimax-oauth
-```
-## See Also
-- [AI Providers reference](../integrations/providers.md)
-- [Environment Variables](../reference/environment-variables.md)
-- [Configuration](../user-guide/configuration.md)
-- [hermes doctor](../reference/cli-commands.md)

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/guides/oauth-over-ssh.md DELETED Viewed

@@ -1,172 +0,0 @@
----
-sidebar_position: 17
-title: "OAuth over SSH / Remote Hosts"
-description: "How to complete browser-based OAuth (Spotify, MCP servers) when Hermes runs on a remote machine, container, or behind a jump box"
----
-# OAuth over SSH / Remote Hosts
-Some Hermes providers — **Spotify** and **remote MCP servers** (Linear, Sentry, Atlassian, Asana, Figma, …) — use a *loopback redirect* OAuth flow. The auth server redirects your browser to `http://127.0.0.1:<port>/callback` so a tiny HTTP listener started by Hermes can grab the authorization code.
-This works perfectly when Hermes and your browser are on the same machine. It breaks the moment they aren't: your laptop's browser tries to reach `127.0.0.1` on **your laptop**, but the listener is bound to `127.0.0.1` on **the remote server**.
-The fix is a one-line SSH local-forward. For MCP servers on an interactive terminal, you can often paste the redirect URL back instead (no tunnel).
-**xAI Grok OAuth (`xai-oauth`) uses OAuth device code**, not a loopback callback — open the printed verification URL in any browser and Hermes polls until approval. No SSH tunnel is required. See [xAI Grok OAuth](./xai-grok-oauth.md).
-## TL;DR
-```bash
-# On your local machine (laptop), in a separate terminal:
-ssh -N -L 43827:127.0.0.1:43827 user@remote-host
-# In your existing SSH session on the remote machine:
-hermes auth spotify --no-browser
-# → Hermes prints an authorize URL. Open it in a browser on your laptop.
-# → Your browser redirects to 127.0.0.1:43827/callback, the tunnel forwards
-#   the request to the remote listener, login completes.
-```
-Hermes prints the exact port it bound to on the `Waiting for callback on ...` line — copy it from there. Spotify defaults to port `43827`.
-## Which Providers Need This
-| Provider | Loopback port | Tunnel needed? |
-|----------|---------------|----------------|
-| Spotify | `43827` (default) | Yes, when Hermes is remote |
-| MCP servers (`auth: oauth`) | auto-picked per server | Yes, when Hermes is remote (or paste redirect URL) |
-| `xai-oauth` (Grok SuperGrok) | n/a | No — device code flow |
-| `anthropic` (Claude Pro/Max) | n/a | No — paste-the-code flow |
-| `openai-codex` (ChatGPT Plus/Pro) | n/a | No — device code flow |
-| `minimax`, `nous-portal` | n/a | No — device code flow |
-| `openrouter` (`hermes auth add openrouter --type oauth`) | OS-assigned, local only | No — over SSH Hermes switches to OpenRouter's headless flow and asks you to paste the code shown in the browser |
-If your provider isn't in the table, you don't need a tunnel.
-## MCP Servers
-**Desktop Skills → MCP:** the native app receives the callback on your computer
-and relays it to the selected connection and profile, so this flow does not need
-an SSH callback tunnel or `dashboard.public_url`. Tokens stay on the owning
-backend profile. Leaving the MCP tab or changing its scope cancels pending
-sign-in. If Desktop asks you to update the backend, update it before retrying;
-it does not fall back to a remote HTTP callback. The terminal workflows below
-are unchanged.
-Remote MCP servers (Linear, Sentry, Atlassian, Asana, Figma, etc.) use the same loopback redirect flow. Hermes auto-picks a free port per server and prints the authorize URL when the OAuth flow kicks off — either at startup (when a new server appears in `mcp_servers:`) or when you run `hermes mcp login <server>`.
-You have two ways to complete it from a remote host:
-**Option 1 — paste the redirect URL back (no setup, works anywhere).** On an interactive terminal, Hermes prompts you to paste the redirect URL alongside running the local listener. After approving in your browser, the redirect to `http://127.0.0.1:<port>/callback` will show a connection error — that's expected. Copy the **full URL from the browser's address bar** and paste it at the Hermes prompt:
-```
-  MCP OAuth: authorization required.
-  Open this URL in your browser:
-    https://mcp.linear.app/authorize?response_type=code&...
-  Or paste the redirect URL here (or the ?code=...&state=... portion) and press Enter:
-> https://mcp.linear.app/callback?code=abc123&state=xyz
-  Got authorization code from paste — completing flow.
-```
-A bare `?code=...&state=...` query string is accepted too. This works for any MCP server with `auth: oauth` and requires no SSH config changes.
-**Option 2 — SSH port forward (same as Spotify).** Hermes prints the exact port it bound to in the SSH-session hint. Open a separate terminal on your laptop:
-```bash
-ssh -N -L <port>:127.0.0.1:<port> user@remote-host
-```
-Then open the authorize URL in your browser as normal; the redirect tunnels through and the listener picks it up. Use this when you need the flow to complete unattended (e.g. scripted re-auth where you can't paste interactively).
-**Pitfall — the 30s config-reload race.** If you edit `~/.hermes/config.yaml` to add an OAuth MCP server from inside a running Hermes session, the CLI auto-reloads MCP connections with a 30s timeout. That's not enough time to complete an interactive OAuth flow, and the reload will give up. Use `hermes mcp login <server>` from a fresh terminal instead — it has no such cap and waits the full 5 min for you to paste back.
-## Why the listener can't just bind 0.0.0.0
-Spotify and most MCP OAuth servers validate the `redirect_uri` parameter against an allowlist. Both require the loopback form (`http://127.0.0.1:<exact-port>/callback`). Binding the listener to `0.0.0.0` or a different port would cause the auth server to reject the request as a redirect_uri mismatch. The SSH tunnel keeps the loopback URI intact end-to-end.
-## Step-by-step: single SSH hop
-### 1. Start the tunnel from your local machine
-```bash
-# Spotify (port 43827)
-ssh -N -L 43827:127.0.0.1:43827 user@remote-host
-```
-`-N` means "don't open a remote shell, just hold the tunnel open." Keep this terminal running for the duration of the login.
-### 2. In a separate SSH session, run the auth command
-```bash
-ssh user@remote-host
-hermes auth spotify --no-browser
-```
-Hermes detects the SSH session, skips the browser auto-open, and prints an authorize URL plus a `Waiting for callback on http://127.0.0.1:<port>/callback` line.
-### 3. Open the URL in your local browser
-Copy the authorize URL from the remote terminal and paste it into the browser on your laptop. Approve the consent screen. The auth server redirects to `http://127.0.0.1:<port>/callback`. Your browser hits the tunnel, the request is forwarded to the remote listener, and Hermes prints `Login successful!`.
-You can tear down the tunnel (Ctrl+C in the first terminal) once you see the success line.
-## Step-by-step: through a jump box
-If you reach Hermes through a bastion / jump host, use SSH's built-in `-J` (ProxyJump):
-```bash
-ssh -N -L 43827:127.0.0.1:43827 -J jump-user@jump-host user@final-host
-```
-This chains a SSH connection through the jump host without putting the loopback port on the jump box itself. The local `127.0.0.1:43827` on your laptop tunnels straight through to `127.0.0.1:43827` on the final remote host.
-For older OpenSSH that doesn't support `-J`, the long form is:
-```bash
-ssh -N \
-    -o "ProxyCommand=ssh -W %h:%p jump-user@jump-host" \
-    -L 43827:127.0.0.1:43827 \
-    user@final-host
-```
-## Mosh, tmux, ssh ControlMaster
-The tunnel is a property of the underlying SSH connection. If you're running Hermes inside `tmux` over a mosh session, the mosh roaming doesn't carry the `-L` forwarding. Open a *separate* plain SSH session **only** for the `-L` tunnel — that's the connection that has to stay alive during the auth flow. Your interactive mosh/tmux session can keep running Hermes normally.
-If you use `ssh -o ControlMaster=auto`, port forwards on a multiplexed connection share the master's lifetime. Restart the master if the tunnel doesn't come up:
-```bash
-ssh -O exit user@remote-host
-ssh -N -L 43827:127.0.0.1:43827 user@remote-host
-```
-## Troubleshooting
-### `bind [127.0.0.1]:43827: Address already in use`
-Something on your laptop is already using that port. Either the previous tunnel didn't shut down cleanly, or a local Hermes is also listening on it. Find and kill the offender:
-```bash
-# macOS / Linux
-lsof -iTCP:43827 -sTCP:LISTEN
-kill <PID>
-```
-Then retry the `ssh -L` command.
-### Authorization timed out waiting for the local callback
-The redirect never made it back to the remote listener. Check the tunnel is still alive (`ssh -N` doesn't show output, so look at the terminal you started it from), confirm you used the port from the latest `Waiting for callback on ...` line (Hermes may auto-bump if the preferred port is busy), restart the tunnel if needed, and re-run the auth command.
-### Tokens land in the wrong `~/.hermes`
-The tokens are written under the Linux user that ran `hermes auth add ...`. If your gateway / systemd service runs as a different user (e.g. `root` or a dedicated `hermes` user), authenticate as **that** user so the tokens land in their `~/.hermes/auth.json`. `sudo -u hermes -i` or equivalent.
-## See Also
-- [xAI Grok OAuth](./xai-grok-oauth.md) — device code; no SSH tunnel
-- [Spotify (`Running over SSH`)](../user-guide/features/spotify.md#running-over-ssh--in-a-headless-environment)
-- [Native MCP client (OAuth section)](../user-guide/features/mcp.md#oauth-authenticated-http-servers)
-- [SSH `-J` / ProxyJump (man page)](https://man.openbsd.org/ssh#J)