> ## Documentation Index
> Fetch the complete documentation index at: https://octop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```bash macOS / Linux theme={null}
curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash
```

```powershell Windows (PowerShell) theme={null}
irm https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.ps1 | iex
```

```bat Windows (cmd) theme={null}
curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.bat -o install.bat
install.bat
```

```bash PyPI (existing Python) theme={null}
pip install octop
```

**2. Reload your shell**

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

```bash Zsh theme={null}
source ~/.zshrc
```

```bash Bash theme={null}
source ~/.bashrc
```

> [!NOTE]
>
> 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:

```bash theme={null}
octop --version
```

**3. Initialize Octop**

Bootstrap your local environment:

```bash theme={null}
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:

```bash theme={null}
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.

> [!NOTE]
>
> 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](https://octop.mintlify.site/quickstart-docker.md).

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

```bash theme={null}
octop run --host 0.0.0.0 --port 9000
```

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

```bash theme={null}
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:

```text theme={null}
Management → Models
```

![Model management](https://mintcdn.com/octop/P_aBdthWeK4YndCE/images/ui-models.png?fit=max\&auto=format\&n=P_aBdthWeK4YndCE\&q=85\&s=6a2563aba21600a6c402a6014dac18bb)

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.

> [!TIP]
>
> Prefer the terminal? Use `octop models config` — see [Agent commands](https://octop.mintlify.site/cli/agent-commands.md#octop-models).

**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.

![Chat](https://mintcdn.com/octop/P_aBdthWeK4YndCE/images/ui-chat.png?fit=max\&auto=format\&n=P_aBdthWeK4YndCE\&q=85\&s=0acc0cf987d6a8bd6e9891ea9230dd46)

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

> [!TIP]
>
> For an interactive terminal chat session, see [`octop chats`](https://octop.mintlify.site/cli/agent-commands#octop-chats).

> [!NOTE]
>
> The base installer sets up the core platform. To unlock additional capabilities, re-run the installer with an `--extras` flag:
>
> ```bash theme={null}
> # 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.

> [!TIP]
>
> For production deployments or multi-user setups, use Docker Compose instead of a bare-metal install. See the [Docker Setup guide](https://octop.mintlify.site/quickstart-docker.md). To install on Feiniu NAS, see [FnOS](https://octop.mintlify.site/guides/fnos.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.