Get Started with Octop: Install and Run in Minutes

Install Octop on macOS, Linux, or Windows, run octop init, complete the first-run setup wizard, then start chatting in minutes.

Octop is a self-hosted, multi-user AI assistant that runs entirely on your own machine. In this guide, you will install the octop CLI, run octop init, start the server, complete the first-run setup wizard, and send your first message — all in under five minutes.

1. Install Octop

   Choose the installer that matches your platform. Every method provisions an isolated environment at ~/.octop/venv and adds octop to your PATH via ~/.octop/bin — no system Python is required.

   macOS / Linux

   curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash
   
2. Reload your shell

   Open a new terminal, or reload your current shell session so that ~/.octop/bin is picked up from your PATH:

   Zsh

   source ~/.zshrc
   

   On Windows the installer updates your user PATH automatically — close and reopen your terminal to apply the change. No shell reload command is needed.

   Confirm the installation succeeded:

   octop --version
   
3. Initialize Octop

   Bootstrap your local environment:

   octop init
   

   This prepares ~/.octop/ (database, secrets, and related files). All data stays on your machine under ~/.octop/.

4. Start the server

   Launch Octop in the foreground:

   octop run
   

   Once you see the server ready message, open your browser and navigate to:

   http://127.0.0.1:8088
   

   On first launch the dashboard opens the setup wizard. Open ~/octop-login.txt in your user home directory, copy the one-time setup password into the wizard, then choose your own admin username and password.

   The file is ~/octop-login.txt in the user home directory, not under ~/.octop/. After setup completes, keep the file if you still need the one-time password — Octop no longer deletes it. Sign in with the username and password you created. Docker first boot uses a different pair (admin / Octop123) — see Docker Setup.

   To bind on all network interfaces or use a different port, pass flags directly:

   octop run --host 0.0.0.0 --port 9000
   

   To run Octop as a persistent background service (systemd, launchd, or Windows Service), use:

   octop service start
   
5. Configure a model provider

   Octop ships built-in presets for Tencent Cloud, OpenAI, Anthropic, DeepSeek, Ollama, and many more. Add your first provider from the web UI:

   Management → Models
   

   

   Pick a built-in preset, enter your API key, and enable it. Its models join the available model pool that every agent under your account can use.

   Prefer the terminal? Use octop models config — see Agent commands.

6. Start chatting

   Open Chat in the web UI at http://127.0.0.1:8088. Select your agent (the setup wizard creates a default main agent) and send your first message.

   

   Your agent now has access to all the skills, connectors, and tools you configure going forward.

   For an interactive terminal chat session, see octop chats.

The base installer sets up the core platform. To unlock additional capabilities, re-run the installer with an --extras flag:

# Browser automation (Playwright Chromium)
curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash -s -- --extras browser

# Feishu channel support
curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash -s -- --extras channels-feishu

Browser automation enables headless Chromium sessions for web tasks and screenshots. The Feishu extra adds a channel bridge so your agents can receive and reply to Feishu messages.

For production deployments or multi-user setups, use Docker Compose instead of a bare-metal install. See the Docker Setup guide. To install on Feiniu NAS, see FnOS.