Skip to content

setup.md

Latest commit

 

History

History
102 lines (67 loc) · 7.87 KB

setup.md

File metadata and controls

102 lines (67 loc) · 7.87 KB
Raw

Setup guide

This document covers what npm run setup actually does, per-OS notes, and troubleshooting. For the one-line quickstart, see the root README.md.

Don't have the repo yet? Use the NPX bootstrap

npx --yes git+ssh://[email protected]/amplimind/AImplimind.git

This clones the repo, runs npm install, then runs the same npm run setup wizard described below — it doesn't reimplement any of it. See the README's "Internal one-command bootstrap" section for the full option list (--target, --repo, --branch, --mode, --skip-setup, --start, --yes, --check-only) and the SSH/private-repo prerequisites.

The rest of this document assumes you already have the repo locally (either via the bootstrap above or a manual git clone) and are running npm run setup directly.

What the wizard checks and does

In order:

  1. Base tools — Node.js version, npm, Git. Informational only; if you got far enough to run npm run setup, Node is already there.
  2. Project dependencies — checks node_modules. If missing, asks to run npm install (auto-confirmed under --yes).
  3. Local app data — ensures data/, data/local-ai-workbench/, data/local-ai-workbench/opencode/, and logs/ exist. Never deletes or overwrites existing files; re-running is a no-op once they exist.
  4. Ollama — checks the CLI and whether the API (http://localhost:11434) is reachable. If the CLI is missing, shows the OS-specific install command and asks before running it. If the API isn't reachable, attempts to start it and polls for up to 15 seconds.
  5. Recommended models — offers starter models based on the setup mode (see below). Always asks before pulling, and shows the approximate download size first.
  6. OpenCode — checks the CLI. In basic mode this is just a status line (OpenCode is optional there). In coding/full mode, offers to install it via npm install -g opencode-ai and asks before running it.
  7. Summary — prints the exact commands to start the app and where the log file is.

Nothing external runs without you seeing the exact command first and confirming it. --yes only auto-confirms safe, project-local, fully reversible steps (creating folders, npm install) — it never silently installs Ollama, OpenCode, or pulls a model.

Setup modes

Mode Project deps + app data Ollama Starter models offered OpenCode
basic (default) yes check/install/start qwen3:8b (chat) status only
coding yes check/install/start + qwen2.5-coder:7b check/install offered
full yes check/install/start + qwen2.5-coder:14b, nomic-embed-text check/install offered
check-only no installs — report only report only not offered report only

Already-installed models are detected by base name (e.g. qwen3:8b matches an existing qwen3:latest) and skipped.

Per-OS notes

Windows (primary target)

  • Ollama: prefers winget install --id Ollama.Ollama -e; falls back to a manual download link if winget isn't available.
  • The wizard does not assume admin rights and does not change your PowerShell execution policy. If running setup.ps1 directly is blocked by execution policy, either run npm run setup instead (goes through Node, not PowerShell scripting) or run PowerShell with -ExecutionPolicy Bypass for that one invocation: 
    powershell -ExecutionPolicy Bypass -File .\setup.ps1
  • OpenCode: installed via npm install -g opencode-ai, which drops opencode.exe under %APPDATA%\npm\node_modules\opencode-ai\bin.

macOS

  • Ollama: prefers brew install ollama if Homebrew is set up; otherwise shows the official .dmg/app download link as a manual fallback.
  • OpenCode: same npm install -g opencode-ai path as everywhere else.

Linux

  • Ollama: uses the official install script (curl -fsSL https://ollama.com/install.sh | sh) — only after you confirm it, per the no-silent-remote-scripts rule. If you'd rather inspect it first, decline the prompt and run it yourself, or check systemctl status ollama if you already have it as a service.

Check-only mode

npm run setup -- --check-only

Prints a status report (Node/npm/Git, project deps, app data, Ollama CLI+API, OpenCode) and exits. Installs nothing, prompts for nothing, modifies nothing. Use this to see what's missing before deciding which mode to run.

Troubleshooting Ollama

  • "Ollama API unreachable" after install: the installer may need a moment, or the Ollama app/service may not have started automatically. Start it manually (open the Ollama app on Windows/macOS, or ollama serve from a terminal on Linux), then re-run npm run setup -- --check-only to confirm.
  • Port 11434 already in use by something else: stop whatever's bound to that port, or note that Ollama itself may already be running — check npm run setup -- --check-only.
  • Model pull is slow/stuck: model downloads can be several GB; this is expected on a slow connection. You can re-run npm run setup later — already-installed models are skipped automatically.

Troubleshooting OpenCode

  • "OpenCode CLI not found" after running the install command: the npm global bin directory may not be on your PATH yet in the current shell. Open a new terminal and re-run npm run setup -- --check-only.
  • OpenCode launches but a coding model gives poor results: pick a model tagged "coding" in the Models/OpenCode page in the app, or re-run setup with --mode coding to pull qwen2.5-coder:7b.
  • See the in-app OpenCode page for install status, project picker, and launch — it uses the same detection logic as this wizard.

Where local data is stored

Everything lives under the repo, nothing leaves your machine:

  • data/local-ai-workbench.sqlite — chat sessions and messages
  • data/local-ai-workbench/opencode/opencode.json — app-managed OpenCode config (only used when you pick "app-managed config" mode when launching OpenCode; "project-local config" writes opencode.json into the target project instead)
  • logs/setup.log — setup wizard log: timestamps, OS, mode, checks, commands run, success/failure. No secrets, no chat content, no source code are ever logged.

Privacy / local-only note

Inference runs through your local Ollama instance. Chat sessions, models, and OpenCode configuration stay on your machine. The setup wizard's only network activity is the install commands and model pulls you explicitly confirm, plus checking http://localhost:11434 (your own machine).

Later: packaging and distribution (not implemented yet)

This task is scoped to one-command developer setup. Planning notes for a later, fuller product packaging effort:

  • Desktop wrapper: Tauri is the leading candidate over Electron (smaller binary, no bundled Chromium-per-app overhead) for wrapping the existing Vite frontend + spawning/managing the NestJS API as a sidecar process.
  • Windows installer: an MSI/NSIS installer that bundles Node (or a packaged binary via pkg/Tauri's bundler) so end users don't need Node preinstalled — separate from this developer-facing npm run setup flow.
  • Company-internal distribution: this setup wizard is structured (installers.mjs returns plan objects with a command, not just runs things) so a company-internal mirror or proxy for the Ollama/OpenCode install commands and model registry can be swapped in later without touching the wizard's flow logic.
  • Signed binaries: relevant once there's an actual installer/binary to sign; not applicable to the current Node-script-based setup.
  • Offline installer: would need a pre-downloaded Ollama installer + pre-pulled model blobs bundled together; out of scope for now since the default flow assumes internet access for the initial install.

None of this changes the current one-command developer setup — it's just where the seams already are for later work.