Skip to content
Get packs

Guide · Open source

How to use Octop: install, run and set it up

Updated · written with AI from the project's own documentation and checked against our catalogue data

Octop is an open-source, self-hosted AI assistant that runs as a single process on your own computer. This guide explains what it does, how to get it running, and how to use its dashboard, CLI and chat integrations. By the end you will know where its data lives and which parts are still in beta.

OctopTencentCloud/Octop · ★ 11.5k · MIT

Quick start

  1. 1Check Python. Install Python 3.12 or newer, since the README lists it as the prerequisite for the source install.
  2. 2Clone the repository. Run git clone on the TencentCloud/Octop repository from GitHub.
  3. 3Run first-time setup. Run octop init to complete the setup wizard.
  4. 4Start Octop. Run octop run to start the dashboard, CLI, IM channels and cron in one process.
  5. 5Set up agents and channels. Create your experts and connect the chat channels you use, such as Feishu, Telegram or Discord.

What Octop is and who it suits

Octop serves a web dashboard, a command-line interface, chat integrations such as Feishu, Telegram and Discord, and scheduled tasks from one process. All data is kept under ~/.octop/, with SQLite as the default database and PostgreSQL as an option.

Each user can have their own set of specialized agents. The project is aimed at households and small teams that want to keep conversations and credentials local, and at developers who want to delegate coding tasks to OpenCode or Claude Code through ACP.

  • Good fit: shared household or small-team assistants, and people who want conversations and credentials on their own machine.
  • Poor fit: anyone who needs a mature, fully stable product (the release is tagged 1.0.3b1 and AgentTeams is marked Beta), or who wants a zero-setup hosted service.

Install Octop from source

The README's source install starts by cloning the repository. It lists Python 3.12+ as a prerequisite for that route. Check your Python version before you begin.

The project also offers native Windows, macOS and Linux desktop apps alongside the web dashboard, according to the README. The source does not give separate install steps for those apps, so check the project's releases page for them.

  • Confirm Python 3.12 or newer is installed.
  • Clone the repository from GitHub.
git clone https://github.com/TencentCloud/Octop

Run the first-time setup and start Octop

Octop has a first-run setup wizard, started with octop init. After setup, octop run starts the dashboard, CLI, IM channels and cron together in one process.

The README does not list the default dashboard address or port in the sections provided, so look in the README or docs for that detail.

octop init octop run

Configure the API docs and check your data folder

Interactive API docs are served at /api/docs but are off by default. To turn them on, set "enable_api_docs": true in config.json.

Everything Octop stores lives under ~/.octop/. Back up that folder to keep your conversations, workspaces and settings.

  • Open config.json and set "enable_api_docs": true if you need the API docs.
  • Keep ~/.octop/ backed up, since it holds the control-plane database and workspace data.
"enable_api_docs": true

Use agents, chat channels and ACP

Each user can have multiple experts, and each expert has its own workspace, providers, channels and cron. Expert personas use 16 MBTI templates or a custom system prompt.

For developers, octop acp exposes ACP so an IDE or terminal AI can delegate work to OpenCode or Claude Code with permission gates. AgentTeams, which coordinates several experts on multi-step work, is still Beta.

  • Assign different experts to different household members or team roles.
  • Connect IM channels such as Feishu, DingTalk, Telegram, Discord or WeCom to reach an agent from chat.
  • Use octop acp to hand coding tasks to OpenCode or Claude Code.
octop acp

What people use it for

  • A household shares one admin account and gives each member their own specialized agent.
  • A small team connects Feishu, DingTalk or WeCom so an agent can route tasks into group chats.
  • A developer uses octop acp to delegate coding tasks to OpenCode or Claude Code.
  • A user schedules recurring agent jobs with cron so they run daily.

Frequently asked questions

Is Octop free to use?

Octop is released under the MIT licence, according to the README. You can read the licence file in the repository to confirm the terms for your use.

What do I need to install Octop?

The README lists Python 3.12+ for the source install, and you will need to clone the repository from GitHub. Octop is designed to run on your own machine.

Where does Octop store my data?

All data is kept under ~/.octop/. The control-plane database uses SQLite by default, and PostgreSQL is optional.

Is Octop ready for production use?

The release is tagged 1.0.3b1 and AgentTeams is marked Beta in the README, so it is not a fully stable product yet. Households and small teams comfortable managing a self-hosted process are its target users.

How is Octop different from Open WebUI, AnythingLLM, LibreChat or Jan?

Octop focuses on multi-user, multi-agent use with chat integrations and ACP delegation to coding agents. Open WebUI, AnythingLLM, LibreChat and Jan are comparable projects, but this guide does not compare their features in detail.

Can I use Octop from Telegram or Discord?

Yes. Octop's IM channels include Feishu, DingTalk, QQ, WeChat, Telegram, Discord and WeCom, according to the README.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Octop suits households and small teams who want a shared, self-hosted assistant and are comfortable running and maintaining it. If you need a mature, fully stable product or a zero-setup hosted service, choose a different tool.

Install options & downloads