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.
: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:
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:
Initialize Octop
Bootstrap your local environment:
This prepares ~/.octop/ (database, secrets, and related files). All data stays on your machine under ~/.octop/.
Start the server
Launch Octop in the foreground:
Once you see the server ready message, open your browser and navigate to:
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.
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. Docker first boot writes admin and a generated (or OCTOP_DEFAULT_PASSWORD) credential to /data/.octop/credential.txt — see Docker Setup.
To bind on all network interfaces or use a different port, pass flags directly:
To run Octop as a persistent background service (systemd, launchd, or Windows Service), use:
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:

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

For an interactive terminal chat session, see 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, 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 and select it from Knowledge bases in the composer.
- To look up meetings, docs, or mail, open Connectors, 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.
The base installer sets up the core platform. To unlock additional capabilities, re-run the installer with an --extras flag:
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 launch a cloud instance with Octop preinstalled, see Use on Tencent Cloud. To install on Feiniu NAS, see FnOS.
Prefer a native desktop app? Download the installer for your platform from the Octop v1.0.3b5 release, for example Octop-desktop-darwin-arm64-1.0.3b5.dmg. For UnionTech UOS and Kylin, see Use on domestic OS. 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.

