better-dsh 0.2.5 → 0.3.0

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/guides/run-nemotron-3-ultra-free.md

@@ -1,123 +0,0 @@
----
-sidebar_position: 0
-title: "Run Nemotron 3 Ultra free in Hermes Agent"
-description: "Try NVIDIA Nemotron 3 Ultra on Nous Portal — free June 4–18 — with day 0 support in Hermes Agent"
----
-
-# Run Nemotron 3 Ultra free in Hermes Agent
-
-Nous Research has been inducted into the **Nemotron Coalition** of leading AI labs working with **NVIDIA** to advance open frontier foundation models. In honor of this, we've partnered with **Nebius** to provide **Nemotron 3 Ultra** free on [Nous Portal](https://portal.nousresearch.com) for two weeks (**June 4th – June 18th**). Follow the instructions below to try the model in your Hermes Agent today.
-
-:::info Limited-time offer
-The `nvidia/nemotron-3-ultra:free` tier is available from **June 4th to June 18th**. The `:free` tag is what keeps it on the no-cost plan — pick that exact variant.
-:::
-
-Pick whichever install fits you. The **desktop app** is the easiest — no terminal required. If you live in a terminal, the **command-line** install is right below it.
-
-## Option A — Desktop app (recommended)
-
-The simplest path: a one-click installer with a guided, point-and-click setup. No terminal needed.
-
-### 1. Download and install
-
-[Download the Hermes Desktop installer](https://hermes-agent.nousresearch.com/) for macOS or Windows, then open it. On first launch it finishes setting itself up (usually under a minute).
-
-### 2. Connect Nous Portal
-
-When the app opens, you'll see a "Let's get you set up" screen. Click **Nous Portal** (marked **Recommended**). Your browser opens — create a [Nous Portal](https://portal.nousresearch.com) account (or sign in), choose the **Free** plan, and authorize Hermes. The app connects automatically.
-
-### 3. Pick the free Nemotron 3 Ultra model
-
-After connecting, the app shows a **Default model** card. Click **Change**, search for **nemotron 3 ultra**, and select the variant tagged **Free tier**:
-
-```
-nvidia/nemotron-3-ultra:free
-```
-
-The `:free` tag is what keeps it on the no-cost tier — pick that variant.
-
-### 4. Start chatting
-
-Click **Start chatting**. That's it — you're talking to Nemotron 3 Ultra, free.
-
-## Option B — Command line
-
-Prefer the terminal?
-
-### 1. Install Hermes Agent
-
-On macOS/Linux/WSL2/Android, run
-
-```bash
-curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
-```
-
-On Windows, run
-
-```powershell
-iex (irm https://hermes-agent.nousresearch.com/install.ps1)
-```
-
-Prefer to review first? Download [`install.sh`](https://hermes-agent.nousresearch.com/install.sh), inspect it, then run it.
-
-After it finishes, reload your shell:
-
-```bash
-source ~/.bashrc   # or source ~/.zshrc
-```
-
-### 2. Run Quick Setup
-
-```bash
-hermes setup
-```
-
-Select **Quick Setup**. Hermes opens a browser tab and waits for you to finish the next steps.
-
-### 3. Create a Nous Portal account
-
-In the browser, create a [Nous Portal](https://portal.nousresearch.com) account (or sign in) and choose the **Free** plan.
-
-### 4. Connect your account
-
-When prompted to connect your account to Hermes Agent, click **Connect**. You'll see a confirmation once it's linked.
-
-### 5. Select the free Nemotron 3 Ultra model
-
-Return to your terminal. From the model list, select:
-
-```
-nvidia/nemotron-3-ultra:free
-```
-
-The `:free` tag is what keeps it on the no-cost tier, so make sure you pick that variant.
-
-### 6. Start chatting
-
-Complete the remaining Quick Setup prompts, then run:
-
-```bash
-hermes
-```
-
-That's it — you're talking to Nemotron 3 Ultra, free.
-
-## Switching to it later
-
-Already set up with another model?
-
-- **Desktop app:** open the model picker, search for **nemotron 3 ultra**, and select the **Free tier** variant.
-- **CLI / TUI:** switch any time from inside a session with `/model nvidia/nemotron-3-ultra:free`, or run `/model` to open the picker and choose it from the list.
-
-## Troubleshooting
-
-- **Don't see the model in the list?** Make sure you finished the Nous Portal connection and that you're on the **Free** plan. In the CLI, `hermes portal info` confirms you're logged in and routing through Nous.
-- **Picked the wrong variant?** Re-select `nvidia/nemotron-3-ultra:free` — the `:free` suffix is required to stay on the no-cost tier.
-- **Browser didn't open / you're on a remote host (CLI)?** See [OAuth over SSH / Remote Hosts](/guides/oauth-over-ssh) for port-forwarding workarounds.
-
-## See also
-
-- **[Desktop App](/user-guide/desktop)** — The native one-click app (macOS, Windows, Linux)
-- **[Run Hermes Agent with Nous Portal](/guides/run-hermes-with-nous-portal)** — Full Portal walkthrough: models, Tool Gateway, and verification
-- **[Nous Portal integration](/integrations/nous-portal)** — What's in the subscription
-- **[Quickstart](/getting-started/quickstart)** — Install-to-chat in under 5 minutes

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/guides/secure-hermes-on-a-work-machine.md

@@ -1,182 +0,0 @@
----
-sidebar_position: 26
-title: "Running Hermes on a Personal or Work Machine"
-description: "A security-posture walkthrough for running Hermes Agent on the machine you live on — what the defaults protect, how to tighten further, and how to undo mistakes"
----
-
-# Running Hermes on a Personal or Work Machine
-
-You're about to run an agent on the machine you live on — a personal laptop or an employer-managed workstation. What's the safe posture?
-
-Short answer: the defaults already do most of the work. Hermes ships secure-by-default, with a defense-in-depth model covering command approval, file-write safety, and credential handling. This page walks through what's on out of the box, which knobs to tighten for a shared or work machine, and how to undo mistakes when they happen. Every control here is covered in depth in the [Security](/user-guide/security) guide.
-
-## What the Defaults Already Protect
-
-Fresh install, no configuration — these protections are active:
-
-**Dangerous commands require approval.** Before executing any command, Hermes checks it against a curated list of dangerous patterns — recursive deletes, writes to `/etc/`, disk operations, pipe-to-shell, and more. The default `approvals.mode: smart` uses an auxiliary LLM to assess risk: low-risk commands are auto-approved for that command only, genuinely dangerous commands are auto-denied, and uncertain cases escalate to a manual prompt.
-
-**Approval prompts fail closed.** If you don't respond to an approval prompt within the timeout (default 300 seconds), the command is **denied**. Walking away from your desk never silently approves anything.
-
-**A hardline blocklist is the always-on floor.** Some commands — `rm -rf /`, fork bombs, zeroing a physical disk — are refused **regardless** of approval mode, `--yolo`, or an explicit "allow always". The blocklist trips before the approval layer even sees the command, and there is no override flag.
-
-**File writes to sensitive paths are blocked.** The `write_file` and `patch` tools cannot touch OS credential stores (`~/.ssh/`, `~/.aws/`, `~/.kube/`, `/etc/sudoers`, `~/.netrc`), Hermes credential stores (`auth.json`, `.env`, pairing data), or project secret files (`.env`, `.env.local`, `.envrc`) anywhere on disk. Blocked writes return an error immediately — there is no approval prompt and no way to override from the chat UI.
-
-**Secrets are redacted from output.** `security.redact_secrets` is on by default: patterns that look like API keys, tokens, and passwords in tool output are redacted before they enter the conversation context and logs.
-
-**Your data goes only where you point it.** API calls go **only to the LLM provider you configure**. Hermes Agent does not collect telemetry, usage data, or analytics. Your conversations, memory, and skills are stored locally in `~/.hermes/`. See the [FAQ](/reference/faq#is-my-data-sent-anywhere).
-
-:::info
-There's more below the surface — SSRF protection on all URL-capable tools, filtered environments for MCP subprocesses, prompt-injection scanning of context files. The [Security](/user-guide/security) page documents every layer.
-:::
-
-## Tightening for a Shared or Work Machine
-
-On a machine with employer data, production credentials, or other people's files, layer these on top of the defaults.
-
-### Switch approvals to manual
-
-`smart` mode auto-approves low-risk commands. If you want to see every flagged command yourself:
-
-```yaml
-approvals:
-  mode: manual
-```
-
-Manual mode always prompts you before executing a flagged command.
-
-### Add your own deny rules
-
-`approvals.deny` is a list of glob patterns that block matching terminal commands unconditionally — even under `--yolo`, `/yolo`, or `mode: off`. It's the user-editable counterpart to the built-in hardline blocklist. Use it to declare things that must never run on this machine:
-
-```yaml
-approvals:
-  deny:
-    - "git push --force*"
-    - "*curl*|*sh*"
-    - "dd if=* of=/dev/*"
-```
-
-Patterns are case-insensitive [fnmatch](https://docs.python.org/3/library/fnmatch.html) globs matched against the whole command text, and matching runs over the same normalized/deobfuscated variants the dangerous-pattern detector uses, so simple quoting tricks don't slip past a rule. Always quote patterns — a bare leading `*` is a YAML parse error. Changes take effect immediately, no restart needed. Details: [User-Defined Deny Rules](/user-guide/security#user-defined-deny-rules-approvalsdeny).
-
-### Sandbox file writes
-
-`HERMES_WRITE_SAFE_ROOT` restricts `write_file` and `patch` to the directory prefix(es) you list — anything outside is hard-blocked. Multiple roots are separated by `:` on Unix:
-
-```bash
-export HERMES_WRITE_SAFE_ROOT=/path/to/project:/home/you/.hermes
-```
-
-Sensitive paths inside the safe root are still blocked — pointing it at `$HOME` does not allow writing `~/.ssh/id_rsa`.
-
-:::caution
-Don't add this to `~/.hermes/.env` casually. If you set it to a project directory only, the agent cannot write to `~/.hermes/cron/jobs.json`, profile skills, or other Hermes state outside that prefix. Include your Hermes home as a second root, as above.
-:::
-
-### Move command execution off the host
-
-The strongest isolation is not running commands on your machine at all. The terminal tool supports multiple [backends](/user-guide/features/tools#terminal-backends):
-
-| Backend | Isolation |
-|---------|-----------|
-| `local` | None — runs on host (dangerous-command checks apply) |
-| `docker` | Container — the container itself is the security boundary |
-| `ssh` | Remote machine — keeps execution on a separate server |
-
-```yaml
-terminal:
-  backend: docker
-  docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
-  docker_forward_env: []  # Explicit allowlist only; empty keeps secrets out of the container
-```
-
-Every Docker container runs with hardened settings — all Linux capabilities dropped (with a minimal add-back set), `no-new-privileges`, a process-count limit, and size-limited tmpfs mounts. With a container backend, destructive commands inside the container can't harm the host, which is why dangerous-command checks are skipped there.
-
-For `ssh`, set `terminal.backend: ssh` in `config.yaml` and provide host details via `TERMINAL_SSH_HOST`, `TERMINAL_SSH_USER`, and `TERMINAL_SSH_KEY` in `~/.hermes/.env`. See [Network Isolation](/user-guide/security#network-isolation).
-
-### If messaging is on: allowlists and pairing
-
-Running the [gateway](/user-guide/security#user-authorization-gateway) on this machine? The default is already deny: if no allowlists are configured and `GATEWAY_ALLOW_ALL_USERS` is not set, **all users are denied**. Keep it explicit:
-
-```bash
-# ~/.hermes/.env
-TELEGRAM_ALLOWED_USERS=123456789
-GATEWAY_ALLOWED_USERS=123456789
-```
-
-Or use DM pairing instead of hardcoding IDs: unknown users receive a one-time pairing code, and you approve them from the CLI with `hermes pairing approve <platform> <code>`. Never set `GATEWAY_ALLOW_ALL_USERS=true` on a machine you care about.
-
-## The Undo Layer: Checkpoints and `/rollback`
-
-Approval gates prevent damage; [checkpoints](/user-guide/checkpoints-and-rollback) reverse it. When enabled, Hermes automatically snapshots your project before destructive operations — `write_file`, `patch`, and destructive terminal commands like `rm`, `mv`, `sed -i`, and `git reset` — into a shadow git store under `~/.hermes/checkpoints/store/`. Your real project `.git` is never touched.
-
-Checkpoints are opt-in. Enable per-session:
-
-```bash
-hermes chat --checkpoints
-```
-
-Or globally:
-
-```yaml
-checkpoints:
-  enabled: true
-```
-
-Then, in a session:
-
-| Command | Description |
-|---------|-------------|
-| `/rollback` | List all checkpoints with change stats |
-| `/rollback diff <N>` | Preview what changed since checkpoint N |
-| `/rollback <N>` | Restore to checkpoint N (also undoes the last chat turn) |
-| `/rollback <N> <file>` | Restore a single file from checkpoint N |
-
-:::tip
-Preview with `/rollback diff <N>` before restoring, and combine checkpoints with git worktrees for maximum safety — each Hermes session in its own worktree, with checkpoints as an extra layer.
-:::
-
-## What This Threat Model Is — and Isn't
-
-Be clear-eyed about what these controls defend against. As the [Security](/user-guide/security#user-defined-deny-rules-approvalsdeny) guide puts it:
-
-> Deny rules are a guardrail against an honest-but-wrong agent, the same threat model as the dangerous-pattern detector. They are not a sandbox against a deliberately adversarial process — for that, use an isolated backend (Docker, Modal) or an egress-restricted environment.
-
-The same applies to the file-write guards: they apply to `write_file` and `patch` only, while the `terminal` tool runs as the same OS user. The denylist reduces accidental damage and gives models a clear stop signal; it does not sandbox a hostile or compromised agent. If your requirement is containment rather than guardrails, the answer is an isolated terminal backend — that's the boundary designed for it.
-
-## A Cautious Starting Config
-
-Everything above, assembled. Adjust to taste in `~/.hermes/config.yaml`:
-
-```yaml
-approvals:
-  mode: manual                  # See every flagged command yourself
-  timeout: 300                  # Unanswered prompts are denied (fail-closed)
-  deny:                         # Never-run list — survives even /yolo
-    - "git push --force*"
-    - "*curl*|*sh*"
-    - "dd if=* of=/dev/*"
-
-security:
-  redact_secrets: true          # Already the default; stated here for clarity
-
-checkpoints:
-  enabled: true                 # Snapshot before destructive operations
-
-terminal:
-  backend: docker               # Or ssh — keep execution off the host
-  docker_forward_env: []        # No host secrets inside the container
-```
-
-And in `~/.hermes/.env`, if you want the write sandbox:
-
-```bash
-HERMES_WRITE_SAFE_ROOT=/path/to/project:/home/you/.hermes
-```
-
-## See Also
-
-- **[Security](/user-guide/security)** — the full defense-in-depth reference: every approval pattern, container hardening flags, gateway authorization, MCP credential filtering
-- **[Checkpoints & Rollback](/user-guide/checkpoints-and-rollback)** — configuration, store maintenance, and restore workflows
-- **[Tools & Toolsets](/user-guide/features/tools)** — all terminal backends and their configuration
-- **[Configuration](/user-guide/configuration)** — the complete `config.yaml` reference