Quick Start

The fastest path to a running Octipus. The setup wizard generates your secrets, writes a minimal .env, registers your admin account, and wires a first model — so most of the steps below are one command.

Embedded vs. external

Octipus has two storage modes. Embedded (PGlite + in-memory cache) needs zero external services and is perfect for a first run or single-user setup. External (PostgreSQL + pgvector + Valkey) is for multi-user / production. The wizard asks which you want — pick embedded to skip Docker entirely.

Setup

1. Install Bun (and Node.js ≥ 18 for the web UI)

   curl -fsSL https://bun.sh/install | bash

   See Installation for full requirements.

2. Clone the repo and install dependencies

   git clone https://github.com/PatriceA/octipus.git
   cd octipus
   bun install
   cd web && bun install && cd ..

3. Run the setup wizard

   bun run setup

   The wizard:

   • lets you choose embedded or external storage,
   • generates MASTER_KEY, JWT_SECRET, and SESSION_SECRET,
   • writes a minimal .env (it won’t overwrite an existing one),
   • registers your admin account (the first user is the admin),
   • optionally wires a model provider + default model, and installs optional capabilities (Playwright, MCP server, browser extension).

   If you picked external, start PostgreSQL + Valkey first — see Installation → Backing services.

4. Start everything

   octi start             # or: bun run start:all

   This starts the backend API, waits for its health check, then starts the web UI. Database migrations run automatically on first boot — there is no manual migrate step.

5. Open the web UI

   Visit http://localhost:3007 and log in with the admin account you created in the wizard.

What runs

Process	Default port	Notes
Backend API	3005	Bun (API_PORT)
Web UI	3007	Next.js (WEB_PORT)

Stop everything with octi stop (= bun run stop:all).

The octi CLI

octi is the day-to-day entry point — it manages the processes, the setup wizard, the terminal client, and health checks. octi setup puts it on your PATH at install time; until then call it as bin/octi <command>.

octi start [--dev]       # Start backend + web UI (waits for health check)
octi stop                # Stop all Octipus processes
octi restart [--dev]     # Restart everything
octi status              # Show running state
octi logs [--web]        # Tail backend (or web) logs
octi open                # Open the web UI in your browser
octi setup [--remote <url>]   # Run the setup wizard (local, or against a remote backend)
octi tui                 # Launch the terminal chat client
octi edit                # Launch the TUI editor
octi doctor [--json]     # Environment health checks
octi capabilities [install]   # List or install optional tools (browser, MCP, …); alias: octi caps
octi models recommend [--install <id>]   # Recommend local models for this hardware (and pull/bind one)
octi persona [show]      # Print the resolved persona (edit it in the web UI)
octi version             # Print version
octi help                # Full command list

Equivalent package scripts

The common lifecycle commands have bun run equivalents (handy in CI or where octi isn’t on PATH). octi start is literally bun run start:all under the hood.

octi command	Package script
octi start	bun run start:all
octi stop	bun run stop:all
octi setup	bun run setup
— (backend only, hot reload)	bun run dev
— (backend API only)	bun run start

Other package scripts (no octi equivalent)

Command	Description
bun run db:migrate	Run migrations manually (CI/ops — normally automatic on boot)
bun run db:generate	Generate a migration from schema changes (developers)
bun test / bun run test:e2e	Unit / E2E tests
bun run backup	Back up database, Valkey, config, and vault

Desktop launcher (optional)

Linux

cp octipus.desktop ~/.local/share/applications/

macOS

Create an Automator application or add bin/octi start to your Dock. The CLI auto-detects macOS and uses open to launch the browser.

Windows

Use bin/octi.cmd. Create a shortcut to octi.cmd start or pin it to the taskbar.

Next steps

Once you’re logged in:

1. Add a model on the Models page (connect Ollama, or add a provider API key — stored in the encrypted vault, not your .env).
2. Start chatting on the Chat page to confirm routing works.
3. Tune everything else under Settings → Configuration — it’s all stored in the database. See Configuration.

Prefer containers? See Docker Setup for a self-contained stack.