nodmix 2026.5.25

package/docs/install/installer.md

@@ -0,0 +1,455 @@
+---
+summary: "How the installer scripts work (install.sh, install-cli.sh, install.ps1), flags, and automation"
+read_when:
+  - You want to understand `nodmix.ai/install.sh`
+  - You want to automate installs (CI / headless)
+  - You want to install from a GitHub checkout
+title: "Installer internals"
+---
+
+Nodmix ships three installer scripts, served from `nodmix.ai`.
+
+| Script                             | Platform             | What it does                                                                                                   |
+| ---------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------- |
+| [`install.sh`](#installsh)         | macOS / Linux / WSL  | Installs Node if needed, installs Nodmix via npm (default) or git, and can run onboarding.                   |
+| [`install-cli.sh`](#install-clish) | macOS / Linux / WSL  | Installs Node + Nodmix into a local prefix (`~/.nodmix`) with npm or git checkout modes. No root required. |
+| [`install.ps1`](#installps1)       | Windows (PowerShell) | Installs Node if needed, installs Nodmix via npm (default) or git, and can run onboarding.                   |
+
+## Quick commands
+
+<Tabs>
+  <Tab title="install.sh">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://nodmix.ai/install.sh | bash
+    ```
+
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://nodmix.ai/install.sh | bash -s -- --help
+    ```
+
+  </Tab>
+  <Tab title="install-cli.sh">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://nodmix.ai/install-cli.sh | bash
+    ```
+
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://nodmix.ai/install-cli.sh | bash -s -- --help
+    ```
+
+  </Tab>
+  <Tab title="install.ps1">
+    ```powershell
+    iwr -useb https://nodmix.ai/install.ps1 | iex
+    ```
+
+    ```powershell
+    & ([scriptblock]::Create((iwr -useb https://nodmix.ai/install.ps1))) -Tag beta -NoOnboard -DryRun
+    ```
+
+  </Tab>
+</Tabs>
+
+<Note>
+If install succeeds but `nodmix` is not found in a new terminal, see [Node.js troubleshooting](/install/node#troubleshooting).
+</Note>
+
+---
+
+<a id="installsh"></a>
+
+## install.sh
+
+<Tip>
+Recommended for most interactive installs on macOS/Linux/WSL.
+</Tip>
+
+### Flow (install.sh)
+
+<Steps>
+  <Step title="Detect OS">
+    Supports macOS and Linux (including WSL). If macOS is detected, installs Homebrew if missing.
+  </Step>
+  <Step title="Ensure Node.js 24 by default">
+    Checks Node version and installs Node 24 if needed (Homebrew on macOS, NodeSource setup scripts on Linux apt/dnf/yum). Nodmix still supports Node 22 LTS, currently `22.19+`, for compatibility.
+  </Step>
+  <Step title="Ensure Git">
+    Installs Git if missing.
+  </Step>
+  <Step title="Install Nodmix">
+    - `npm` method (default): global npm install
+    - `git` method: clone/update repo, install deps with pnpm, build, then install wrapper at `~/.local/bin/nodmix`
+
+  </Step>
+  <Step title="Post-install tasks">
+    - Refreshes a loaded gateway service best-effort (`nodmix gateway install --force`, then restart)
+    - Runs `nodmix doctor --non-interactive` on upgrades and git installs (best effort)
+    - Attempts onboarding when appropriate (TTY available, onboarding not disabled, and bootstrap/config checks pass)
+    - Defaults `SHARP_IGNORE_GLOBAL_LIBVIPS=1`
+
+  </Step>
+</Steps>
+
+### Source checkout detection
+
+If run inside an Nodmix checkout (`package.json` + `pnpm-workspace.yaml`), the script offers:
+
+- use checkout (`git`), or
+- use global install (`npm`)
+
+If no TTY is available and no install method is set, it defaults to `npm` and warns.
+
+The script exits with code `2` for invalid method selection or invalid `--install-method` values.
+
+### Examples (install.sh)
+
+<Tabs>
+  <Tab title="Default">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://nodmix.ai/install.sh | bash
+    ```
+  </Tab>
+  <Tab title="Skip onboarding">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://nodmix.ai/install.sh | bash -s -- --no-onboard
+    ```
+  </Tab>
+  <Tab title="Git install">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://nodmix.ai/install.sh | bash -s -- --install-method git
+    ```
+  </Tab>
+  <Tab title="GitHub main via npm">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://nodmix.ai/install.sh | bash -s -- --version main
+    ```
+  </Tab>
+  <Tab title="Dry run">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://nodmix.ai/install.sh | bash -s -- --dry-run
+    ```
+  </Tab>
+</Tabs>
+
+<AccordionGroup>
+  <Accordion title="Flags reference">
+
+| Flag                                  | Description                                                |
+| ------------------------------------- | ---------------------------------------------------------- |
+| `--install-method npm\|git`           | Choose install method (default: `npm`). Alias: `--method`  |
+| `--npm`                               | Shortcut for npm method                                    |
+| `--git`                               | Shortcut for git method. Alias: `--github`                 |
+| `--version <version\|dist-tag\|spec>` | npm version, dist-tag, or package spec (default: `latest`) |
+| `--beta`                              | Use beta dist-tag if available, else fallback to `latest`  |
+| `--git-dir <path>`                    | Checkout directory (default: `~/nodmix`). Alias: `--dir` |
+| `--no-git-update`                     | Skip `git pull` for existing checkout                      |
+| `--no-prompt`                         | Disable prompts                                            |
+| `--no-onboard`                        | Skip onboarding                                            |
+| `--onboard`                           | Enable onboarding                                          |
+| `--dry-run`                           | Print actions without applying changes                     |
+| `--verbose`                           | Enable debug output (`set -x`, npm notice-level logs)      |
+| `--help`                              | Show usage (`-h`)                                          |
+
+  </Accordion>
+
+  <Accordion title="Environment variables reference">
+
+| Variable                                                | Description                                   |
+| ------------------------------------------------------- | --------------------------------------------- |
+| `NODMIX_INSTALL_METHOD=git\|npm`                      | Install method                                |
+| `NODMIX_VERSION=latest\|next\|main\|<semver>\|<spec>` | npm version, dist-tag, or package spec        |
+| `NODMIX_BETA=0\|1`                                    | Use beta if available                         |
+| `NODMIX_GIT_DIR=<path>`                               | Checkout directory                            |
+| `NODMIX_GIT_UPDATE=0\|1`                              | Toggle git updates                            |
+| `NODMIX_NO_PROMPT=1`                                  | Disable prompts                               |
+| `NODMIX_NO_ONBOARD=1`                                 | Skip onboarding                               |
+| `NODMIX_DRY_RUN=1`                                    | Dry run mode                                  |
+| `NODMIX_VERBOSE=1`                                    | Debug mode                                    |
+| `NODMIX_NPM_LOGLEVEL=error\|warn\|notice`             | npm log level                                 |
+| `SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1`                      | Control sharp/libvips behavior (default: `1`) |
+
+  </Accordion>
+</AccordionGroup>
+
+---
+
+<a id="install-clish"></a>
+
+## install-cli.sh
+
+<Info>
+Designed for environments where you want everything under a local prefix
+(default `~/.nodmix`) and no system Node dependency. Supports npm installs
+by default, plus git-checkout installs under the same prefix flow.
+</Info>
+
+### Flow (install-cli.sh)
+
+<Steps>
+  <Step title="Install local Node runtime">
+    Downloads a pinned supported Node LTS tarball (the version is embedded in the script and updated independently) to `<prefix>/tools/node-v<version>` and verifies SHA-256.
+  </Step>
+  <Step title="Ensure Git">
+    If Git is missing, attempts install via apt/dnf/yum on Linux or Homebrew on macOS.
+  </Step>
+  <Step title="Install Nodmix under prefix">
+    - `npm` method (default): installs under the prefix with npm, then writes wrapper to `<prefix>/bin/nodmix`
+    - `git` method: clones/updates a checkout (default `~/nodmix`) and still writes the wrapper to `<prefix>/bin/nodmix`
+
+  </Step>
+  <Step title="Refresh loaded gateway service">
+    If a gateway service is already loaded from that same prefix, the script runs
+    `nodmix gateway install --force`, then `nodmix gateway restart`, and
+    probes gateway health best-effort.
+  </Step>
+</Steps>
+
+### Examples (install-cli.sh)
+
+<Tabs>
+  <Tab title="Default">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://nodmix.ai/install-cli.sh | bash
+    ```
+  </Tab>
+  <Tab title="Custom prefix + version">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://nodmix.ai/install-cli.sh | bash -s -- --prefix /opt/nodmix --version latest
+    ```
+  </Tab>
+  <Tab title="Git install">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://nodmix.ai/install-cli.sh | bash -s -- --install-method git --git-dir ~/nodmix
+    ```
+  </Tab>
+  <Tab title="Automation JSON output">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://nodmix.ai/install-cli.sh | bash -s -- --json --prefix /opt/nodmix
+    ```
+  </Tab>
+  <Tab title="Run onboarding">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://nodmix.ai/install-cli.sh | bash -s -- --onboard
+    ```
+  </Tab>
+</Tabs>
+
+<AccordionGroup>
+  <Accordion title="Flags reference">
+
+| Flag                        | Description                                                                     |
+| --------------------------- | ------------------------------------------------------------------------------- |
+| `--prefix <path>`           | Install prefix (default: `~/.nodmix`)                                         |
+| `--install-method npm\|git` | Choose install method (default: `npm`). Alias: `--method`                       |
+| `--npm`                     | Shortcut for npm method                                                         |
+| `--git`, `--github`         | Shortcut for git method                                                         |
+| `--git-dir <path>`          | Git checkout directory (default: `~/nodmix`). Alias: `--dir`                  |
+| `--version <ver>`           | Nodmix version or dist-tag (default: `latest`)                                |
+| `--node-version <ver>`      | Node version (default: `22.22.0`)                                               |
+| `--json`                    | Emit NDJSON events                                                              |
+| `--onboard`                 | Run `nodmix onboard` after install                                            |
+| `--no-onboard`              | Skip onboarding (default)                                                       |
+| `--set-npm-prefix`          | On Linux, force npm prefix to `~/.npm-global` if current prefix is not writable |
+| `--help`                    | Show usage (`-h`)                                                               |
+
+  </Accordion>
+
+  <Accordion title="Environment variables reference">
+
+| Variable                                    | Description                                   |
+| ------------------------------------------- | --------------------------------------------- |
+| `NODMIX_PREFIX=<path>`                    | Install prefix                                |
+| `NODMIX_INSTALL_METHOD=git\|npm`          | Install method                                |
+| `NODMIX_VERSION=<ver>`                    | Nodmix version or dist-tag                  |
+| `NODMIX_NODE_VERSION=<ver>`               | Node version                                  |
+| `NODMIX_GIT_DIR=<path>`                   | Git checkout directory for git installs       |
+| `NODMIX_GIT_UPDATE=0\|1`                  | Toggle git updates for existing checkouts     |
+| `NODMIX_NO_ONBOARD=1`                     | Skip onboarding                               |
+| `NODMIX_NPM_LOGLEVEL=error\|warn\|notice` | npm log level                                 |
+| `SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1`          | Control sharp/libvips behavior (default: `1`) |
+
+  </Accordion>
+</AccordionGroup>
+
+---
+
+<a id="installps1"></a>
+
+## install.ps1
+
+### Flow (install.ps1)
+
+<Steps>
+  <Step title="Ensure PowerShell + Windows environment">
+    Requires PowerShell 5+.
+  </Step>
+  <Step title="Ensure Node.js 24 by default">
+    If missing, attempts install via winget, then Chocolatey, then Scoop. Node 22 LTS, currently `22.19+`, remains supported for compatibility.
+  </Step>
+  <Step title="Install Nodmix">
+    - `npm` method (default): global npm install using selected `-Tag`, launched from a writable installer temp directory so shells opened in protected folders such as `C:\` still work
+    - `git` method: clone/update repo, install/build with pnpm, and install wrapper at `%USERPROFILE%\.local\bin\nodmix.cmd`
+
+  </Step>
+  <Step title="Post-install tasks">
+    - Adds needed bin directory to user PATH when possible
+    - Refreshes a loaded gateway service best-effort (`nodmix gateway install --force`, then restart)
+    - Runs `nodmix doctor --non-interactive` on upgrades and git installs (best effort)
+
+  </Step>
+  <Step title="Handle failures">
+    `iwr ... | iex` and scriptblock installs report a terminating error without closing the current PowerShell session. Direct `powershell -File` / `pwsh -File` installs still exit non-zero for automation.
+  </Step>
+</Steps>
+
+### Examples (install.ps1)
+
+<Tabs>
+  <Tab title="Default">
+    ```powershell
+    iwr -useb https://nodmix.ai/install.ps1 | iex
+    ```
+  </Tab>
+  <Tab title="Git install">
+    ```powershell
+    & ([scriptblock]::Create((iwr -useb https://nodmix.ai/install.ps1))) -InstallMethod git
+    ```
+  </Tab>
+  <Tab title="GitHub main via npm">
+    ```powershell
+    & ([scriptblock]::Create((iwr -useb https://nodmix.ai/install.ps1))) -Tag main
+    ```
+  </Tab>
+  <Tab title="Custom git directory">
+    ```powershell
+    & ([scriptblock]::Create((iwr -useb https://nodmix.ai/install.ps1))) -InstallMethod git -GitDir "C:\nodmix"
+    ```
+  </Tab>
+  <Tab title="Dry run">
+    ```powershell
+    & ([scriptblock]::Create((iwr -useb https://nodmix.ai/install.ps1))) -DryRun
+    ```
+  </Tab>
+  <Tab title="Debug trace">
+    ```powershell
+    # install.ps1 has no dedicated -Verbose flag yet.
+    Set-PSDebug -Trace 1
+    & ([scriptblock]::Create((iwr -useb https://nodmix.ai/install.ps1))) -NoOnboard
+    Set-PSDebug -Trace 0
+    ```
+  </Tab>
+</Tabs>
+
+<AccordionGroup>
+  <Accordion title="Flags reference">
+
+| Flag                        | Description                                                |
+| --------------------------- | ---------------------------------------------------------- |
+| `-InstallMethod npm\|git`   | Install method (default: `npm`)                            |
+| `-Tag <tag\|version\|spec>` | npm dist-tag, version, or package spec (default: `latest`) |
+| `-GitDir <path>`            | Checkout directory (default: `%USERPROFILE%\nodmix`)     |
+| `-NoOnboard`                | Skip onboarding                                            |
+| `-NoGitUpdate`              | Skip `git pull`                                            |
+| `-DryRun`                   | Print actions only                                         |
+
+  </Accordion>
+
+  <Accordion title="Environment variables reference">
+
+| Variable                           | Description        |
+| ---------------------------------- | ------------------ |
+| `NODMIX_INSTALL_METHOD=git\|npm` | Install method     |
+| `NODMIX_GIT_DIR=<path>`          | Checkout directory |
+| `NODMIX_NO_ONBOARD=1`            | Skip onboarding    |
+| `NODMIX_GIT_UPDATE=0`            | Disable git pull   |
+| `NODMIX_DRY_RUN=1`               | Dry run mode       |
+
+  </Accordion>
+</AccordionGroup>
+
+<Note>
+If `-InstallMethod git` is used and Git is missing, the script exits and prints the Git for Windows link.
+</Note>
+
+---
+
+## CI and automation
+
+Use non-interactive flags/env vars for predictable runs.
+
+<Tabs>
+  <Tab title="install.sh (non-interactive npm)">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://nodmix.ai/install.sh | bash -s -- --no-prompt --no-onboard
+    ```
+  </Tab>
+  <Tab title="install.sh (non-interactive git)">
+    ```bash
+    NODMIX_INSTALL_METHOD=git NODMIX_NO_PROMPT=1 \
+      curl -fsSL --proto '=https' --tlsv1.2 https://nodmix.ai/install.sh | bash
+    ```
+  </Tab>
+  <Tab title="install-cli.sh (JSON)">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://nodmix.ai/install-cli.sh | bash -s -- --json --prefix /opt/nodmix
+    ```
+  </Tab>
+  <Tab title="install.ps1 (skip onboarding)">
+    ```powershell
+    & ([scriptblock]::Create((iwr -useb https://nodmix.ai/install.ps1))) -NoOnboard
+    ```
+  </Tab>
+</Tabs>
+
+---
+
+## Troubleshooting
+
+<AccordionGroup>
+  <Accordion title="Why is Git required?">
+    Git is required for `git` install method. For `npm` installs, Git is still checked/installed to avoid `spawn git ENOENT` failures when dependencies use git URLs.
+  </Accordion>
+
+  <Accordion title="Why does npm hit EACCES on Linux?">
+    Some Linux setups point npm global prefix to root-owned paths. `install.sh` can switch prefix to `~/.npm-global` and append PATH exports to shell rc files (when those files exist).
+  </Accordion>
+
+  <Accordion title="sharp/libvips issues">
+    The scripts default `SHARP_IGNORE_GLOBAL_LIBVIPS=1` to avoid sharp building against system libvips. To override:
+
+    ```bash
+    SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL --proto '=https' --tlsv1.2 https://nodmix.ai/install.sh | bash
+    ```
+
+  </Accordion>
+
+  <Accordion title='Windows: "npm error spawn git / ENOENT"'>
+    Install Git for Windows, reopen PowerShell, rerun installer.
+  </Accordion>
+
+  <Accordion title='Windows: "nodmix is not recognized"'>
+    Run `npm config get prefix` and add that directory to your user PATH (no `\bin` suffix needed on Windows), then reopen PowerShell.
+  </Accordion>
+
+  <Accordion title="Windows: how to get verbose installer output">
+    `install.ps1` does not currently expose a `-Verbose` switch.
+    Use PowerShell tracing for script-level diagnostics:
+
+    ```powershell
+    Set-PSDebug -Trace 1
+    & ([scriptblock]::Create((iwr -useb https://nodmix.ai/install.ps1))) -NoOnboard
+    Set-PSDebug -Trace 0
+    ```
+
+  </Accordion>
+
+  <Accordion title="nodmix not found after install">
+    Usually a PATH issue. See [Node.js troubleshooting](/install/node#troubleshooting).
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+- [Install overview](/install)
+- [Updating](/install/updating)
+- [Uninstall](/install/uninstall)

package/docs/install/kubernetes.md

@@ -0,0 +1,196 @@
+---
+summary: "Deploy Nodmix Gateway to a Kubernetes cluster with Kustomize"
+read_when:
+  - You want to run Nodmix on a Kubernetes cluster
+  - You want to test Nodmix in a Kubernetes environment
+title: "Kubernetes"
+---
+
+A minimal starting point for running Nodmix on Kubernetes — not a production-ready deployment. It covers the core resources and is meant to be adapted to your environment.
+
+## Why not Helm?
+
+Nodmix is a single container with some config files. The interesting customization is in agent content (markdown files, skills, config overrides), not infrastructure templating. Kustomize handles overlays without the overhead of a Helm chart. If your deployment grows more complex, a Helm chart can be layered on top of these manifests.
+
+## What you need
+
+- A running Kubernetes cluster (AKS, EKS, GKE, k3s, kind, OpenShift, etc.)
+- `kubectl` connected to your cluster
+- An API key for at least one model provider
+
+## Quick start
+
+```bash
+# Replace with your provider: ANTHROPIC, GEMINI, OPENAI, or OPENROUTER
+export <PROVIDER>_API_KEY="..."
+./scripts/k8s/deploy.sh
+
+kubectl port-forward svc/nodmix 18789:18789 -n nodmix
+open http://localhost:18789
+```
+
+Retrieve the configured shared secret for the Control UI. This deploy script
+creates token auth by default:
+
+```bash
+kubectl get secret nodmix-secrets -n nodmix -o jsonpath='{.data.NODMIX_GATEWAY_TOKEN}' | base64 -d
+```
+
+For local debugging, `./scripts/k8s/deploy.sh --show-token` prints the token after deploy.
+
+## Local testing with Kind
+
+If you don't have a cluster, create one locally with [Kind](https://kind.sigs.k8s.io/):
+
+```bash
+./scripts/k8s/create-kind.sh           # auto-detects docker or podman
+./scripts/k8s/create-kind.sh --delete  # tear down
+```
+
+Then deploy as usual with `./scripts/k8s/deploy.sh`.
+
+## Step by step
+
+### 1) Deploy
+
+**Option A** — API key in environment (one step):
+
+```bash
+# Replace with your provider: ANTHROPIC, GEMINI, OPENAI, or OPENROUTER
+export <PROVIDER>_API_KEY="..."
+./scripts/k8s/deploy.sh
+```
+
+The script creates a Kubernetes Secret with the API key and an auto-generated gateway token, then deploys. If the Secret already exists, it preserves the current gateway token and any provider keys not being changed.
+
+**Option B** — create the secret separately:
+
+```bash
+export <PROVIDER>_API_KEY="..."
+./scripts/k8s/deploy.sh --create-secret
+./scripts/k8s/deploy.sh
+```
+
+Use `--show-token` with either command if you want the token printed to stdout for local testing.
+
+### 2) Access the gateway
+
+```bash
+kubectl port-forward svc/nodmix 18789:18789 -n nodmix
+open http://localhost:18789
+```
+
+## What gets deployed
+
+```
+Namespace: nodmix (configurable via NODMIX_NAMESPACE)
+├── Deployment/nodmix        # Single pod, init container + gateway
+├── Service/nodmix           # ClusterIP on port 18789
+├── PersistentVolumeClaim      # 10Gi for agent state and config
+├── ConfigMap/nodmix-config  # nodmix.json + AGENTS.md
+└── Secret/nodmix-secrets    # Gateway token + API keys
+```
+
+## Customization
+
+### Agent instructions
+
+Edit the `AGENTS.md` in `scripts/k8s/manifests/configmap.yaml` and redeploy:
+
+```bash
+./scripts/k8s/deploy.sh
+```
+
+### Gateway config
+
+Edit `nodmix.json` in `scripts/k8s/manifests/configmap.yaml`. See [Gateway configuration](/gateway/configuration) for the full reference.
+
+### Add providers
+
+Re-run with additional keys exported:
+
+```bash
+export ANTHROPIC_API_KEY="..."
+export OPENAI_API_KEY="..."
+./scripts/k8s/deploy.sh --create-secret
+./scripts/k8s/deploy.sh
+```
+
+Existing provider keys stay in the Secret unless you overwrite them.
+
+Or patch the Secret directly:
+
+```bash
+kubectl patch secret nodmix-secrets -n nodmix \
+  -p '{"stringData":{"<PROVIDER>_API_KEY":"..."}}'
+kubectl rollout restart deployment/nodmix -n nodmix
+```
+
+### Custom namespace
+
+```bash
+NODMIX_NAMESPACE=my-namespace ./scripts/k8s/deploy.sh
+```
+
+### Custom image
+
+Edit the `image` field in `scripts/k8s/manifests/deployment.yaml`:
+
+```yaml
+image: ghcr.io/nodmix/nodmix:latest # or pin to a specific version from https://github.com/nodmix/nodmix/releases
+```
+
+### Expose beyond port-forward
+
+The default manifests bind the gateway to loopback inside the pod. That works with `kubectl port-forward`, but it does not work with a Kubernetes `Service` or Ingress path that needs to reach the pod IP.
+
+If you want to expose the gateway through an Ingress or load balancer:
+
+- Change the gateway bind in `scripts/k8s/manifests/configmap.yaml` from `loopback` to a non-loopback bind that matches your deployment model
+- Keep gateway auth enabled and use a proper TLS-terminated entrypoint
+- Configure the Control UI for remote access using the supported web security model (for example HTTPS/Tailscale Serve and explicit allowed origins when needed)
+
+## Re-deploy
+
+```bash
+./scripts/k8s/deploy.sh
+```
+
+This applies all manifests and restarts the pod to pick up any config or secret changes.
+
+## Teardown
+
+```bash
+./scripts/k8s/deploy.sh --delete
+```
+
+This deletes the namespace and all resources in it, including the PVC.
+
+## Architecture notes
+
+- The gateway binds to loopback inside the pod by default, so the included setup is for `kubectl port-forward`
+- No cluster-scoped resources — everything lives in a single namespace
+- Security: `readOnlyRootFilesystem`, `drop: ALL` capabilities, non-root user (UID 1000)
+- The default config keeps the Control UI on the safer local-access path: loopback bind plus `kubectl port-forward` to `http://127.0.0.1:18789`
+- If you move beyond localhost access, use the supported remote model: HTTPS/Tailscale plus the appropriate gateway bind and Control UI origin settings
+- Secrets are generated in a temp directory and applied directly to the cluster — no secret material is written to the repo checkout
+
+## File structure
+
+```
+scripts/k8s/
+├── deploy.sh                   # Creates namespace + secret, deploys via kustomize
+├── create-kind.sh              # Local Kind cluster (auto-detects docker/podman)
+└── manifests/
+    ├── kustomization.yaml      # Kustomize base
+    ├── configmap.yaml          # nodmix.json + AGENTS.md
+    ├── deployment.yaml         # Pod spec with security hardening
+    ├── pvc.yaml                # 10Gi persistent storage
+    └── service.yaml            # ClusterIP on 18789
+```
+
+## Related
+
+- [Docker](/install/docker)
+- [Docker VM runtime](/install/docker-vm-runtime)
+- [Install overview](/install)