OpenCode no Docker ajuda a obter runtime reproduzível, limite claro de arquivos ou um caminho para modelo local. O contêiner não é seguro por si só: imagem, volumes, credenciais, rede, permissões e evidências antes da escrita precisam ser revisados.
Resposta rápida: escolha o caminho Docker
Docker Sandbox serve para um workspace isolado gerenciado, mas você precisa conhecer os arquivos montados, o provedor que recebe o código e as permissões.
Docker Model Runner fornece o serviço de modelo e o OpenCode continua sendo a interface. Um endpoint funcionando não configura projeto e permissões.
Uma imagem própria fixa Node e pacotes, mas cria responsabilidade pelo Dockerfile, usuário, atualizações e segredos.
Caminhos de configuração e compromissos
`opencode docker image`, `opencode docker compose` e `docker opencode` são variações da mesma decisão. Uma tabela é suficiente.
Comece com a imagem mínima que execute o CLI e alcance o provedor. Evite serviços extras e o volume do home no primeiro teste.
Se a razão é privacidade, documente o serviço de inferência separado do agente. O endpoint não substitui a revisão do volume.
| Caminho | Bom para | Limite a validar |
|---|---|---|
| Docker Sandbox | Workspace isolado rápido | Autenticação, volume e permissões |
| Docker Model Runner | Inferência local ou privada | Modelo, endpoint, porta e contexto |
| Imagem própria | Ferramentas fixas e equipe | Dockerfile, usuário, updates e segredos |
| Docker Compose | Vários serviços | Nomes, rede, volumes e limpeza |
Antes de executar OpenCode no contêiner
Verifique a origem da imagem antes de montar código. Prefira documentação oficial ou Dockerfile, base e atualização auditáveis.
Monte apenas o projeto; evite home, chaves SSH, credenciais cloud e socket Docker do host.
Injete credenciais em runtime, nunca em Dockerfile, camadas, Compose versionado ou histórico do shell; confira `.dockerignore`.
Use repositório pequeno, leitura, mudança segura, diff Git e teste sem efeito em produção.
7 verificações para um setup confiável
As verificações transformam o início em evidência: modelo ausente aponta para endpoint, arquivos errados para volume e escrita ampla para permissões.
Use a mesma ordem no notebook e na CI e registre imagem, provedor, caminho e comando.
Uma resposta não prova segurança se imagem ou volume forem amplos demais.
- Inspecione a imagem Registre nome, tag/digest, base, atualização e usuário.
- Crie workspace estreito Monte só o projeto e use branch ou worktree separado.
- Conecte um provedor Valide endpoint e mantenha a chave fora do repositório.
- Confirme o modelo Cheque resposta, ID, contexto e porta no contêiner.
- Faça leitura Peça um resumo antes de permitir mudanças.
- Revise um diff Altere documentação ou fixture e rejeite arquivos estranhos.
- Registre limpeza Pare o contêiner, remova volumes temporários e anote a correção.
Docker Model Runner e endpoints compatíveis com OpenAI
Docker Model Runner é útil para inferência local ou privada. Ative o modelo, valide-o na mesma rede e use URL e ID exatos.
Teste endpoint e OpenCode separadamente e depois confirme contexto, permissões e sessão.
Limite interface e portas e registre gateway, serviço Compose ou servidor remoto.
# Illustrative shape only; confirm current image, endpoint, and model fields in official docs
docker run --rm -it --mount type=bind,src="$PWD",dst=/workspace --workdir /workspace -e OPENAI_API_KEY -e OPENAI_BASE_URL opencode-image:reviewed opencodePermissões, segredos, portas e Git
A fronteira do contêiner é só parte das permissões. OpenCode, Docker, usuário Linux, provedor e Git precisam concordar.
Documente comando mínimo, limpeza, volumes, portas privadas e reprodução da imagem.
A primeira escrita deve ser pequena; pare diante de segredos, bundles ou arquivos externos.
| Verificação | Padrão seguro | Sinal de risco |
|---|---|---|
| Segredos | Injetar em runtime e rotacionar | Chave em Dockerfile, camada ou Compose |
| Arquivos | Um projeto, non-root e worktree | Home, SSH ou socket Docker |
| Rede | Só endpoint e portas necessárias | Todas as portas ou endpoint público |
| Git | Revisar status e diff | Escrita fora do worktree |
| Imagem | Digest ou tag revisada | `latest` sem responsável |
Solução de problemas: isole a camada que falha
Se `opencode` não existe, confira imagem, PATH, entrypoint e usuário antes de mexer no provedor.
Se o modelo não aparece, teste endpoint dentro do contêiner e confira URL, DNS, porta, credencial e ID; `localhost` pode apontar para o contêiner.
Se a edição falha, reduza volume e escopo, revise permissões e repita leitura.
Quando um teste funciona, mas a próxima execução enxerga arquivos diferentes, compare primeiro o volume montado e o diretório de trabalho. Um status limpo antes do início, uma tarefa somente leitura e um diff salvo mostram se o problema veio do prompt, da permissão ou do contêiner.
Para repetir o fluxo em equipe, registre no mesmo lugar a tag ou o digest da imagem, o provedor, o ID do modelo, a porta, o branch e o comando de limpeza. Assim outra pessoa consegue reproduzir o teste sem adivinhar o nome do host. Se a imagem mudar, confira usuário, PATH, certificados e volumes permitidos antes de ampliar a escrita.
| Sintoma | Camada provável | Primeiro teste |
|---|---|---|
| Comando não existe | Imagem ou PATH | Versão na mesma imagem e diretório |
| Provedor sem modelo | Endpoint ou ID | Teste no contêiner e compare ID |
| Arquivos ausentes | Volume ou diretório | Mostre workdir e projeto |
| Timeout | Rede, porta, cota ou modelo | Pedido curto |
| Arquivos inesperados | Volume ou permissão | Pare, confira Git e reduza volume |
FAQ do OpenCode no Docker
O OpenCode pode rodar no Docker?
Sim, mas imagem, volume, credenciais, rede e permissões precisam de revisão.
Docker Sandbox ou imagem própria?
Sandbox para isolamento gerenciado; imagem própria para dependências fixas que você consiga manter.
Como conecto Model Runner?
Valide o serviço e use URL compatível com OpenAI e ID exato na mesma rede.
O que montar?
Somente projeto ou worktree; evite home, chaves, credenciais e socket Docker.
Preciso de Compose?
Não. Use-o para vários serviços e rede privada reproduzível.
Por que o modelo não aparece?
Confira base URL, localhost, ID, porta, chave e nome do serviço.
Fontes oficiais para conferir
Detalhes de integração mudam. Confira imagens, autenticação, endpoints e permissões na documentação oficial antes de usar comandos em repositórios sensíveis.