> For AI agents: the complete documentation index is available at /en/llms.txt, the full documentation bundle is available at /en/llms-full.txt.

# Get Started with Octop: Install and Run 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.


### 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
curl -fsSL https://download.octop.cloud/octop/scripts/install.sh | bash
```
```powershell Windows (PowerShell)
irm https://download.octop.cloud/octop/scripts/install.ps1 | iex
```
```bat Windows (cmd)
curl -fsSL https://download.octop.cloud/octop/scripts/install.bat -o install.bat
install.bat
```
```bash Docker (China Mirror)
docker run -d --name octop -p 8088:8088 -v octop-data:/data/.octop -e HOME=/data ghcr.nju.edu.cn/tencentcloud/octop:latest
```
```bash Docker (GitHub Source)
docker run -d --name octop -p 8088:8088 -v octop-data:/data/.octop -e HOME=/data ghcr.io/tencentcloud/octop:latest
```
```bash PyPI (existing Python)
pip install octop
```

`:latest` is the lite image. It does not include a virtual desktop, OCR, or local embedding. Use `ghcr.io/tencentcloud/octop:full` or `:<version>-full` when you need those. The China mirror uses the same tags on `ghcr.nju.edu.cn/tencentcloud/octop`.

### 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
source ~/.zshrc
```
```bash Bash
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
octop --version
```

### Initialize Octop

Bootstrap your local environment:
```bash
octop init
```
This prepares `~/.octop/` (database, secrets, and related files). All data stays on your machine under `~/.octop/`.

### Start the server

Launch Octop in the foreground:
```bash
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 web UI 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. If you forget the password, see [Reset password](/en/guide/guides/reset-password.md). Docker first boot writes `admin` and a generated (or `OCTOP_DEFAULT_PASSWORD`) credential to `/data/.octop/credential.txt` — see [Docker Setup](/en/guide/quickstart-docker.md).
> 

To bind on all network interfaces or use a different port, pass flags directly:
```bash
octop run --host 0.0.0.0 --port 9000
```
To run Octop as a persistent background service (systemd, launchd, or Windows Service), use:
```bash
octop service start
```

### 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
Management → Models
```

![Model management](/images/en/ui-models.png "Model management")

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](/en/cli/agent-commands.md#octop-models).
> 

### Send a first message

Open **Conversation** at `http://127.0.0.1:8088`. Select the default expert `main` created by the setup wizard, and send something you actually want done, for example “Turn the meeting notes below into three action items.”

![Conversation](/images/en/ui-chat.png "Conversation")

> **TIP**
> 
> For an interactive terminal chat session, see [`octop chats`](/en/cli/agent-commands.md#octop-chats).
> 

### Give it a real job

Once a reply comes back, add one capability at a time:
- For a specialist or a different voice, open [Agents](/en/guide/concepts/agents.md), create one from **Discover Experts**, then open **MBTI** and click **Take the test**.
- For answers grounded in your files, upload them to a [knowledge base](/en/guide/concepts/knowledge.md) and select it from **Knowledge bases** in the composer.
- To look up meetings, docs, or mail, open [Connectors](/en/guide/concepts/connectors.md), **Click to connect**, finish authorization, then ask “Check my Tencent Meeting schedule for tomorrow.”
- To reach the expert from Feishu or WeChat, bind a channel in [IM channels](/en/guide/guides/im-channels.md).


> **NOTE**
> 
> The base installer sets up the core platform. To unlock additional capabilities, re-run the installer with an `--extras` flag:
> ```bash
> # Browser automation (Playwright Chromium)
> curl -fsSL https://download.octop.cloud/octop/scripts/install.sh | bash -s -- --extras browser
> 
> # Feishu channel support
> curl -fsSL https://download.octop.cloud/octop/scripts/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](/en/guide/quickstart-docker.md). To launch a cloud instance with Octop preinstalled, see [Use on Tencent Cloud](/en/guide/use-in-tencent-cloud.md). To install on Feiniu NAS, see [FnOS](/en/guide/fnos.md).
> 



> **TIP**
> 
> Prefer a native desktop app? Download the installer for your platform from the [Octop v1.0.3b5 release](https://github.com/TencentCloud/Octop/releases/tag/v1.0.3b5), for example `Octop-desktop-darwin-arm64-1.0.3b5.dmg`. For UnionTech UOS and Kylin, see [Use on domestic OS](/en/guide/domestic-os.md). The desktop client bundles a portable Octop runtime under `~/.octop` and opens the web UI in an Electron shell. After the session expires, the shell renews it with a device credential stored at `~/.octop/desktop-device.json`. The desktop app is optional for server or CLI-only use. Desktop installers include browser automation only. Virtual desktop, OCR, and local embedding stay on the Docker image tag `:full`.
> 

