Quick Start

Setup

1. Install Bun (if not installed)

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

2. Clone and install dependencies

   cd assistant
   bun install
   cd web && bun install && cd ..

3. Configure the environment

   cp .env.example .env
   # Edit .env with your database password, security keys, etc.
   
   # Or run the interactive setup wizard:
   bun run setup

4. Create the database (if it does not exist)

   docker exec <db-container> psql -U <superuser> -c "CREATE DATABASE assistant;"
   docker exec <db-container> psql -U <superuser> -d assistant \
     -c "CREATE EXTENSION IF NOT EXISTS vector;"
   docker exec <db-container> psql -U <superuser> -d assistant \
     -c 'CREATE EXTENSION IF NOT EXISTS "uuid-ossp";'

5. Start everything

   bin/octi start

The assistant start command will:

• Check that PostgreSQL and Redis are reachable
• Start the backend API server
• Start the Next.js web UI
• Wait for the health check to pass
• Open your browser to the web UI

CLI Management

The assistant CLI provides all the commands you need to manage the application:

assistant start          # Start backend + web UI, open browser
assistant start --dev    # Start in dev mode (hot reload)
assistant stop           # Stop all assistant processes
assistant restart        # Stop + start
assistant status         # Show running state and service health
assistant logs           # Tail backend logs
assistant logs --web     # Tail web UI logs
assistant open           # Open web UI in browser

To make the assistant command available globally:

bun link    # Creates global symlink

Desktop App Setup

Linux

Add Octipus to your application menu:

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

macOS

Create an Automator application or add to Dock. The CLI script auto-detects macOS and uses open for browser launch.

Windows

Use the bin/octi.cmd batch script. Create a shortcut to octi.cmd start on your desktop or pin to taskbar.

Package Scripts

In addition to the CLI, you can use these package scripts directly:

Core

Command	Description
bun run start	Start backend only
bun run dev	Start backend with hot reload
bun run build	Build for production
bun run start:all	Start everything (alias for bin/octi start)
bun run stop:all	Stop everything (alias for bin/octi stop)

Database

Command	Description
bun run db:migrate	Run database migrations
bun run db:generate	Generate migrations from schema changes
bun run db:studio	Open Drizzle Studio (database GUI)

Development

Command	Description
bun test	Run unit tests
bun run test:e2e	Run E2E API test suite
bun run typecheck	Type check without emitting
bun run setup	Interactive setup wizard
bun run backup	Backup database, Redis, config, vault

Next Steps

Once Octipus is running, visit the web UI and:

1. Register an account on the login page
2. Configure a model on the Models page (connect Ollama, add API keys, etc.)
3. Start chatting on the Chat page to test your setup