# Install

**Status:** Stages S0–S2 implemented. S3–S7 pending.

## Stages

| Stage | Where | Outcome | Status |
|-------|--------|---------|--------|
| S0 | Human | Host per [DEPLOYER_HOST.md](DEPLOYER_HOST.md) | ✅ Procedural |
| S0b | Host script | Docker installed if missing | ✅ Implemented |
| S1 | Host script | Repo env, `.env` from `.env.example` | ✅ Implemented |
| S2 | Host script | Main + aux vision config; vision smoke | ✅ Implemented |
| S3–S5 | Host → Compose / `nemohermes` | Stack, sandbox, policy, skills | ⏳ Pending |
| S6 | Host script | Doctor green | ⏳ Pending |
| S7 | Owner + operator connect helpers | Name assistant; connect **their** SaaS/channels | ⏳ Pending |

## Platform commands (normative)

All mutations: `nemohermes` / `openshell` (see [design/research/platform-notes.md](../design/research/platform-notes.md)).

---

## S0: Host baselining

Follow [DEPLOYER_HOST.md](DEPLOYER_HOST.md) to prepare the host:

1. Provision a Linux host (cloud VM, bare metal).
2. Install OS updates.
3. Create a deploy user with sudo access.
4. Install `nemohermes` and `openshell` CLIs.
5. Clone this repository.

## S0b: Docker bootstrap

```bash
./scripts/bootstrap.sh
# or
make bootstrap
```

**Idempotent:** if Docker is already installed and running, the script exits immediately.

**What it checks:**
- `docker info` succeeds → skip install.
- OS family detection (Debian/Ubuntu or RHEL/Fedora).
- Installs Docker, adds user to `docker` group, verifies daemon.

## S1: Repository environment

```bash
./scripts/install/s1-env.sh
# or
make install-s1
```

**What it does:**
1. If `.env` does not exist, copies `.env.example` to `.env`.
2. Validates that all required keys are present and non-empty:
   - `LUMINA_SANDBOX` — sandbox name (default: `hermes`)
   - `LUMINA_INFERENCE_BASE_URL` — inference endpoint URL
   - `LUMINA_INFERENCE_MODEL` — model identifier
   - `LUMINA_VISION_MODEL` — vision model identifier
3. Fails with clear messages if keys are missing or empty.

**Edit `.env`** with your actual values before running S2. See `.env.example` for all keys and descriptions.

**Never commit `.env` with real secrets.** It is in `.gitignore`.

## S2: Model + vision configuration

```bash
./scripts/install/s2-models.sh
# or
make install-s2
```

**What it does:**
1. Loads `.env` and validates required keys.
2. Checks that `nemohermes` and `openshell` CLIs are available.
3. Verifies the inference endpoint is reachable (`/v1/models`).
4. If the OpenShell gateway is connected, configures the inference route via `openshell inference set`.
5. Runs the **vision smoke test**:
   - Probes `/v1/models` for `multimodal` capability tag.
   - Falls back to a minimal chat completion if capability tags are not exposed.
6. **Fails loudly** (non-zero exit) if vision capability cannot be confirmed.

**If the gateway is not yet connected:** the script validates the endpoint and skips the `openshell` write. S3+ will handle full gateway configuration.

## Run all stages (S0b–S2)

```bash
./scripts/install.sh
# or
make install
# or
make install-s0-s2
```

## After install (S0–S2)

- Verify `.env` values are correct for your environment.
- Continue with S3+ when implemented (compose stack, sandbox creation, policy, skills).
- See [SETUP_UX.md](SETUP_UX.md) for owner-facing setup after full install.
- See [design/scenarios.md](../design/scenarios.md) (S1–S5) for operational scenarios.

## UAT host notes

This repository was tested on a live host with:
- `nemohermes` v0.0.93, `openshell` v0.0.85
- Sandbox: `hermes` (default)
- Gateway: `nemoclaw` at `https://127.0.0.1:8080`
- Inference: OpenAI-compatible endpoint with multimodal model
- Docker: present and running

Scripts are idempotent on this configuration.