Quick Start

One-click install — auto-detect environment, install dependencies, verify everything works

One-Click Environment Setup

Auto-detects your system, installs Python 3.11+, Node.js 20+, creates virtual environment, installs all dependencies, and runs 5 verification checks.

macOS

git clone https://github.com/octopusos/octopus.git
cd octopus
chmod +x scripts/setup-macos.sh
./scripts/setup-macos.sh

Linux

git clone https://github.com/octopusos/octopus.git
cd octopus
chmod +x scripts/setup-linux.sh
sudo ./scripts/setup-linux.sh

Windows

git clone https://github.com/octopusos/octopus.git
cd octopus

# PowerShell (Administrator)
Set-ExecutionPolicy -Scope Process Bypass
.\scripts\setup-windows.ps1

Script Auto-Completes

Python 3.11+ (Homebrew / apt / winget)
Node.js 20 LTS
Virtual environment .venv/ creation and activation
kernel / server / CLI / TUI four-layer pip install
Web frontend npm install
5 automated verifications (Server / CLI / TUI / Web / 3,534 Kernel Tests)

Start Server

source .venv/bin/activate
python3 -m server.main

# Verify
curl http://localhost:8000/health
# {"status": "ok"}

Experience Three Product Forms

# CLI Interactive
source .venv/bin/activate
PYTHONPATH=products python3 -m cli
PYTHONPATH=products python3 -m cli chat

# TUI Terminal UI
PYTHONPATH=products python3 -m tui

# Web Console
cd products/web && npm run dev
# Open http://localhost:5173 in browser

Installation Verification

The setup script automatically runs these 5 verification checks:

Server app creation — FastAPI app initializes correctly
CLI version output — octopus 0.9.0
TUI import check — textual components load successfully
Web build — Vite production build passes
Kernel tests — 3,534 tests all pass