Como hospedar o OneCLI com Docker Compose

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

Ao alojar o OneCLI por conta própria, cada pessoa da sua equipa recebe o seu próprio agente. Cada agente é executado no seu próprio sandbox. 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 um servidor adequado. O valor predefinido documentado é 2 GiB de memória por sandbox de agente. Por isso, esta carga de trabalho não é adequada para uma VPS com 1 GB.

A stack inclui sete componentes. Saber a função de cada um facilita a leitura do resto 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 com tráfego de saída, e sem nunca aceder à base de dados."
• Supervisor do Sandbox. O README descreve-o como sendo executado "dentro de cada sandbox, comunicando através de uma interface de harness independente do fornecedor, para que o runtime do agente possa ser substituído."
• Adaptador de canal. Um daemon que liga uma aplicação Slack, para 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 componente 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 é implementado aqui é uma aplicação web multiutilizador: um sistema de contas em que a primeira conta é proprietária da instância, uma base de dados de conversas e segredos e um runner que inicia contentores.

O modelo por pessoa é a base de todo o desenho. Como diz o README: "Cria um agente por pessoa, atribui a cada agente o acesso de que precisa e ele trabalha numa sandbox, encaminhado através de um gateway que injeta as credenciais e aplica a tua política." Cada agente tem o seu próprio sistema de ficheiros e shell, a sua própria página de conversação, a memória mantida pela plataforma e as skills que escreves uma vez. As credenciais funcionam de forma inversa à configuração habitual. Em vez de copiares uma chave de API para o ambiente de cada pessoa, guardas a chave uma vez e concedes 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.19 ou mais recente. O ficheiro Compose utiliza um serviço de migrações executado uma vez, que é aguardado pela API. Esta forma de declarar a dependência requer a versão 2.19.
• Memória, que é a limitação real. Leia a secção sobre dimensionamento abaixo antes de escolher um plano.
• Portas loopback livres 10254, 10255, 10256 e 5432.

Não precisa de instalar PostgreSQL manualmente: o ficheiro Compose executa-o como um serviço. Também não precisa de Node.js nem de Rust. Esses componentes só são necessários no processo de compilação a partir do código-fonte, no qual mise fixa a toolchain.

Quantos sandboxes de agentes cabem no seu VPS?

A documentação do próprio runner apresenta números reais, não estimativas vagas. Cada sandbox recebe 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.

[
  {
    "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 resultam de uma conta, não de um benchmark: memória total, menos aproximadamente 2 GB para o PostgreSQL e os quatro serviços de execução contínua, dividida pelo limite de 2 GiB por sandbox. Com base nisso, o 2 GB box comporta 0 sandboxes, portanto o plano mais barato não consegue executar um agente alojado. O 16 GB box deixa espaço para 7, acima do limite predefinido 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.

Dois fatores alteram essa conta. Um sandbox com um processo em segundo plano em execução nunca é suspenso. Por isso, mantém o seu slot permanentemente ocupado. Dimensione RUNNER_MAX_SANDBOXES para a carga sustentada, não para o minuto de maior atividade. Além disso, a memória esgota-se antes da CPU. Cada sandbox está limitado a uma CPU, portanto quatro agentes ocupados precisam de quatro núcleos. No entanto, quatro agentes inativos, mas ativos, continuam a ocupar 8 GiB.

Instalar o OneCLI com Docker Compose

A documentação de self-hosting do projeto fornece esta sequência exata. Ela grava três segredos em docker/.env, junto ao ficheiro Compose, e depois inicia 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
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 grava o resultado, em vez do texto literal. SECRET_ENCRYPTION_KEY é a chave AES-256-GCM usada para todos os segredos na 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 do Compose: se a omitir, a stack fica saudável, mas nenhum sandbox de agente é iniciado.

--wait mantém a shell bloqueada até todos os serviços comunicarem um estado saudável. Por isso, uma saída diferente de zero é o primeiro sinal de que existe um problema. Depois, verifique o que foi realmente iniciado.

docker compose ps
docker compose logs migrations

Fixe a versão. ONECLI_VERSION define a tag de todos os serviços de uma só vez, e a imagem do sandbox do agente segue essa tag, a menos que RUNNER_AGENT_IMAGE indique outro local. Em 19 August 2026, a versão atual é v2.0.1, publicada em 18 August 2026. Adicione-a ao mesmo ficheiro e inicie novamente a stack.

echo 'ONECLI_VERSION=v2.0.1' >> .env
docker compose up -d --wait

Também existe um instalador, curl -fsSL https://onecli.sh/install | sh, que grava a configuração em ~/.onecli/.env e executa o mesmo trabalho. O caminho com Compose permite ler todos os ficheiros antes de qualquer execução. É também o caminho a usar num servidor que já aloja outras stacks Compose. A compilação a partir do código-fonte é uma terceira opção, documentada como pnpm install e depois pnpm run setup no repositório clonado. Essa opção requer mise, Rust para o gateway e Docker na mesma. Destina-se a quem pretende alterar o código.

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á em execução, mas nada fora do servidor lhe consegue aceder. Essa 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, por isso não existe um dashboard sem encriptação na Internet pública nem é necessário abrir outra porta na firewall.

Definir ONECLI_BIND_HOST=0.0.0.0 publica o dashboard através de HTTP simples e publica também o PostgreSQL. Se várias pessoas precisarem do dashboard, coloque um reverse proxy com TLS (transport layer security) à frente da porta 10254 e mantenha o host associado à porta. Faça isso antes de a instância ter um proprietário. A documentação upstream explica diretamente o motivo: "Até fazer isso, a instância não tem proprietário e, num host acessível, a primeira pessoa que chegar torna-se o proprietário." Se esse proxy já estiver à frente das suas outras aplicações self-hosted, encaminhar a autenticação através de uma camada de single sign-on self-hosted coloca o dashboard atrás do login 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, atribua uma chave de modelo

Abra o dashboard e crie a conta imediatamente. Essa conta é proprietária da instância e, depois de criada, a adesão exige um convite.

Em seguida, armazene uma chave de modelo antes de criar um agente. Um agente alojado precisa de uma chave de modelo atribuída, e a ordem é importante: armazene a chave no dashboard, atribua-a ao agente e só depois inicie uma conversa. Se não fizer a atribuição, a sandbox nunca é iniciada. O resultado é um agente que fica parado sem fazer nada.

Faça atribuições restritas. Cada agente recebe apenas o que lhe foi atribuído, e o gateway aplica essa regra em cada pedido. Assim, um agente que lê um repositório não tem acesso à chave do seu fornecedor de pagamentos. A mesma lista de atribuições permite controlar os custos. Um agente por pessoa com acesso a qualquer modelo que possua gera uma fatura por pessoa. Por isso, vale a pena ler como limitar quanto um agente pode gastar em chamadas de modelo antes de disponibilizar dez agentes.

Como o gateway mantém as chaves fora dos agentes

O gateway é um proxy HTTPS escrito em Rust, que 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 da credencial real. O gateway compara o pedido de saída com as permissões desse agente, desencripta o segredo real, substitui-o no pedido e encaminha-o. Os segredos ficam no PostgreSQL encriptados 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 destino. Isto cria um registo de auditoria que não existe quando as chaves ficam nos perfis de shell de dez pessoas.

Dois mecanismos determinam como fazer a implementação.

• 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 antes de abrir uma nova ligação ao serviço upstream. Por isso, um agente cujo cliente HTTP não confia 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. Se apontar um agente externo ao gateway, a porta do proxy precisa do seu próprio TLS, porque esse cabeçalho é um bearer token.

O compromisso é claro: por conceção, o gateway lê em texto simples todos os pedidos feitos pelos seus agentes. É o processo mais sensível da máquina. Trate o respetivo host em conformidade 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. Segundo a documentação: "não mantém nenhuma porta que o mundo exterior possa alcançar, por isso um portátil, um homelab ou uma VPC atrás de NAT funcionam sem entrada, túnel ou terminação TLS". NAT é a tradução de endereços de rede, o mecanismo usado por um router doméstico. 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 do sandbox. O ficheiro compose define uma segunda rede marcada com internal: true. No Docker, isso significa que não existe qualquer rota para fora do host. Os sandboxes ligam-se a essa rede. O gateway tem interfaces nas 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 ela através de duas interfaces é o que transforma a saída apenas pelo gateway numa fronteira, e não numa sugestão". Um agente que decida enviar o seu código-fonte para um endereço à sua escolha não tem uma rota para o fazer.

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

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

Deverá ver "Internal": true. Se aparecer false, o controlo de saída está desativado e o gateway volta a ser apenas uma sugestão. Use o nome da rede do 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 muito peso na descrição do próprio projeto, embora o mecanismo esteja documentado em exatamente um lugar.

O README afirma 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, comunicando através de uma interface de harness independente do fornecedor para permitir trocar o runtime do agente". Nenhuma das frases explica de que é feito o isolamento. A documentação do runner explica: o backend predefinido é Docker (RUNNER_BACKEND=docker), e um sandbox é um contentor Docker com limites de memória, CPU e processos, ligado à rede interna. O código mantém uma interface para outros backends, e a documentação cita tecnologias como Kubernetes e microVMs como módulos que alguém teria de escrever. Atualmente, no seu servidor, um sandbox é um contentor.

O que a documentação não diz é igualmente importante. Não existe um modelo de ameaças. Não há qualquer declaração sobre executar o daemon Docker sem root, sobre remapeamento de user namespaces, sobre perfis seccomp ou AppArmor além das predefinições do Docker, nem qualquer afirmação sobre uma fronteira ao nível do kernel, como gVisor ou uma microVM. Por isso, adote a 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 é o isolamento fornecido por um contentor Docker normal, e um contentor partilha o kernel do host.

Há um segundo facto a considerar. O serviço runner monta /var/run/docker.sock, porque é assim que cria os sandboxes. O acesso ao socket do Docker equivale a root no host, pois quem consegue chamar essa API pode iniciar um contentor com o sistema de ficheiros do host montado dentro dele. Todos os runners baseados em Docker funcionam desta forma. A consequência é que o processo runner é tão sensível quanto o gateway.

Considere a fronteira não comprovada até que o projeto upstream a documente. Na prática, isso significa adotar três hábitos.

1. Execute o OneCLI num servidor que não faça mais nada. Não coloque nesse servidor serviços de produção não relacionados, uma base de dados partilhada ou dados de outra equipa.
2. Pressuponha que um agente com execução arbitrária de código dentro do seu sandbox pode alcançar o host, e torne esse cenário recuperável mantendo cópias de segurança fora do servidor.
3. Leia apps/runner/src ou pergunte ao projeto upstream antes de afirmar a um colega que o agente está contido.

Para ver um exemplo de como é uma fronteira documentada e quais são as perguntas que vale a pena fazer ao projeto upstream, compare isto com como é uma verdadeira fronteira de sandbox de agente. A diferença está em saber se alguém documentou o mecanismo e aquilo que ele não impede.

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 consistem em aumentar a versão e reiniciar. Um serviço de migrações executado uma 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. Uma atualização falhada passa a parecer uma indisponibilidade, e não uma corrupção silenciosa. docker compose logs migrations explica porquê.

cd onecli/docker
docker compose pull
docker compose up -d --wait
docker compose logs migrations

Se instalou através do script de instalação, execute novamente esse script em vez de obter os ficheiros manualmente. Assim, o ficheiro Compose permanece sincronizado com as imagens referenciadas.

Faça cópias de segurança de duas coisas. O PostgreSQL contém os agentes, as conversas, a memória e os segredos encriptados. O ficheiro docker/.env contém SECRET_ENCRYPTION_KEY. Sem essa chave, os segredos encriptados não podem ser lidos. Por isso, um dump da base de dados, por si só, não restaura nada utilizável.

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 ambas as cópias fora do servidor. O procedimento é igual ao necessário para qualquer stack Compose com estado. Se já faz cópias de segurança e atualiza uma stack Docker Compose regularmente, adicione estes dois caminhos 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 um código diferente de zero. Leia docker compose logs migrations primeiro, porque a API aguarda deliberadamente esse serviço.
• Um agente fica inativo e nenhuma sandbox aparece. Confirme se COMPOSE_PROFILES=runner está em docker/.env e se docker compose ps lista um runner. Depois, confirme se o agente recebeu uma chave de modelo autorizada, porque as sandboxes não são iniciadas sem uma.
• Não há slots disponíveis. RUNNER_MAX_SANDBOXES usa 4 por padrão, e uma sandbox com um processo em segundo plano em execução mantém o slot ocupado permanentemente. docker ps mostra o que está realmente em execução.
• Os contentores desaparecem ou o host fica muito lento. A memória esgotou. dmesg -T | grep -i oom regista as terminações causadas por falta de memória do kernel, e uma única sandbox pode reservar 2048 MB por si só.
• As chamadas HTTPS de um agente falham com erros de verificação de certificado, e não com erros de autenticação. O cliente HTTP do agente não confia na autoridade de certificação do gateway.
• Contentores ou volumes antigos permanecem depois de eliminar um agente. O runner reconcilia o estado a cada 60 segundos e destrói órfãos com mais de RUNNER_ORPHAN_GRACE_SECONDS, que usa 3600 por padrão. Aguarde uma hora antes de considerar isto uma fuga de recursos.

É 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 pessoa, é muita infraestrutura sem benefício. Teria de executar PostgreSQL, um plano de controlo, um gateway e um runner para disponibilizar um único agente. Além disso, o problema das credenciais que o gateway resolve quase não existe quando é o próprio utilizador o único detentor da chave. Em vez disso, execute um único harness num servidor menor: um harness de agente num VPS resolve esse problema usando uma fração da memória. Se ainda não escolheu uma direção, o levantamento comparação de agentes de IA self-hosted é o primeiro passo mais económico.

FAQ

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

Docker com o plugin Compose na versão 2.19 ou posterior e memória suficiente. O PostgreSQL é incluído no ficheiro compose, pelo que não precisa de o instalar separadamente. A memória determina o dimensionamento: o runner aloca 2048 MB por sandbox de agente por predefinição, a documentação pede cerca de 10 GiB livres além da stack base para servir o limite predefinido de quatro sandboxes e aproximadamente 2 GB são usados pelo PostgreSQL e pelos quatro serviços de execução prolongada. Um servidor com 4 GB executa um agente de cada vez. Um servidor com 16 GB suporta confortavelmente o limite predefinido. Um VPS com 1 GB ou 2 GB não consegue iniciar um agente alojado.

O OneCLI precisa de PostgreSQL ou pode usar SQLite?

Precisa de PostgreSQL. DATABASE_URL está documentado como uma cadeia 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 esquema antes de a API arrancar. Não existe uma opção SQLite documentada. Se já executa o PostgreSQL noutro local, aponte DATABASE_URL para essa instância e mantenha o serviço de migrações, porque uma migração falhada interrompe a stack em vez de permitir que sirva um esquema aplicado apenas parcialmente.

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

O mecanismo documentado é um contentor Docker com limites de memória, CPU e processos, ligado a uma rede marcada como internal: true, sem qualquer rota de saída exceto através do gateway. O controlo de tráfego de saída é real e pode verificá-lo com docker network inspect. O isolamento do host tem a força de um contentor, mas o projeto upstream não publica um modelo de ameaças, nenhuma indicação de execução rootless ou de user namespaces e nenhuma fronteira ao nível do kernel, como gVisor ou uma microVM. O runner também monta /var/run/docker.sock, o que equivale a ter root no host. Considere a fronteira entre o agente e o host não comprovada até o projeto upstream a especificar, execute o OneCLI num servidor dedicado e mantenha as cópias de segurança fora desse servidor.

Preciso de abrir alguma porta de entrada para o OneCLI?

Não. O runner só inicia ligações de saída e não mantém portas acessíveis a partir do exterior, pelo que funciona atrás de NAT sem túnel. Por predefinição, o ficheiro compose associa o dashboard, o gateway, a API e o PostgreSQL a 127.0.0.1. Aceda ao dashboard através de um túnel SSH ou coloque um reverse proxy com TLS à frente da porta 10254 se várias pessoas precisarem de o utilizar. O gateway na porta 10255 destina-se aos agentes e, num único servidor, esses agentes acedem-lhe através da rede Docker interna.

O OneCLI é gratuito para utilização dentro de uma empresa?

O núcleo está sob 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 releases e 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.