How to Install Tencent's Octop AI Assistant Locally
A practical walkthrough for installing Octop, Tencent Cloud's open-source AI assistant, and setting up experts, knowledge bases, and coding agents.
What is Octop and why does it matter?
Octop is an open-source AI assistant from Tencent Cloud’s GitHub organization, built to run on your own machine rather than through a hosted service. It combines specialist agents (called “experts”), document search through knowledge bases, scheduled tasks, and connections to external coding tools like OpenCode and Claude Code. Octop is free and MIT-licensed, but you still have to supply and pay for your own model access, whether that’s a cloud API or a local model run through something like Ollama.
The appeal isn’t any single feature. It’s having experts, documents, team workflows, and coding tool integration in one dashboard, so you’re not rebuilding a setup every time a task shifts from answering a question to reviewing a draft to editing a file in a repo.
TL;DR
- Octop is self-hosted and open source under the MIT license, but it doesn’t include free model access. You connect your own cloud API key or a local model and pay for usage accordingly.
- Self-hosting doesn’t mean fully private. If you connect a cloud model provider, your documents and prompts still leave your machine and go to that provider.
- Experts are Octop’s agent unit. Each one gets its own workspace, model choice, and prompt file, so you can assign a writing role to one expert and a review role to another.
- Knowledge bases use embeddings to search your documents, and you can run embedding generation locally or send it to an online service, which is a separate cost and privacy decision from your chat model.
- Teams let multiple experts collaborate under a coordinator model, but the feature is still in beta and has quirks, like stopped jobs not always halting work already dispatched to members.
- Coding agent integration runs through ACP (agent client protocol), letting an expert hand off tasks to a tool like OpenCode to read and write actual project files.
- Scheduled tasks can send fixed reminders or trigger fresh agent work, but the Octop process needs to stay running, and background use needs the time zone configured correctly.
Built like a system. Not vibe-coded.
Remy manages the project — every layer architected, not stitched together at the last second.
How do you install Octop?
Octop ships with a terminal installer and a web dashboard, plus desktop downloads for Windows, Mac, and Linux listed on the project’s GitHub releases page. The terminal route works like this:
- Open the Octop GitHub repository and find the installation instructions.
- On Mac or Linux, run the shell installer command. On Windows, use the equivalent PowerShell command.
- The installer sets up the Python environment automatically, so there’s no manual Python configuration.
- Open a new terminal once installation finishes so the
octopcommand is recognized. - Start the app with
octop run. You can append a time zone flag so scheduled tasks behave correctly (the project defaults to Asia/Shanghai, so non-Shanghai users should set their own). - With the terminal still running, open the local dashboard address at port 8088 on your machine.
On first launch, Octop asks for a temporary setup password that’s printed in the terminal. That gets you into account creation, where you pick a database (SQLite is the simple option for a single-machine setup) and set an admin username and password with at least eight characters, including letters and numbers.
How do you connect a model to Octop?
After account setup, Octop asks you to configure a model provider. You pick a provider you already have API access to, enter the key, and confirm the API address. If you’re using a non-standard or self-hosted service, you select the matching API type and supply the base URL yourself. You can also connect a local model running through Ollama instead of a cloud provider.
It’s worth testing the connection with a single chat model before adding anything else. Installing Octop doesn’t grant you any model quota. It’s purely the orchestration layer. Whatever model you choose for experts that will search documents or delegate tasks needs to handle tool calls reliably, since those actions depend on the model correctly invoking search and delegation functions rather than just generating text.
What are “experts” and how do you build one?
Octop’s term for an individual agent is an “expert.” Each expert has its own workspace, its own model assignment, and a prompt file (agents.md) where you define its role. You could set up one expert as a writer and another as a reviewer, each running a different model if you want.
To create one, you go to the experts page, choose “new expert,” name it, assign a model, and edit the prompt file with specific instructions, for example, telling it to write clear summaries from supplied information and to flag when something isn’t documented. Templates and personality settings exist too, but a clear, specific job description in the prompt file does most of the work.
Everyone else built a construction worker.
We built the contractor.
One file at a time.
UI, API, database, deploy.
Once an expert is running, it’s worth testing it with something small and checkable, like a short internal document, before connecting it to anything bigger. Compare its answer directly against the source material. If it invents details not in the document, that’s a signal to tighten the prompt or check the knowledge base setup before trusting it with real work.
How do knowledge bases and embeddings work in Octop?
Knowledge bases are Octop’s document search layer. You enable the feature, then choose how embeddings get generated. Embeddings are what let the assistant search for relevant passages rather than relying on everything being pasted into the prompt. You can generate embeddings locally (selecting a downloadable embedding model) or use an online embedding service, which sends document content to a third party and may add cost.
The embedding model is separate from the chat model powering your expert, and running embeddings locally doesn’t change where the chat model itself runs if that model is cloud-based.
Once a knowledge base is set up, you upload documents, wait for them to show as ready, and connect that knowledge base to a specific expert conversation. A good test is asking the expert to summarize a document, cite its source, and specifically confirm or deny details that aren’t actually true in the source. That tells you whether it’s grounding answers in the document or filling gaps with assumptions.
How do teams and coding agent integration work?
Teams let multiple experts collaborate under a coordinator model. You create a team, add at least two expert members plus a coordinator, and give the team a task. The coordinator delegates work to members and assembles their output into a final answer. A practical setup is a “writer” expert and a “reviewer” expert, where the reviewer checks the writer’s claims against source material and the coordinator returns a corrected result.
Team features are explicitly marked beta. One known limitation: stopping the coordinator’s current response doesn’t necessarily stop work already dispatched to the members, so in-flight jobs should be allowed to finish before restarting the app.
For coding tasks, Octop connects to external coding agents through ACP (agent client protocol). Tools like OpenCode need to be installed and configured separately on the same machine running Octop, and Octop needs to be able to find the executable. Once the ACP runner is enabled for an expert, you can ask that expert to use the coding tool to read and write files in a project folder, for instance drafting a markdown file based on source notes. The connection doesn’t include free access to the coding tool’s underlying model. That tool needs its own working setup, and it’s worth inspecting the actual file it produces rather than trusting the chat’s claim that the task is done.
Is Octop worth setting up?
For people who want a self-hosted assistant with configurable experts, document search, and the ability to pull in a coding tool when needed, Octop offers a lot in one dashboard. But it comes with real setup overhead: managing your own model credentials, choosing how embeddings run, and keeping the process alive for scheduled tasks. The team feature is still beta, and running multiple agents against a task means more model calls and a higher bill than a single chat session.
A reasonable approach is starting small: one expert, one model, one small test document. Confirm the answers are accurate and grounded in your source material before adding a reviewer expert, a team, or coding agent access. Because the whole stack is self-hosted and open source, you can build the setup up gradually rather than configuring everything at once.
Frequently Asked Questions
Is Octop completely free to use?
The software itself is free and open source under the MIT license. However, you need to supply your own model, whether through a paid cloud API or a locally run model, and that usage can cost money depending on the provider.
Does running Octop locally keep my data private?
Not automatically. Self-hosting the app means the orchestration and dashboard run on your machine, but if you connect a cloud model provider, your documents and prompts are still sent to that provider for processing.
What’s the difference between an “expert” and a “team” in Octop?
An expert is a single configured agent with its own workspace, model, and instructions. A team combines multiple experts under a coordinator model that delegates tasks and merges their results, useful when a job needs more than one role, like drafting and reviewing.
What is ACP and why does it matter for coding tasks?
ACP (agent client protocol) is how Octop connects an expert to an external coding tool like OpenCode, letting that expert hand off tasks involving reading or writing actual project files rather than just generating text in chat.
Can Octop run entirely on local models?
Yes, it supports connecting a local model through Ollama instead of a cloud API. Performance and the quality of results depend on the hardware available and the specific model chosen.
