@symerian/symi 3.0.21 → 3.0.22

package/docs/install/hetzner.md

@@ -1,347 +0,0 @@
----
-summary: "Run Symi Gateway 24/7 on a cheap Hetzner VPS (Docker) with durable state and baked-in binaries"
-read_when:
-  - You want Symi running 24/7 on a cloud VPS (not your laptop)
-  - You want a production-grade, always-on Gateway on your own VPS
-  - You want full control over persistence, binaries, and restart behavior
-  - You are running Symi in Docker on Hetzner or a similar provider
-title: "Hetzner"
----
-
-# Symi on Hetzner (Docker, Production VPS Guide)
-
-## Goal
-
-Run a persistent Symi Gateway on a Hetzner VPS using Docker, with durable state, baked-in binaries, and safe restart behavior.
-
-If you want “Symi 24/7 for ~$5”, this is the simplest reliable setup.
-Hetzner pricing changes; pick the smallest Debian/Ubuntu VPS and scale up if you hit OOMs.
-
-## What are we doing (simple terms)?
-
-- Rent a small Linux server (Hetzner VPS)
-- Install Docker (isolated app runtime)
-- Start the Symi Gateway in Docker
-- Persist `~/.symi` + `~/.symi/workspace` on the host (survives restarts/rebuilds)
-- Access the Control UI from your laptop via an SSH tunnel
-
-The Gateway can be accessed via:
-
-- SSH port forwarding from your laptop
-- Direct port exposure if you manage firewalling and tokens yourself
-
-This guide assumes Ubuntu or Debian on Hetzner.  
-If you are on another Linux VPS, map packages accordingly.
-For the generic Docker flow, see [Docker](/install/docker).
-
----
-
-## Quick path (experienced operators)
-
-1. Provision Hetzner VPS
-2. Install Docker
-3. Clone Symi repository
-4. Create persistent host directories
-5. Configure `.env` and `docker-compose.yml`
-6. Bake required binaries into the image
-7. `docker compose up -d`
-8. Verify persistence and Gateway access
-
----
-
-## What you need
-
-- Hetzner VPS with root access
-- SSH access from your laptop
-- Basic comfort with SSH + copy/paste
-- ~20 minutes
-- Docker and Docker Compose
-- Model auth credentials
-- Optional provider credentials
-  - WhatsApp QR
-  - Telegram bot token
-  - Gmail OAuth
-
----
-
-## 1) Provision the VPS
-
-Create an Ubuntu or Debian VPS in Hetzner.
-
-Connect as root:
-
-```bash
-ssh root@YOUR_VPS_IP
-```
-
-This guide assumes the VPS is stateful.
-Do not treat it as disposable infrastructure.
-
----
-
-## 2) Install Docker (on the VPS)
-
-```bash
-apt-get update
-apt-get install -y git curl ca-certificates
-curl -fsSL https://get.docker.com | sh
-```
-
-Verify:
-
-```bash
-docker --version
-docker compose version
-```
-
----
-
-## 3) Clone the Symi repository
-
-```bash
-git clone https://github.com/symi/symi.git
-cd symi
-```
-
-This guide assumes you will build a custom image to guarantee binary persistence.
-
----
-
-## 4) Create persistent host directories
-
-Docker containers are ephemeral.
-All long-lived state must live on the host.
-
-```bash
-mkdir -p /root/.symi/workspace
-
-# Set ownership to the container user (uid 1000):
-chown -R 1000:1000 /root/.symi
-```
-
----
-
-## 5) Configure environment variables
-
-Create `.env` in the repository root.
-
-```bash
-SYMI_IMAGE=symi:latest
-SYMI_GATEWAY_TOKEN=change-me-now
-SYMI_GATEWAY_BIND=lan
-SYMI_GATEWAY_PORT=18789
-
-SYMI_CONFIG_DIR=/root/.symi
-SYMI_WORKSPACE_DIR=/root/.symi/workspace
-
-GOG_KEYRING_PASSWORD=change-me-now
-XDG_CONFIG_HOME=/home/node/.symi
-```
-
-Generate strong secrets:
-
-```bash
-openssl rand -hex 32
-```
-
-**Do not commit this file.**
-
----
-
-## 6) Docker Compose configuration
-
-Create or update `docker-compose.yml`.
-
-```yaml
-services:
-  symi-gateway:
-    image: ${SYMI_IMAGE}
-    build: .
-    restart: unless-stopped
-    env_file:
-      - .env
-    environment:
-      - HOME=/home/node
-      - NODE_ENV=production
-      - TERM=xterm-256color
-      - SYMI_GATEWAY_BIND=${SYMI_GATEWAY_BIND}
-      - SYMI_GATEWAY_PORT=${SYMI_GATEWAY_PORT}
-      - SYMI_GATEWAY_TOKEN=${SYMI_GATEWAY_TOKEN}
-      - GOG_KEYRING_PASSWORD=${GOG_KEYRING_PASSWORD}
-      - XDG_CONFIG_HOME=${XDG_CONFIG_HOME}
-      - PATH=/home/linuxbrew/.linuxbrew/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
-    volumes:
-      - ${SYMI_CONFIG_DIR}:/home/node/.symi
-      - ${SYMI_WORKSPACE_DIR}:/home/node/.symi/workspace
-    ports:
-      # Recommended: keep the Gateway loopback-only on the VPS; access via SSH tunnel.
-      # To expose it publicly, remove the `127.0.0.1:` prefix and firewall accordingly.
-      - "127.0.0.1:${SYMI_GATEWAY_PORT}:18789"
-    command:
-      [
-        "node",
-        "dist/index.js",
-        "gateway",
-        "--bind",
-        "${SYMI_GATEWAY_BIND}",
-        "--port",
-        "${SYMI_GATEWAY_PORT}",
-        "--allow-unconfigured",
-      ]
-```
-
-`--allow-unconfigured` is only for bootstrap convenience, it is not a replacement for a proper gateway configuration. Still set auth (`gateway.auth.token` or password) and use safe bind settings for your deployment.
-
----
-
-## 7) Bake required binaries into the image (critical)
-
-Installing binaries inside a running container is a trap.
-Anything installed at runtime will be lost on restart.
-
-All external binaries required by skills must be installed at image build time.
-
-The examples below show three common binaries only:
-
-- `gog` for Gmail access
-- `goplaces` for Google Places
-- `wacli` for WhatsApp
-
-These are examples, not a complete list.
-You may install as many binaries as needed using the same pattern.
-
-If you add new skills later that depend on additional binaries, you must:
-
-1. Update the Dockerfile
-2. Rebuild the image
-3. Restart the containers
-
-**Example Dockerfile**
-
-```dockerfile
-FROM node:22-bookworm
-
-RUN apt-get update && apt-get install -y socat && rm -rf /var/lib/apt/lists/*
-
-# Example binary 1: Gmail CLI
-RUN curl -L https://github.com/steipete/gog/releases/latest/download/gog_Linux_x86_64.tar.gz \
-  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/gog
-
-# Example binary 2: Google Places CLI
-RUN curl -L https://github.com/steipete/goplaces/releases/latest/download/goplaces_Linux_x86_64.tar.gz \
-  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/goplaces
-
-# Example binary 3: WhatsApp CLI
-RUN curl -L https://github.com/steipete/wacli/releases/latest/download/wacli_Linux_x86_64.tar.gz \
-  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/wacli
-
-# Add more binaries below using the same pattern
-
-WORKDIR /app
-COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
-COPY scripts ./scripts
-
-RUN corepack enable
-RUN pnpm install --frozen-lockfile
-
-COPY . .
-RUN pnpm build
-RUN pnpm ui:install
-RUN pnpm ui:build
-
-ENV NODE_ENV=production
-
-CMD ["node","dist/index.js"]
-```
-
----
-
-## 8) Build and launch
-
-```bash
-docker compose build
-docker compose up -d symi-gateway
-```
-
-Verify binaries:
-
-```bash
-docker compose exec symi-gateway which gog
-docker compose exec symi-gateway which goplaces
-docker compose exec symi-gateway which wacli
-```
-
-Expected output:
-
-```
-/usr/local/bin/gog
-/usr/local/bin/goplaces
-/usr/local/bin/wacli
-```
-
----
-
-## 9) Verify Gateway
-
-```bash
-docker compose logs -f symi-gateway
-```
-
-Success:
-
-```
-[gateway] listening on ws://0.0.0.0:18789
-```
-
-From your laptop:
-
-```bash
-ssh -N -L 18789:127.0.0.1:18789 root@YOUR_VPS_IP
-```
-
-Open:
-
-`http://127.0.0.1:18789/`
-
-Paste your gateway token.
-
----
-
-## What persists where (source of truth)
-
-Symi runs in Docker, but Docker is not the source of truth.
-All long-lived state must survive restarts, rebuilds, and reboots.
-
-| Component           | Location                      | Persistence mechanism  | Notes                           |
-| ------------------- | ----------------------------- | ---------------------- | ------------------------------- |
-| Gateway config      | `/home/node/.symi/`           | Host volume mount      | Includes `symi.json`, tokens    |
-| Model auth profiles | `/home/node/.symi/`           | Host volume mount      | OAuth tokens, API keys          |
-| Skill configs       | `/home/node/.symi/skills/`    | Host volume mount      | Skill-level state               |
-| Agent workspace     | `/home/node/.symi/workspace/` | Host volume mount      | Code and agent artifacts        |
-| WhatsApp session    | `/home/node/.symi/`           | Host volume mount      | Preserves QR login              |
-| Gmail keyring       | `/home/node/.symi/`           | Host volume + password | Requires `GOG_KEYRING_PASSWORD` |
-| External binaries   | `/usr/local/bin/`             | Docker image           | Must be baked at build time     |
-| Node runtime        | Container filesystem          | Docker image           | Rebuilt every image build       |
-| OS packages         | Container filesystem          | Docker image           | Do not install at runtime       |
-| Docker container    | Ephemeral                     | Restartable            | Safe to destroy                 |
-
----
-
-## Infrastructure as Code (Terraform)
-
-For teams preferring infrastructure-as-code workflows, a community-maintained Terraform setup provides:
-
-- Modular Terraform configuration with remote state management
-- Automated provisioning via cloud-init
-- Deployment scripts (bootstrap, deploy, backup/restore)
-- Security hardening (firewall, UFW, SSH-only access)
-- SSH tunnel configuration for gateway access
-
-**Repositories:**
-
-- Infrastructure: [symi-terraform-hetzner](https://github.com/andreesg/symi-terraform-hetzner)
-- Docker config: [symi-docker-config](https://github.com/andreesg/symi-docker-config)
-
-This approach complements the Docker setup above with reproducible deployments, version-controlled infrastructure, and automated disaster recovery.
-
-> **Note:** Community-maintained. For issues or contributions, see the repository links above.

package/docs/install/index.md

@@ -1,218 +0,0 @@
----
-summary: "Install Symi — installer script, npm/pnpm, from source, Docker, and more"
-read_when:
-  - You need an install method other than the Getting Started quickstart
-  - You want to deploy to a cloud platform
-  - You need to update, migrate, or uninstall
-title: "Install"
----
-
-# Install
-
-Already followed [Getting Started](/start/getting-started)? You're all set — this page is for alternative install methods, platform-specific instructions, and maintenance.
-
-## System requirements
-
-- **[Node 22+](/install/node)** (the [installer script](#install-methods) will install it if missing)
-- macOS, Linux, or Windows
-- `pnpm` only if you build from source
-
-<Note>
-On Windows, we strongly recommend running Symi under [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install).
-</Note>
-
-## Install methods
-
-<Tip>
-The **installer script** is the recommended way to install Symi. It handles Node detection, installation, and onboarding in one step.
-</Tip>
-
-<Warning>
-For VPS/cloud hosts, avoid third-party "1-click" marketplace images when possible. Prefer a clean base OS image (for example Ubuntu LTS), then install Symi yourself with the installer script.
-</Warning>
-
-<AccordionGroup>
-  <Accordion title="Installer script" icon="rocket" defaultOpen>
-    Downloads the CLI, installs it globally via npm, and launches the onboarding wizard.
-
-    <Tabs>
-      <Tab title="macOS / Linux / WSL2">
-        ```bash
-        curl -fsSL https://jaysteelmind.github.io/getsymi/install.sh | bash
-        ```
-      </Tab>
-      <Tab title="Windows (PowerShell)">
-        ```powershell
-        iwr -useb https://jaysteelmind.github.io/getsymi/install.ps1 | iex
-        ```
-      </Tab>
-    </Tabs>
-
-    That's it — the script handles Node detection, installation, and onboarding.
-
-    To skip onboarding and just install the binary:
-
-    <Tabs>
-      <Tab title="macOS / Linux / WSL2">
-        ```bash
-        curl -fsSL https://jaysteelmind.github.io/getsymi/install.sh | bash -s -- --no-onboard
-        ```
-      </Tab>
-      <Tab title="Windows (PowerShell)">
-        ```powershell
-        & ([scriptblock]::Create((iwr -useb https://jaysteelmind.github.io/getsymi/install.ps1))) -NoOnboard
-        ```
-      </Tab>
-    </Tabs>
-
-    For all flags, env vars, and CI/automation options, see [Installer internals](/install/installer).
-
-  </Accordion>
-
-  <Accordion title="npm / pnpm" icon="package">
-    If you already have Node 22+ and prefer to manage the install yourself:
-
-    <Tabs>
-      <Tab title="npm">
-        ```bash
-        npm install -g @symerian/symi@latest
-        symi onboard --install-daemon
-        ```
-
-        <Accordion title="sharp build errors?">
-          If you have libvips installed globally (common on macOS via Homebrew) and `sharp` fails, force prebuilt binaries:
-
-          ```bash
-          SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g @symerian/symi@latest
-          ```
-
-          If you see `sharp: Please add node-gyp to your dependencies`, either install build tooling (macOS: Xcode CLT + `npm install -g node-gyp`) or use the env var above.
-        </Accordion>
-      </Tab>
-      <Tab title="pnpm">
-        ```bash
-        pnpm add -g symi@latest
-        pnpm approve-builds -g        # approve symi, node-llama-cpp, sharp, etc.
-        symi onboard --install-daemon
-        ```
-
-        <Note>
-        pnpm requires explicit approval for packages with build scripts. After the first install shows the "Ignored build scripts" warning, run `pnpm approve-builds -g` and select the listed packages.
-        </Note>
-      </Tab>
-    </Tabs>
-
-  </Accordion>
-
-  <Accordion title="From source" icon="github">
-    For contributors or anyone who wants to run from a local checkout.
-
-    <Steps>
-      <Step title="Clone and build">
-        Clone the [Symi repo](https://github.com/symi/symi) and build:
-
-        ```bash
-        git clone https://github.com/symi/symi.git
-        cd symi
-        pnpm install
-        pnpm ui:build
-        pnpm build
-        ```
-      </Step>
-      <Step title="Link the CLI">
-        Make the `symi` command available globally:
-
-        ```bash
-        pnpm link --global
-        ```
-
-        Alternatively, skip the link and run commands via `pnpm symi ...` from inside the repo.
-      </Step>
-      <Step title="Run onboarding">
-        ```bash
-        symi onboard --install-daemon
-        ```
-      </Step>
-    </Steps>
-
-    For deeper development workflows, see [Setup](/start/setup).
-
-  </Accordion>
-</AccordionGroup>
-
-## Other install methods
-
-<CardGroup cols={2}>
-  <Card title="Docker" href="/install/docker" icon="container">
-    Containerized or headless deployments.
-  </Card>
-  <Card title="Podman" href="/install/podman" icon="container">
-    Rootless container: run `setup-podman.sh` once, then the launch script.
-  </Card>
-  <Card title="Nix" href="/install/nix" icon="snowflake">
-    Declarative install via Nix.
-  </Card>
-  <Card title="Ansible" href="/install/ansible" icon="server">
-    Automated fleet provisioning.
-  </Card>
-  <Card title="Bun" href="/install/bun" icon="zap">
-    CLI-only usage via the Bun runtime.
-  </Card>
-</CardGroup>
-
-## After install
-
-Verify everything is working:
-
-```bash
-symi doctor         # check for config issues
-symi status         # gateway status
-symi dashboard      # open the browser UI
-```
-
-If you need custom runtime paths, use:
-
-- `SYMI_HOME` for home-directory based internal paths
-- `SYMI_STATE_DIR` for mutable state location
-- `SYMI_CONFIG_PATH` for config file location
-
-See [Environment vars](/help/environment) for precedence and full details.
-
-## Troubleshooting: `symi` not found
-
-<Accordion title="PATH diagnosis and fix">
-  Quick diagnosis:
-
-```bash
-node -v
-npm -v
-npm prefix -g
-echo "$PATH"
-```
-
-If `$(npm prefix -g)/bin` (macOS/Linux) or `$(npm prefix -g)` (Windows) is **not** in your `$PATH`, your shell can't find global npm binaries (including `symi`).
-
-Fix — add it to your shell startup file (`~/.zshrc` or `~/.bashrc`):
-
-```bash
-export PATH="$(npm prefix -g)/bin:$PATH"
-```
-
-On Windows, add the output of `npm prefix -g` to your PATH.
-
-Then open a new terminal (or `rehash` in zsh / `hash -r` in bash).
-</Accordion>
-
-## Update / uninstall
-
-<CardGroup cols={3}>
-  <Card title="Updating" href="/install/updating" icon="refresh-cw">
-    Keep Symi up to date.
-  </Card>
-  <Card title="Migrating" href="/install/migrating" icon="arrow-right">
-    Move to a new machine.
-  </Card>
-  <Card title="Uninstall" href="/install/uninstall" icon="trash-2">
-    Remove Symi completely.
-  </Card>
-</CardGroup>