Como hospedar o Octop com Docker em um VPS

O que é o Octop e por que o alojaria por conta própria

O Octop é um assistente de IA alojado por conta própria para uma família ou uma equipa pequena. A razão para alojar o Octop em vez de usar apenas uma interface de chat é manter os utilizadores separados. O Open WebUI fornece uma interface de navegador à frente de um modelo. O Octop acrescenta contas com uma função de administrador, um espaço de trabalho privado e um conjunto de credenciais para cada utilizador, além de uma biblioteca de agentes especializados entre os quais cada utilizador pode alternar conforme a tarefa. Essa é a diferença que permite a um único VPS servir cinco pessoas em vez de apenas uma.

O projeto está disponível em github.com/TencentCloud/Octop. É um único processo que disponibiliza um painel web, uma interface de linha de comandos, canais de chat (Feishu, DingTalk, QQ, Discord, WeCom) e tarefas agendadas, tudo suportado por uma única base de dados SQLite em ~/.octop/. Tudo o que se segue aplica-se à tag v0.9.19, publicada em 5 August 2026. Se ainda está a decidir entre plataformas, a comparação de alternativas ao Open WebUI que pode executar num VPS abrange as principais opções.

É importante esclarecer uma coisa antes de perder uma noite com isto. O Octop é software anterior à versão 1.0, publicado a partir da organização GitHub de um fornecedor, com cerca de 900 estrelas em August 2026. O desenvolvimento é rápido, como mostram os números das versões, e nada aqui constitui uma promessa de um caminho de atualização estável. Fixe uma tag, leia o changelog e mantenha cópias de segurança.

O que precisa antes de começar

• Um VPS com Ubuntu 24.04, Docker Engine e o plugin Compose. Não conhece o Compose? Comece por Noções básicas do Docker Compose para um VPS.
• git, porque vai fazer checkout de uma tag de release em vez de obter uma imagem.
• Um nome de domínio apontado para o VPS, porque pretende colocar TLS (transport layer security) à frente do serviço.
• Um backend de modelo compatível com a API da OpenAI: um Ollama local, um gateway self-hosted ou uma chave paga.

O próprio Octop é leve. Consiste num processo Python e num ficheiro SQLite. O peso está no backend do modelo. Se pretende executar o modelo no mesmo servidor, dimensione o servidor para esse modelo.

Por que não recomendamos o instalador via curl

O README começa com uma instalação em uma linha:

curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash

Não recomendamos este método em um servidor importante, por um motivo concreto: esse script não está no repositório. Ele é servido a partir de um bucket do Tencent Cloud Object Storage. Nada nele é coberto por uma tag ou um commit do git. Portanto, não é possível comparar o script de hoje com o da semana passada, e não existe histórico que explique uma alteração. Amanhã, o bucket pode fornecer bytes diferentes, sem que nada no projeto registre isso. Encaminhar o resultado diretamente para bash também faz a máquina executar o script antes de você ler qualquer linha.

O instalador também grava dados no host, em vez de usar um container. Ele usa uv para obter o Python 3.12 e criar um ambiente que o gestor de pacotes não conhece. Por isso, a remoção posterior precisa ser feita manualmente.

Há duas opções melhores. Obtenha o script, leia-o e depois execute-o. Isso leva trinta segundos: curl -fsSL <url> -o install.sh, depois less install.sh e, por fim, bash install.sh. Ou use Docker, que é o restante deste guia. O pacote PyPI (pip install octop) é pelo menos um artefato versionado que pode ser fixado em uma release.

Implantar o Octop com Docker Compose, fixado na v0.9.19

Não existe uma imagem publicada para obter desde agosto de 2026. O ficheiro Compose fornecido cria a imagem a partir do repositório, por isso fixar uma versão significa fazer checkout de uma tag git. Isto acrescenta um passo em relação à maioria dos projetos self-hosted, porque algo como um workspace AFFiNE self-hosted fixa uma tag de imagem publicada e nunca cria nada no seu VPS. A rotina de clone, checkout e build abaixo é a mesma que o guia de implementação do openGym apresenta. Se já a configurou uma vez, a estrutura será familiar.

git clone https://github.com/TencentCloud/Octop.git
cd Octop
git checkout v0.9.19

Este é o serviço definido pelo ficheiro, reduzido às partes relevantes:

services:
  octop:
    build:
      context: ..
      dockerfile: docker/Dockerfile
    image: octop:latest
    container_name: octop
    restart: unless-stopped
    ports:
      - "${OCTOP_PORT:-8088}:${OCTOP_PORT:-8088}"
    volumes:
      - ${OCTOP_DATA:-~/.octop}:/data/.octop
    environment:
      - HOME=/data
      - OCTOP_BIND_HOST=0.0.0.0
      - OCTOP_PORT=${OCTOP_PORT:-8088}
      - OCTOP_DEFAULT_PASSWORD=${OCTOP_DEFAULT_PASSWORD:-octop}
      - OCTOP_ADMIN_USERNAME=${OCTOP_ADMIN_USERNAME:-admin}
      - OPENAI_API_KEY=${OPENAI_API_KEY:-}

Observe o bloco build:. image: octop:latest é o nome da build criada por si, não uma referência a um registry. Por isso, latest significa aqui o que compilou mais recentemente. Defina o caminho dos dados explicitamente, em vez de o deixar ao valor predefinido, e defina uma palavra-passe real para a conta de administrador antes do primeiro arranque. Coloque isto em docker/.env:

OCTOP_PORT=8088
OCTOP_ADMIN_USERNAME=admin
OCTOP_DEFAULT_PASSWORD=<a long random password>
OCTOP_DATA=/srv/octop-data

Há uma armadilha aqui que merece mais atenção do que o resto do ficheiro. O Compose lê docker/.env apenas para interpolar os marcadores ${...} no YAML. Uma chave adicionada a esse ficheiro não chega ao contentor, a menos que também esteja listada em environment: no ficheiro Compose. Adicionar OCTOP_ACCESS_TOKEN_TTL apenas a .env não produz efeito algum, sem apresentar qualquer erro. A alternativa é escrever as mesmas chaves em ~/.octop/env dentro do diretório de dados montado, que o Octop carrega no arranque. O guia sobre ficheiros de ambiente e secrets no Docker Compose explica por que razão estes dois mecanismos não são equivalentes.

Crie a imagem e inicie o serviço:

docker compose -f docker/docker-compose.yml up -d --build
docker compose -f docker/docker-compose.yml ps
curl http://127.0.0.1:8088/api/health

Uma instância saudável responde à verificação de saúde com {"status":"ok","version":"..."}. Se obtiver qualquer outro resultado, consulte docker compose -f docker/docker-compose.yml logs -f octop antes de abrir o browser.

Agora atribua um nome significativo à imagem que acabou de criar, porque o --build seguinte vai substituir octop:latest e deixará de ser possível distinguir as duas:

docker image tag octop:latest octop:0.9.19

O primeiro arranque executa octop init e grava as credenciais iniciais no volume de dados:

docker exec -it octop cat /data/.octop/credential.txt

Os valores predefinidos são admin / octop e são aplicados apenas na primeira inicialização. É por isso que surge frequentemente a pergunta sobre a alteração de OCTOP_DEFAULT_PASSWORD depois de o contentor já ter arrancado uma vez. Essa alteração não produz efeito, porque a conta já existe. Altere a palavra-passe no dashboard.

Não publique a porta 8088

A linha ports: acima faz o bind de todas as interfaces na VPS. Assim que o contentor arranca, o dashboard fica disponível na Internet pública em texto simples, com uma palavra-passe predefinida. O valor predefinido de OCTOP_BIND_HOST do Octop é 127.0.0.1; o ficheiro Compose substitui-o por 0.0.0.0 porque o processo tem de aceitar tráfego de fora do seu próprio namespace de rede. Essa substituição está correta. O problema é a porta publicada, que expõe o serviço.

Edite a linha ports: em docker/docker-compose.yml para que o mapeamento escute apenas na interface de loopback:

    ports:
      - "127.0.0.1:${OCTOP_PORT:-8088}:${OCTOP_PORT:-8088}"

Não tente corrigir isto com um simples ficheiro de substituição. O Compose concatena as listas ports de vários ficheiros em vez de as substituir. Assim, acaba por publicar ambos os mapeamentos, e o segundo falha ao fazer o bind. Se quiser manter o ficheiro upstream intacto, use a tag !override na sequência. Essa é a forma documentada de substituir a sequência em vez de acrescentar itens. A explicação sobre como o Compose combina vários ficheiros aborda as restantes regras de combinação.

Fazer o bind à interface de loopback também resolve um problema que, de outro modo, teria com a firewall. O Docker escreve as regras das portas publicadas na tabela nat antes das chains geridas pelo ufw. Por isso, ufw deny 8088 não impede o acesso a uma porta de um contentor publicada. Uma porta associada a 127.0.0.1 nunca pode ser alcançada a partir do exterior, independentemente da configuração do ufw. Por esse motivo, esta é a correção adequada, e não uma alternativa secundária.

Coloque o TLS à frente com um reverse proxy

O Caddy é o caminho mais curto, porque solicita o certificado através do ACME (ambiente de gestão automática de certificados) por conta própria e faz proxy de WebSockets sem configuração adicional:

octop.example.com {
    reverse_proxy 127.0.0.1:8088
}

O nginx requer mais atenção, porque o Octop transmite o chat através de um WebSocket:

server {
    listen 443 ssl;
    server_name octop.example.com;

    ssl_certificate     /etc/letsencrypt/live/octop.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/octop.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8088;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_read_timeout 3600s;
    }
}

Cada linha tem uma função. O chat usa WS /agents/{id}/chat/ws, por isso, sem proxy_http_version 1.1 e os dois cabeçalhos de upgrade, o nginx responde à tentativa de upgrade com 400 Bad Request: o dashboard carrega normalmente, mas todas as mensagens que envia ficam bloqueadas indefinidamente, sem erro na página. proxy_buffering off é importante porque o endpoint de retoma human-in-the-loop devolve text/event-stream, e os SSE (eventos enviados pelo servidor) mantidos num buffer do proxy chegam todos de uma vez no final, em vez de serem transmitidos em fluxo. proxy_read_timeout cobre execuções longas de ferramentas, porque o valor predefinido de 60 segundos interrompe um agente a meio da tarefa e regista upstream timed out (110: Connection timed out).

Como funciona a autenticação JWT atrás do proxy

O Octop autentica com um token bearer, não com um cookie. POST /api/auth/login devolve {access_token, role, user, ...} e as chamadas seguintes transportam Authorization: Bearer <access_token>. Para um reverse proxy, isto é uma vantagem: não há domínio de cookie, flag Secure nem regra SameSite que possa ser configurada incorretamente. Assim, uma sessão que funcionou em http://127.0.0.1:8088 comporta-se da mesma forma em https://octop.example.com.

Há duas consequências que deve conhecer antes de disponibilizar o serviço a utilizadores reais.

O WebSocket transporta o token no URL. O endpoint é WS /agents/{id}/chat/ws?token=<jwt>, porque o JavaScript do navegador não pode definir um cabeçalho Authorization num handshake WebSocket. O TLS protege esse token durante o transporte. Não o protege dos seus próprios logs: o nginx grava por predefinição a linha de pedido completa, incluindo a query string, em access_log. Assim, um token válido de um utilizador real acaba num ficheiro de texto simples no servidor. Registe o caminho sem os argumentos. $uri é o caminho normalizado, já sem a query string. Coloque isto no bloco http e faça referência a ele a partir do servidor:

log_format octop_noargs '$remote_addr [$time_local] '
                        '"$request_method $uri $server_protocol" '
                        '$status $body_bytes_sent';
access_log /var/log/nginx/octop.log octop_noargs;

Não existe logout por sessão. OCTOP_ACCESS_TOKEN_TTL tem 86400 como valor predefinido, por isso um token permanece válido durante 24 horas depois do login. A única forma documentada de invalidar um token é octop admin rotate-jwt-secret. Este comando roda a chave de assinatura armazenada em ~/.octop/secrets/jwt_secret e invalida imediatamente todos os tokens ainda válidos, para todos os utilizadores. Por isso, quando alguém sai da equipa, a ordem é: elimine o utilizador, rode o segredo e depois peça aos restantes utilizadores para iniciarem sessão novamente. Se isto parecer excessivo, reduza o tempo de validade. Lembre-se de adicionar a variável à lista environment: e também a .env:

OCTOP_ACCESS_TOKEN_TTL=28800

A proteção contra força bruta está implementada: OCTOP_LOGIN_MAX_ATTEMPTS tem 5 falhas como valor predefinido e OCTOP_LOGIN_LOCKOUT_SECONDS tem 900. Assim, um utilizador bloqueado fica simplesmente à espera de quinze minutos, em vez de interpretar a situação como uma instalação avariada. O Octop tem o seu próprio armazenamento de utilizadores e não tem suporte OIDC documentado na versão v0.9.19. Se precisar de single sign-on real, coloque um proxy de autenticação à frente dele. É essa a finalidade de um servidor Authentik autoalojado.

Indicar ao Octop um backend de modelos

Os fornecedores são configurados por agente no dashboard, e octop provider list mostra o que está definido. O Octop inclui predefinições para APIs compatíveis com OpenAI, DashScope (Qwen) e Ollama. As credenciais são armazenadas na tabela providers da sua própria base de dados SQLite. Esta escolha altera o que paga e o que sai do servidor.

Um modelo local com Ollama. Nada sai do servidor, e paga em RAM em vez de tokens. O detalhe de ligação que causa problemas: um contentor não consegue aceder ao Ollama do host em 127.0.0.1:11434, porque esse endereço é o loopback do próprio contentor. Adicione uma entrada de gateway do host ao serviço:

    extra_hosts:
      - "host.docker.internal:host-gateway"

Depois, defina o URL base do fornecedor como http://host.docker.internal:11434/v1, que é o caminho compatível com OpenAI do Ollama. Preencha o campo da chave da API com qualquer texto não vazio, porque o Ollama ignora esse valor, mas os clientes OpenAI recusam-se a enviar uma chave vazia. O Ollama também tem de escutar além do loopback para isto funcionar, o que significa OLLAMA_HOST=0.0.0.0:11434 na respetiva unidade systemd. Essa é a parte arriscada: o Ollama não tem autenticação. Uma porta 11434 aberta num IP público disponibiliza gratuitamente um servidor de modelos a quem a detetar primeiro. Permita apenas o intervalo privado do Docker, sudo ufw allow from 172.16.0.0/12 to any port 11434 proto tcp, e bloqueie o restante. Executar Ollama numa VPS aborda o dimensionamento dos modelos, e a comparação entre Ollama e vLLM explica quando o Ollama deixa de ser o servidor adequado.

Há mais um aviso sobre modelos locais, porque isto parece um erro do Octop, mas não é. Os agentes funcionam através da chamada de ferramentas, e o prompt do sistema, as definições das ferramentas e o histórico formam um prompt grande. O Ollama disponibiliza os modelos com uma janela de contexto predefinida modesta, por isso o início do prompt, onde estão as definições das ferramentas, sai da janela. O modelo deixa então de chamar ferramentas ou inventa ferramentas que não existem. Aumente num_ctx para 16k ou 32k e escolha um modelo que seja realmente bom a chamar funções. Uma resposta que termina a meio de uma frase é o problema oposto e depende de uma definição diferente, num_predict. Por isso, se as respostas forem truncadas, vale a pena verificar onde num_predict está definido e o que done_reason indica antes de culpar o agente. Se preferir começar com um candidato específico em vez de uma lista curta, Nemotron 3.5 Lightning merece ser testado. Esse artigo indica a tag exata a obter, a RAM necessária e se o desempenho apenas com CPU é suficiente.

Um gateway autoalojado. Coloque um gateway LiteLLM autoalojado entre o Octop e todos os restantes serviços. Assim, terá um único URL base, uma chave separada por utilizador, limites de consumo e um único log. Também pode trocar o modelo por trás do gateway sem editar nada no Octop.

Uma API paga. A melhor qualidade, com uma contrapartida clara: o conteúdo das conversas sai do seu servidor e chega ao fornecedor, que é precisamente a maior parte do motivo para usar alojamento próprio. A chave é definida em docker/.env como OPENAI_API_KEY, e o ficheiro Compose já a transmite.

Qualquer que seja a opção escolhida, o ficheiro Compose também transporta OCTOP_LANGFUSE_ENABLED, LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY e LANGFUSE_BASE_URL. Assim, pode enviar traces para a sua própria instância Langfuse e ver o que os agentes estão realmente a fazer, em vez de tentar adivinhar através da janela de chat.

Utilizadores, funções e a biblioteca partilhada de agentes

A conta de administração criada no primeiro arranque cria e gere as restantes contas. Cada utilizador tem os seus próprios agentes, espaço de trabalho e credenciais. Esse isolamento é assegurado pelo token armazenado pelo navegador. Em paralelo, existe um conjunto partilhado de competências e subagentes que qualquer pessoa pode utilizar. Esta é a funcionalidade que torna a execução do Octop útil para uma família: uma pessoa cria um bom agente de pesquisa uma vez e ninguém precisa de o recriar.

Tenha cuidado com as ferramentas. O Octop disponibiliza aprovação de ferramentas e proteções para comandos shell, e ambas são reais. No entanto, um agente que executa comandos shell executa-os dentro do contentor do Octop, com o volume de dados montado. As proteções limitam o que um prompt descuidado pode fazer. Não constituem uma fronteira de sandbox. Por isso, mantenha a aprovação de ferramentas ativada para qualquer pessoa a quem não entregaria acesso a um shell. Se estiver a comparar esta opção com outras, o comparativo de agentes de IA autoalojados explica como cada uma trata essa questão.

Atualizar um projeto que lança versões tão rapidamente

[
  {
    "version": "v0.9.16",
    "days_since_previous_release": 2
  },
  {
    "version": "v0.9.17",
    "days_since_previous_release": 3
  },
  {
    "version": "v0.9.18",
    "days_since_previous_release": 1
  },
  {
    "version": "v0.9.19",
    "days_since_previous_release": 3
  }
]

Estas são as datas das tags do repositório, contadas até 7 de agosto de 2026. 4 versões marcadas foram lançadas em nove dias, com um intervalo mínimo de 1 dia, e v0.9.19 foi lançado 3 dias depois da tag anterior. Essa cadência é um bom sinal para o projeto e um mau motivo para executar latest. Leia as alterações antes de aplicá-las:

cd Octop
git fetch --tags
git tag --sort=-creatordate | head
NEW_TAG=$(git tag --sort=-creatordate | head -1)
git log --oneline "v0.9.19..$NEW_TAG"

Faça sempre um backup primeiro, porque as migrações da base de dados são executadas no arranque e uma migração falhada num projeto anterior à versão 1.0 é um problema que terá de resolver:

docker compose -f docker/docker-compose.yml stop
sudo tar czf octop-backup-$(date +%F).tgz -C /srv octop-data
docker compose -f docker/docker-compose.yml start

Depois, faça checkout da nova tag e reconstrua com docker compose -f docker/docker-compose.yml up -d --build. Se algo correr mal, fazer checkout da tag antiga e reconstruir repõe o código, mas apenas o tarball repõe a base de dados.

Esse tarball contém octop.db, config.json, o segredo de assinatura JWT e credential.txt, por isso é tão sensível como o próprio servidor. Mantenha-o com o modo 600 e guarde uma cópia fora do servidor. Numa instalação maior, o projeto também disponibiliza docker/docker-compose.postgres.yml, que executa PostgreSQL com pgvector em vez de SQLite.

Modos de falha e as mensagens que verá

A verificação de integridade nunca responde. curl http://127.0.0.1:8088/api/health fica bloqueado ou recusa a ligação. Leia docker compose -f docker/docker-compose.yml logs -f octop. Um contentor que termina durante a inicialização inicial normalmente não consegue escrever no diretório de dados. Verifique a propriedade do caminho definido em OCTOP_DATA.

O dashboard carrega, mas o chat fica bloqueado. Não aparece nenhum erro na página e nunca chega uma resposta. Abra a consola do browser e procure uma ligação falhada a wss://octop.example.com/agents/.../chat/ws. O proxy não está a encaminhar a atualização da ligação. Adicione proxy_http_version 1.1 e os cabeçalhos Upgrade e Connection.

A resposta completa aparece de uma vez, vários segundos depois. O streaming funciona, mas o buffering está ativo. Defina proxy_buffering off.

bind: address already in use. Já existe outro processo a utilizar 8088. sudo ss -tlnp | grep 8088 identifica-o. Também verá este erro se tiver adicionado uma segunda entrada ports num ficheiro de override em vez de editar a entrada original.

A palavra-passe correta é rejeitada. Cinco tentativas incorretas ativam um bloqueio de 900 segundos. Aguarde esse período em vez de reinstalar.

A nova palavra-passe em .env não teve efeito. Essas credenciais só se aplicam durante a inicialização inicial. Altere a palavra-passe no dashboard.

O agente responde, mas nunca executa uma ferramenta. Quase sempre é um problema do modelo local: a janela de contexto é demasiado pequena para as definições das ferramentas ou o modelo tem pouca capacidade para chamadas de funções. Aumente num_ctx e experimente um modelo desenvolvido para utilizar ferramentas.

FAQ

O Octop substitui o Open WebUI?

Só se precisar do que ele acrescenta. O Open WebUI é uma interface de chat para um modelo e cumpre bem essa função para uma pessoa ou para uma família de confiança. O Octop acrescenta contas com uma função de administrador, workspaces e credenciais por utilizador, além de uma biblioteca selecionável de agentes especializados. Assim, várias pessoas podem partilhar um servidor sem partilharem o mesmo histórico. Se uma única conta for suficiente, o Open WebUI é a opção mais simples e muito mais madura.

Porque não devo usar o script de instalação curl do Octop?

O script é servido a partir de um bucket do Tencent Cloud Object Storage, e não do repositório. Por isso, não está abrangido por qualquer tag ou commit do git. Não é possível comparar o que ele faz hoje com o que fazia na semana passada, e canalizá-lo para bash executa-o antes de o ler. O script também instala o software no host com o seu próprio ambiente Python 3.12, fora do gestor de pacotes. Transfira-o e leia-o primeiro, ou faça o deployment com Docker Compose a partir de uma tag obtida por checkout.

O Octop pode usar um modelo local em vez de uma API paga?

Sim. O Octop comunica com APIs compatíveis com OpenAI e inclui uma predefinição para Ollama. Por isso, apontá-lo para http://host.docker.internal:11434/v1 funciona depois de adicionar extra_hosts: ["host.docker.internal:host-gateway"] ao contentor e definir OLLAMA_HOST=0.0.0.0:11434 no host. Restrinja a porta 11434 à gama de endereços do Docker na firewall, porque o Ollama não tem autenticação própria. Conte com aumentar num_ctx do Ollama para 16k ou mais, porque os prompts dos agentes com definições de ferramentas excedem a janela de contexto predefinida. Nesse caso, o modelo deixa de chamar as ferramentas.

Preciso de um reverse proxy ou posso abrir a porta 8088?

Precisa do proxy. O ficheiro Compose fornecido pelo Octop publica a porta 8088 em todas as interfaces, sem TLS. Assim, as palavras-passe e os bearer tokens atravessariam a Internet em texto simples. Altere a porta publicada para 127.0.0.1:8088:8088 e coloque o Caddy ou o nginx à frente, com um certificado. Com nginx, encaminhe os cabeçalhos de atualização do WebSocket e defina proxy_buffering off. Caso contrário, a página carrega, mas o chat deixa silenciosamente de responder.

O Octop está pronto para produção?

O projeto ainda está numa versão anterior à 1.0 e, em agosto de 2026, publica várias releases identificadas por tag todas as semanas. Por isso, considere-o promissor, mas ainda não estabilizado. Pode ser adequado para uma família ou uma pequena equipa interna se fixar uma tag exata, ler o log de commits antes de cada atualização e fizer uma cópia de segurança do volume de dados antes de cada rebuild. Não o execute em latest e ainda não coloque nele dados de clientes.