SSD Nodes Learn Hosting plans →
Guias Matt ConnorPor Matt Connor

Como hospedar o OneCLI com Docker Compose

Hospede o OneCLI numa VPS com um agente isolado por pessoa, chaves protegidas no gateway, Docker Compose e PostgreSQL. Planeje 2 GiB por sandbox.

O que você obtém ao alojar o OneCLI por conta própria

Aloje o OneCLI por conta própria e cada pessoa da sua equipa terá o seu próprio agente. Cada agente executa no seu próprio sandbox, enquanto as chaves de API ficam num gateway que os agentes nunca conseguem ler. A instalação é uma stack do Docker Compose com PostgreSQL, acessível em http://localhost:10254. Planeie usar uma máquina adequada. O limite predefinido documentado é de 2 GiB de memória por sandbox de agente. Por isso, reserve separadamente memória para a stack base e para a memória realmente utilizada pelos agentes.

Essa stack inclui oito componentes. Saber a função de cada um facilita a leitura do restante deste guia.

  • Dashboard web (Next.js), porta 10254. Criação de agentes, conversas, edição de memória e competências, ligações e segredos.
  • Servidor de API, porta 10256. O plano de controlo: base de dados, gestão de conversas e filas de trabalho.
  • Gateway Rust, porta 10255. Interceta os pedidos de saída dos agentes e injeta as credenciais.
  • Runner. O README descreve-o como o componente que "inicia, suspende e elimina os sandboxes dos agentes. Apenas de saída e sem acesso à base de dados."
  • Supervisor de sandbox. O README descreve-o como um componente que executa "dentro de cada sandbox e comunica através de uma interface de harness independente do fornecedor, para que o runtime do agente possa ser substituído."
  • Terminador SSH, porta 10257. O README chama-lhe "a porta de entrada SSH": termina as ligações SSH com certificados de curta duração emitidos pela API e encaminha cada sessão para o sandbox de um agente. Executa no mesmo perfil runner que o runner.
  • Adaptador de canal. Um daemon que liga uma aplicação Slack, permitindo que um agente responda em canais e mensagens diretas com o seu próprio nome.
  • PostgreSQL. O ficheiro compose fornecido executa postgres:18-alpine com um volume pgdata.

O nome diz CLI, mas o produto é um servidor

O OneCLI é uma plataforma de servidor. O nome sugere uma ferramenta de linha de comandos instalada num portátil, mas essa descrição não corresponde ao produto apresentado neste guia. Existe um cliente de linha de comandos separado no repositório onecli/onecli-cli. Esse cliente encaminha o tráfego de um agente de programação local através de um gateway. O que vai implementar aqui é uma aplicação web multiutilizador: um sistema de contas com organizações e convites, uma base de dados de conversas e segredos, e um runner que inicia contentores.

O modelo por pessoa é a base de todo o design. O README diz: "Cria-se um agente por pessoa, atribui-se a cada agente o acesso de que precisa, e ele funciona numa sandbox, encaminhado através de um gateway que injeta as credenciais e aplica a sua política." Cada agente tem o seu próprio sistema de ficheiros e shell, a sua própria página de conversas, a memória mantida pela plataforma e as skills que escreve uma vez. As credenciais funcionam de forma inversa à configuração habitual. Em vez de copiar uma chave de API para o ambiente de cada pessoa, armazena-se a chave uma vez e atribui-se acesso aos agentes autorizados a utilizá-la.

O que o servidor precisa antes de começar

  • Docker, com o plugin Compose na versão 2.24.0 ou posterior. O ficheiro compose fornecido usa mapeamentos opcionais env_file com required: false, suportados pelo Docker a partir da versão 2.24.0. Os comentários de migração explicam que o requisito mínimo indicado de 2.19 existe para suportar dependências executadas uma única vez com up --wait, mas isso não abrange os ficheiros de ambiente opcionais usados pelo ficheiro.
  • Memória, que é a verdadeira limitação. Leia a secção de dimensionamento abaixo antes de escolher um plano.
  • Portas loopback livres 10254, 10255, 10256, 10257 e 5432. A porta 10257 é a porta de entrada SSH, que começa com o perfil runner ativado por este guia.

Não precisa de instalar PostgreSQL manualmente: o ficheiro compose executa-o como um serviço. O assistente de configuração abaixo precisa de Node.js e pnpm no host. O trabalho no próprio código também usa mise para fixar a toolchain, incluindo Rust para o gateway.

Quantos sandboxes de agentes cabem no seu VPS?

A documentação do próprio runner fornece números concretos. Cada sandbox é limitado a 2048 MB de memória (RUNNER_SANDBOX_MEMORY_MB), uma CPU (RUNNER_SANDBOX_CPUS) e 512 processos (RUNNER_SANDBOX_PIDS). O limite de concorrência é 4 (RUNNER_MAX_SANDBOXES), e a documentação recomenda cerca de 10 GiB de memória livre além da stack base para suportar esse limite.

GráficoAgent memory budgets per box, using the documented 2 GiB cap
Os dados por trás deste gráfico
[
  {
    "plan": "2 GB box",
    "ram_gb": 2,
    "sandbox_slots": 0
  },
  {
    "plan": "4 GB box",
    "ram_gb": 4,
    "sandbox_slots": 1
  },
  {
    "plan": "8 GB box",
    "ram_gb": 8,
    "sandbox_slots": 3
  },
  {
    "plan": "16 GB box",
    "ram_gb": 16,
    "sandbox_slots": 7
  },
  {
    "plan": "32 GB box",
    "ram_gb": 32,
    "sandbox_slots": 15
  }
]

Essas quantidades de slots são cálculos, não um benchmark: memória total, menos aproximadamente 2 GB assumidos para o PostgreSQL e os outros serviços de longa duração, dividido pelo limite de 2 GiB por sandbox. Com base nisso, os orçamentos de 2 GB box para 0 sandboxes no limite máximo de memória; zero significa que não há orçamento para um sandbox no limite máximo segundo estas premissas, e não que o Docker se recuse a iniciar um agente. Um 16 GB box deixa espaço para 7, bem acima do limite padrão de quatro e dos cerca de 10 GiB de memória livre exigidos pela documentação do runner. O 32 GB box permite chegar a 15. Executar mais de quatro ao mesmo tempo também exige aumentar RUNNER_MAX_SANDBOXES.

Dois fatores alteram esse cálculo. Um sandbox com um processo em segundo plano em execução nunca fica suspenso. Por isso, mantém o seu slot permanentemente ocupado. Dimensione RUNNER_MAX_SANDBOXES para a carga sustentada, e não para o minuto de maior utilização. A plataforma impõe um limite para isso: por padrão, cada runner mantém no máximo RUNNER_MAX_SANDBOXES menos um sandboxes mantidos ativos (nunca menos de um), valor que pode ser substituído por MAX_HELD_AWAKE_SANDBOXES na API. Acima desse limite, o runner remove o sandbox que está inativo há mais tempo e informa que o processo monitorizado foi perdido. O uso de memória e CPU depende do trabalho executado. Cada sandbox é limitado a uma CPU, portanto quatro agentes ocupados podem usar quatro núcleos. No entanto, a configuração de 2 GiB de memória é um limite máximo, não uma reserva: quatro agentes inativos mas ativos não consomem automaticamente 8 GiB.

Configurações do runner que pode querer alterar
  • RUNNER_MAX_SANDBOXES (predefinição 4): quantos sandboxes são executados ao mesmo tempo.
  • RUNNER_SANDBOX_MEMORY_MB (predefinição 2048): limite de memória por sandbox.
  • RUNNER_SANDBOX_CPUS (predefinição 1): limite de CPU por sandbox.
  • RUNNER_SANDBOX_PIDS (predefinição 512): limite de processos por sandbox.
  • RUNNER_NETWORK_INTERNAL (predefinição true): mantém a rede do sandbox sem rota de saída. Mantenha esta opção ativada.
  • RUNNER_SANDBOX_NETWORK (predefinição onecli-sandboxes): a rede à qual os sandboxes se ligam.
  • RUNNER_RECONCILE_SECONDS (predefinição 60): com que frequência o runner reconcilia o estado.
  • RUNNER_ORPHAN_GRACE_SECONDS (predefinição 3600): idade a partir da qual os contentores e volumes órfãos são destruídos.
  • RUNNER_AGENT_IMAGE: substitui a imagem do sandbox, que, de outro modo, segue ONECLI_VERSION.

Instalar o OneCLI com Docker Compose

A sequência original do documento de self-hosting escreve três segredos em docker/.env, junto do ficheiro Compose. Essa sequência não inclui o token do runner, o grupo do socket Docker nem as credenciais SSH exigidas pelos serviços que ativa. Por isso, execute o assistente de configuração antes de iniciar a stack.

git clone https://github.com/onecli/onecli.git && cd onecli/docker
cat > .env <<EOF
SECRET_ENCRYPTION_KEY=$(head -c 32 /dev/urandom | base64)
GATEWAY_INTERNAL_SECRET=$(head -c 32 /dev/urandom | base64)
BETTER_AUTH_SECRET=$(head -c 32 /dev/urandom | base64)
COMPOSE_PROFILES=runner
EOF
chmod 600 .env
cd ..
pnpm install
pnpm run setup
cd docker
docker compose up -d --wait

Leia esse bloco antes de o executar. O marcador do heredoc não está entre aspas, por isso a shell executa cada head -c 32 /dev/urandom | base64 e escreve o resultado, em vez do texto literal. SECRET_ENCRYPTION_KEY é a chave AES-256-GCM de todos os segredos da base de dados. GATEWAY_INTERNAL_SECRET autentica o gateway perante a API. BETTER_AUTH_SECRET assina os cookies de sessão. COMPOSE_PROFILES=runner é a linha mais importante, porque o serviço runner está atrás de um perfil Compose: se a omitir, a stack fica operacional, mas nenhum sandbox de agente é iniciado.

--wait aguarda que os serviços estejam em execução ou saudáveis e que a dependência das migrações termine com sucesso. Por isso, uma saída diferente de zero é o primeiro sinal de que existe um problema. Em seguida, verifique o que foi realmente iniciado.

docker compose ps
docker compose logs migrations

Fixe a versão. ONECLI_VERSION define a tag para todos os serviços de uma só vez, e a imagem do sandbox do agente segue essa versão, exceto se RUNNER_AGENT_IMAGE apontar para outro local. Use apenas o número da versão: as tags das imagens publicadas não têm o prefixo v. Em 1 November 2026, a versão atual é v2.17.0, publicada em 31 October 2026. Adicione-a ao mesmo ficheiro e use depois o procedimento de atualização documentado, para que os sandboxes em execução também passem a usar essa imagem.

echo 'ONECLI_VERSION=2.17.0' >> .env
cd ..
pnpm run setup --upgrade
cd docker

Também existe um instalador, curl -fsSL https://onecli.sh/install | sh, que escreve a configuração em ~/.onecli/.env e executa o mesmo trabalho. Ele define ONECLI_VERSION=latest durante a própria execução, substituindo uma versão fixada apenas nesse ficheiro .env. O caminho com Compose é aquele em que pode ler todos os ficheiros antes de executar qualquer componente. É também o caminho a usar num servidor que já aloja outras stacks Compose. A configuração obtida acima é atualizada com pnpm run setup --upgrade. Esse caminho requer Node.js e pnpm no servidor. Se também trabalhar diretamente no código, requer mise e Rust para o gateway, pelo que é adequado para quem pretende alterar o OneCLI. Para Kubernetes, a release v2.11.0 (8 October 2026) adicionou um chart Helm. O chart atual executa os sandboxes de agente como Jobs com volumes persistentes, sem um daemon Docker, e documenta os segredos, a base de dados e a configuração de encaminhamento necessários.

Aceder ao dashboard a partir do portátil

Todas as portas publicadas no ficheiro compose fornecido estão associadas a ${ONECLI_BIND_HOST:-127.0.0.1}. Num VPS, isso significa que o dashboard está a ser executado e que nada fora do servidor lhe consegue aceder. Esta predefinição está correta. Mantenha-a e crie um túnel:

ssh -N -L 10254:127.0.0.1:10254 you@your-server

Agora abra http://localhost:10254 no portátil. O tráfego passa pela ligação SSH. Assim, não existe um dashboard sem encriptação na Internet pública nem uma porta adicional para configurar na firewall.

Definir ONECLI_BIND_HOST=0.0.0.0 publica o dashboard através de HTTP simples e publica também o PostgreSQL, com a palavra-passe predefinida do ficheiro compose, onecli, exceto se definir POSTGRES_PASSWORD. Também publica a entrada SSH na porta 10257, um serviço que monta o socket do Docker. Se várias pessoas precisarem do dashboard, coloque um reverse proxy com TLS (transport layer security) à frente e mantenha o host associado inalterado. Defina ONECLI_EXTERNAL_URL como o URL HTTPS correspondente e use a configuração de reverse proxy do projeto upstream, que encaminha os caminhos do dashboard, da API e do gateway para os respetivos serviços. Um proxy, por si só, não impede o acesso de pessoas não autorizadas. A documentação de self-hosting afirma que o registo está aberto por conceção e que não existe nenhuma opção para o desativar: qualquer pessoa que consiga aceder ao dashboard pode criar uma conta, que recebe a sua própria organização, e apenas a entrada na sua organização requer um convite. A recomendação é manter o dashboard atrás do perímetro da sua rede. Se esse proxy já estiver à frente das suas outras aplicações self-hosted, encaminhar a autenticação através de uma camada de início de sessão único self-hosted coloca o dashboard atrás do início de sessão que a sua equipa já utiliza. Assim, remover alguém num único local também fecha esta porta.

Crie a primeira conta e, em seguida, conceda uma chave de modelo

Abra o dashboard e crie a sua conta imediatamente. Cada conta nova recebe a sua própria organização, e os colegas entram na sua por convite. O registo continua aberto depois disso, o que é mais uma razão para manter o dashboard atrás do túnel ou de um proxy autenticado. Se estiver a atualizar a partir de uma release anterior à introdução dos logins, faça o registo imediatamente: a documentação de self-hosting indica que os dados existentes passam para a primeira conta registada. Portanto, num host acessível, essa conta deve ser sua.

Depois, armazene uma chave de modelo antes de criar um agente. Um agente alojado precisa de uma chave de modelo concedida, e a ordem é importante: armazene a chave no dashboard, conceda-a ao agente e só depois inicie uma conversa. Se ignorar a concessão, o sandbox nunca arranca. O agente responde na thread a explicar que precisa de uma chave de modelo.

Conceda apenas o necessário. Cada agente recebe apenas o que lhe concedeu, e o gateway aplica essa regra em todos os pedidos. Assim, um agente que lê um repositório não tem acesso à chave do seu fornecedor de pagamentos. A mesma lista de concessões permite controlar os custos. Um agente por pessoa que possa chamar qualquer modelo que possua representa uma fatura por pessoa. Por isso, vale a pena ler como limitar o que um agente pode gastar em chamadas a modelos antes de criar dez agentes.

Como o gateway mantém as chaves fora dos agentes

O gateway é um proxy HTTPS escrito em Rust, à escuta na porta 10255. O cliente HTTP de um agente é configurado para o utilizar, e o agente transporta uma credencial de substituição em vez de uma credencial real. O gateway compara o pedido de saída com as permissões desse agente, desencripta o segredo real, substitui a credencial no pedido e encaminha-o. Os segredos ficam armazenados no PostgreSQL, cifrados com AES-256-GCM (advanced encryption standard, 256-bit, Galois/counter mode), e só são desencriptados no momento do pedido. Cada chamada é registada com a identidade do agente e o respetivo destino. Isto cria uma trilha de auditoria que não existe quando as chaves ficam nos perfis de shell de dez pessoas.

Dois mecanismos determinam como o implementa.

  • A interceção HTTPS é um ataque man-in-the-middle. O gateway gera uma autoridade de certificação local, o agente confia nela, e o gateway termina a ligação TLS do agente e abre uma nova ligação ao serviço upstream. Por isso, um agente cujo cliente HTTP não confie na autoridade de certificação do gateway falha com um erro de verificação do certificado, e não com um erro de autenticação.
  • O agente identifica-se com um cabeçalho Proxy-Authorization. Num único host, onde os agentes e o gateway partilham uma rede Docker interna, esse cabeçalho nunca atravessa uma rede que não controla. Aponte um agente externo ao gateway e proteja a ligação com uma VPN ou transporte TLS, porque esse cabeçalho é um bearer token; o upstream recomenda uma VPN para a porta de proxy CONNECT direta.

A contrapartida é clara: o gateway lê, em texto simples e por conceção, todos os pedidos feitos pelos seus agentes. É o processo mais sensível da máquina. Trate o respetivo host de acordo com esse risco e mantenha reduzido o número de pessoas que podem iniciar sessão, usando utilizadores Linux com privilégios mínimos.

Por que o runner não precisa de uma porta de entrada

O runner funciona apenas com ligações de saída. A documentação indica: "não mantém portas que o mundo exterior possa alcançar, por isso um portátil, um homelab ou uma VPC atrás de NAT funcionam sem ingresso, sem túnel e sem configuração de terminação TLS". NAT significa tradução de endereços de rede, como a que um router doméstico faz. O runner estabelece a ligação de saída para o plano de controlo e obtém o trabalho a partir dele. Por isso, não há nada para encaminhar nem para abrir.

Esse desenho é útil na rede da sandbox. O ficheiro compose define uma segunda rede marcada como internal: true. No Docker, isso significa que não existe conectividade de rede externa. As sandboxes ligam-se a essa rede. O gateway tem ligações às duas redes, por isso é o único caminho de saída. A documentação do runner explica o ponto claramente: "uma rede internal com o gateway ligado a ambas é o que transforma a saída apenas pelo gateway num limite efetivo, e não numa mera recomendação". Um agente não pode contornar o gateway abrindo uma ligação direta para um endereço externo. A política do gateway continua a decidir quais pedidos são permitidos.

Confirme isto no seu próprio sistema, em vez de confiar apenas no parágrafo acima.

docker network ls
docker network inspect onecli-sandboxes | grep -i internal

Deve ver "Internal": true. Se aparecer false, o controlo de saída está desativado e o gateway volta a ser apenas uma recomendação. Use o nome da rede da sandbox apresentado por docker network ls, porque onecli-sandboxes é apenas o valor predefinido.

Qual é a robustez do sandbox do OneCLI?

Leia esta seção com atenção, porque o termo "sandboxed" tem grande importância na descrição do próprio projeto, enquanto o mecanismo é documentado na documentação do runner e no código do backend.

O README diz que cada agente recebe "o seu próprio sandbox isolado, com um sistema de ficheiros e uma shell", e identifica o Sandbox Supervisor como o componente que "é executado dentro de cada sandbox, utilizando uma interface de harness neutra em relação ao fornecedor, para que o runtime do agente possa ser substituído". Nenhuma das frases explica de que é feito o isolamento. A documentação do runner explica: o backend predefinido é o Docker (RUNNER_BACKEND=docker), e um sandbox é um container Docker com limite de memória, limite de CPU e limite de processos, ligado à rede interna. O código mantém uma camada de abstração para outros backends. O código atual do runner também implementa um backend Kubernetes, que o Helm chart utiliza para Jobs de sandbox e volumes persistentes. Na instalação com Compose deste guia, um sandbox é um container Docker.

A documentação do runner descreve agora o limite do Docker: o agente é executado como node, com no-new-privileges, todas as capacidades do Linux removidas e o perfil seccomp predefinido do Docker. O backend monta no sandbox apenas o diretório home persistente do agente. Portanto, adote uma interpretação restrita. Os limites são limites de recursos. A rede interna é um controlo real de saída. O isolamento entre um agente e o seu host utiliza estes controlos de container, e um container partilha o kernel do host.

Há um segundo facto a considerar. O serviço runner monta /var/run/docker.sock, porque é assim que cria sandboxes. O acesso ao socket de um daemon Docker rootful equivale a root no host, porque qualquer pessoa que possa chamar essa API pode iniciar um container com o sistema de ficheiros do host montado dentro dele. O runner baseado em Docker fornecido pelo projeto utiliza esse socket. A consequência é que o processo runner é tão sensível quanto o gateway. O terminador SSH monta o mesmo socket para poder executar comandos dentro dos containers de sandbox, e os próprios comentários do compose file classificam essa montagem como equivalente a root no host. Por isso, mantenha a porta 10257 ligada apenas ao loopback, a menos que tenha uma razão para a expor.

Trate o limite baseado num kernel partilhado de forma conservadora. Na prática, isso significa adotar três hábitos.

  1. Execute o OneCLI numa máquina que não faça mais nada. Não coloque nessa máquina nenhum serviço de produção não relacionado, nenhuma base de dados partilhada e dados de outras equipas.
  2. Parta do princípio de que um agente que obtenha execução arbitrária de código dentro do seu sandbox pode alcançar o host e torne esse cenário recuperável com cópias de segurança guardadas fora da máquina.
  3. Leia apps/runner/src ou pergunte aos responsáveis pelo projeto antes de dizer a um colega que o agente está contido.

Para ver como é um limite documentado e quais são as perguntas que vale a pena fazer aos responsáveis pelo projeto, compare esta seção com como é um limite real de sandbox de agente. A questão é saber se o mecanismo documentado cobre as ameaças que precisa de impedir.

A divisão das licenças e por que deve verificar antes de criar

O núcleo do OneCLI está sob a licença Apache-2.0, e é permitido alojá-lo internamente em produção. Os diretórios com o nome ee/ estão abrangidos por uma licença OneCLI Enterprise separada: são gratuitos para desenvolvimento, testes e avaliação, mas exigem uma subscrição para utilização em produção. As notas de versão da v2.0.1, de 18 August 2026, mencionam a reposição de um ficheiro de licença Apache-2.0 detetável pelo GitHub, pelo que o badge na página do repositório mudou recentemente. Verifique a tag que vai efetivamente implementar, em vez de confiar num resumo escrito noutra data.

cd onecli && find . -type d -name ee -not -path '*/node_modules/*'

Tudo o que estiver nesses caminhos corresponde à parte comercial. Se uma funcionalidade de que pretende depender estiver aí, calcule o custo antes de criar um processo com base nela.

Atualizações, migrações e o único ficheiro que não pode perder

As atualizações têm de renovar as imagens dos serviços e a imagem separada do agente. Depois, têm de reiniciar os sandboxes em execução. Um serviço de migração executado uma única vez é iniciado antes da API em cada up. Se uma migração falhar, a stack recusa iniciar em vez de servir pedidos com um esquema parcialmente migrado. Esse é o comportamento pretendido, porque uma atualização falhada aparece como uma indisponibilidade, e não como corrupção silenciosa. O docker compose logs migrations explica o motivo.

É fácil não reparar num passo. A documentação de self-hosting desaconselha fazer a atualização com um docker compose pull && docker compose up -d simples, porque a imagem do sandbox do agente não é um serviço do Compose. É o valor RUNNER_AGENT_IMAGE no runner. Por isso, o docker compose pull nunca o deteta, e os agentes alojados podem continuar a usar uma imagem de sandbox antiga sem qualquer aviso. Atualize o checkout, altere o pin e execute a ferramenta de atualização documentada. Essa ferramenta descarrega a imagem do sandbox e reinicia os sandboxes em execução.

cd onecli
git pull
sed -i 's/^ONECLI_VERSION=.*/ONECLI_VERSION=2.17.0/' docker/.env
pnpm install
pnpm run setup --upgrade
cd docker
docker compose logs migrations

Substitua 2.17.0 pela release para a qual está a atualizar. Os reinícios dos sandboxes interrompem o trabalho em curso. O workspace persistente de cada agente é preservado.

Se instalou o sistema com o script de instalação, execute novamente esse script em vez de fazer o pull manualmente. Assim, o ficheiro do Compose mantém-se alinhado com as imagens referenciadas. Exporte ONECLI_VERSION primeiro se quiser uma release específica, porque o script substitui um pin mantido apenas no seu ficheiro .env.

Faça uma cópia de segurança da base de dados, da configuração e dos volumes do workspace dos agentes. O PostgreSQL contém os agentes, as conversas, a memória e os secrets encriptados. O ficheiro docker/.env contém SECRET_ENCRYPTION_KEY. Sem essa chave, os secrets encriptados ficam ilegíveis, mesmo que o resto da base de dados seja restaurado. O /workspace de cada agente reside num volume persistente separado e precisa da sua própria cópia de segurança.

cd onecli/docker
docker compose exec -T postgres pg_dump -U onecli onecli | gzip > ~/onecli-db.sql.gz
install -m 600 .env ~/onecli-env.backup

Mantenha essas cópias e as cópias de segurança dos workspaces fora do servidor. O procedimento é o mesmo que qualquer stack Compose com estado precisa. Se já faz cópias de segurança e atualiza uma stack Docker Compose regularmente, adicione os volumes da base de dados, da configuração e dos workspaces ao procedimento e deixe de se preocupar com isso.

Quando não funciona

  • A stack nunca fica saudável e docker compose up -d --wait termina com código diferente de zero. Consulte primeiro docker compose logs migrations, porque a API espera deliberadamente por esse serviço.
  • Um agent fica inativo e nenhum sandbox aparece. Verifique se COMPOSE_PROFILES=runner está em docker/.env e se docker compose ps lista um runner. Depois confirme se o agent recebeu uma model key autorizada, porque os sandboxes não são iniciados sem uma.
  • Não há slots disponíveis. RUNNER_MAX_SANDBOXES usa 4 por padrão, e um sandbox com um processo em segundo plano em execução mantém o slot até que o limite de permanência ativa o remova. docker ps mostra o que está realmente em execução.
  • A stack não inicia e o Docker informa que uma porta já está em uso. Com o perfil runner ativado, a porta de entrada SSH usa 10257, além das outras quatro portas.
  • Os containers desaparecem ou o host fica lento. Verifique se há esgotamento de memória com dmesg -T | grep -i oom; o limite de memória padrão permite que um único sandbox use até 2048 MB.
  • As chamadas HTTPS de um agent falham com erros de verificação de certificado, e não com erros de autenticação. O cliente HTTP não confia na autoridade de certificação do gateway.
  • Containers ou volumes antigos permanecem depois de eliminar um agent. O runner faz a reconciliação a cada 60 segundos e destrói órfãos com mais de RUNNER_ORPHAN_GRACE_SECONDS, que por padrão é 3600; aguarde uma hora antes de considerar isso um vazamento.

É isto que deve executar?

O teste de adequação é curto. O OneCLI é útil quando várias pessoas precisam de um agente e pretende manter as credenciais num único local: um único armazenamento para fazer a rotação, um único log de auditoria para consultar e um único dashboard onde revogar o acesso de uma pessoa revoga efetivamente esse acesso. Este é um problema operacional real. Copiar uma chave de API para seis portáteis é uma solução pior.

Para uma só pessoa, é muita infraestrutura sem benefício real. Teria de executar PostgreSQL, um plano de controlo, um gateway e um runner para obter um único agente. O problema das credenciais que o gateway resolve quase não existe quando a única pessoa que possui a chave é você. Em vez disso, execute um único harness numa máquina menor: um harness de agente num VPS faz esse trabalho com uma fração da memória. Se ainda não escolheu nenhuma direção, o levantamento comparação entre agentes de IA self-hosted é um primeiro passo mais económico. Se o que não conhece bem são os próprios agentes, e não os servidores onde eles são executados, siga primeiro um percurso faseado para aprender como os agentes funcionam na prática. Compreender o que uma chamada de ferramenta e um armazenamento de memória fazem na realidade é o que permite determinar que permissões o agente de cada pessoa deve receber.

FAQ

Quais são os requisitos mínimos do servidor para alojar o OneCLI?

Docker com o plugin Compose na versão 2.24.0 ou posterior, Node.js e pnpm para o assistente de configuração usado aqui, além de memória suficiente. O PostgreSQL é incluído no ficheiro Compose, portanto não é necessário instalá-lo separadamente. A memória determina o planeamento: por predefinição, o runner limita cada sandbox de agente a 2048 MB, e a documentação recomenda cerca de 10 GiB livres além da stack base para suportar o limite predefinido de quatro sandboxes. Considerando o orçamento assumido de 2 GB para a stack base, um servidor com 4 GB permite uma sandbox no limite máximo, e um servidor com 16 GB cobre o limite predefinido de concorrência. Estes valores servem para planeamento. Não são requisitos mínimos medidos nem alocações fixas de memória.

O OneCLI precisa de PostgreSQL ou pode usar SQLite?

Precisa de PostgreSQL. DATABASE_URL é documentado como uma string de ligação do PostgreSQL, o ficheiro Compose fornecido executa postgres:18-alpine com um volume pgdata, e um serviço de migrações separado aplica o schema antes de a API arrancar. Não existe uma opção SQLite documentada. Para usar um servidor PostgreSQL externo, configure a API e o serviço de migrações para o utilizarem. O ficheiro Compose fornecido define as strings de ligação desses serviços para o serviço PostgreSQL incluído.

A sandbox do agente OneCLI é uma fronteira de segurança real?

O mecanismo Compose documentado é um contentor Docker com limites de memória, CPU e processos, ligado a uma rede marcada como internal: true para que o tráfego externo passe pelo gateway. O controlo de saída é efetivo e pode verificá-lo com docker network inspect. O agente é executado como node, com no-new-privileges, todas as capacidades Linux removidas e o perfil seccomp predefinido do Docker, mas partilha o kernel do host. O runner e o terminador SSH montam ambos /var/run/docker.sock, o que equivale a acesso root num host que utiliza um daemon Docker rootful. Execute o OneCLI num servidor dedicado e mantenha as cópias de segurança fora desse servidor.

Preciso de abrir portas de entrada para o OneCLI?

Não. O runner apenas inicia ligações de saída e não expõe portas acessíveis a partir da Internet, pelo que funciona atrás de NAT sem túnel. O ficheiro Compose associa por predefinição o dashboard, o gateway, a API, o PostgreSQL e, no perfil runner, a porta de entrada SSH em 10257 a 127.0.0.1. Aceda ao dashboard através de um túnel SSH ou utilize a configuração de reverse proxy do projeto upstream, com TLS e as rotas necessárias para o dashboard, a API e o gateway, se várias pessoas precisarem de acesso. Tenha em atenção que o registo continua aberto a qualquer pessoa que consiga aceder-lhe. O gateway na porta 10255 destina-se aos agentes. Num único servidor, esses agentes acedem-lhe através da rede Docker interna.

O OneCLI pode ser utilizado gratuitamente dentro de uma empresa?

O núcleo utiliza a licença Apache-2.0, e a utilização self-hosted em produção é permitida sem licença comercial. Os diretórios com o nome ee/ estão abrangidos pela OneCLI Enterprise License, que é gratuita para desenvolvimento, testes e avaliação, mas exige uma subscrição em produção. A separação muda entre versões. As notas da v2.0.1, de 18 August 2026, mencionam a reposição de um ficheiro de licença Apache-2.0 detetável pelo GitHub. Por isso, verifique LICENSE e os diretórios ee/ na tag exata que vai implementar antes de criar um workflow dependente de uma funcionalidade específica.

Este artigo foi útil?