Quick Start

1. Check prerequisites

Install Node.js 24.19.0 or newer (including npm) and Git. Linux/macOS/WSL also need Bash and curl. Check node --version before installing. Older Node versions can fail during setup; reopen your terminal after upgrading.

Have a hosted model API key ready, or run Ollama and download a model first. Embedded storage needs no Docker or separate database. CLI-provider users must separately install/authenticate their vendor CLI and add its model in Models; subscription eligibility and charges depend on the provider.

2. Install and configure

Linux / macOS / WSL:

curl -fsSL https://raw.githubusercontent.com/PatriceA/octipus/main/scripts/install.sh | bash

Windows PowerShell:

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/PatriceA/octipus/main/scripts/install.ps1)))

The installer installs locked dependencies, builds the backend/web/MCP packages, audits all three, and runs terminal setup. Choose embedded storage to start simply, create your administrator account, and configure a provider/default model. Add the printed CLI directory to PATH if needed. Audits report findings without automatically changing dependency versions.

3. Start and log in

octi start web

Open http://localhost:3007 and log in with your setup account. The API defaults to port 3005. Setup’s temporary backend stops when the wizard finishes; octi start alone starts only the backend. There is no separate browser onboarding page.

Send a first chat message to verify your model connection. Configuration does not itself prove the provider credentials, quota, or downloaded model are usable.

4. Manage the instance

octi status
octi doctor
octi logs
octi tui
octi stop

octi tui connects to the running backend. For Docker, run bash scripts/install-docker.sh from a checkout and open port 3017 instead. Host Node/npm is not needed for that path.

See Installation for Docker prerequisites, manual builds, headless setup, upgrades, audits, custom install paths, and optional desktop requirements.