OpenCode Docker는 재현 가능한 runtime, 명확한 파일 경계, 로컬 모델 연결이 필요할 때 유용합니다. 컨테이너 자체가 안전을 보장하지는 않습니다. 이미지, mount, credential, network, 권한과 쓰기 전 증거를 함께 확인해야 합니다.
빠른 결론: 작업에 맞는 Docker 경로 선택
Docker Sandbox는 관리형 격리 workspace에 적합하지만 어떤 파일을 mount하는지, 어떤 Provider가 코드를 받는지, 어떤 권한이 있는지 확인해야 합니다.
Docker Model Runner는 별도 계층입니다. 모델 서비스를 제공하고 OpenCode는 코딩 인터페이스로 남습니다. 모델이 응답해도 프로젝트 경계와 권한은 설정되지 않습니다.
자체 이미지는 Node와 패키지를 고정할 수 있지만 Dockerfile, 사용자, 업데이트와 secret을 직접 관리해야 합니다.
Docker 설정 경로와 차이
`opencode docker image`, `opencode docker compose`, `docker opencode`는 같은 설정 선택의 변형입니다. 별도 페이지보다 표 하나가 적절합니다.
저장소 하나라면 CLI가 동작하고 Provider에 연결되는 최소 이미지로 시작하세요. 첫 테스트부터 추가 서비스와 home 전체 mount를 넣지 마세요.
모델 프라이버시가 이유라면 추론 서비스와 코딩 agent를 나눠 기록합니다. endpoint가 mount 검토를 대신하지 않습니다.
| 경로 | 적합한 경우 | 확인할 경계 |
|---|---|---|
| Docker Sandbox | 빠른 격리 workspace | 인증, mount, sandbox 권한 |
| Docker Model Runner | 로컬 또는 private 추론 | 모델, endpoint, port, context |
| 자체 Docker 이미지 | 고정 도구와 팀 재현 | Dockerfile, 사용자, 업데이트, secret |
| Docker Compose | 여러 서비스 | 서비스명, network, volume, cleanup |
컨테이너에서 OpenCode를 실행하기 전
코드를 mount하기 전에 이미지 출처를 확인하세요. 공식 문서나 Dockerfile, base, 업데이트 기록을 검토할 수 있는 이미지를 선택합니다.
대상 프로젝트만 mount하고 home, SSH key, cloud credential, 호스트 Docker socket은 피하세요.
credential은 실행 시 주입합니다. Dockerfile, layer, Git에 커밋된 Compose나 shell history에 넣지 말고 `.dockerignore`도 확인하세요.
작은 저장소에서 읽기, 문서나 fixture의 작은 수정, Git diff, 운영 환경을 건드리지 않는 테스트로 시작합니다.
안정적인 OpenCode Docker 설정을 위한 7가지 점검
점검 순서를 지키면 컨테이너 실행이 증거가 됩니다. 모델이 없으면 endpoint, 파일이 다르면 mount, 쓰기 범위가 넓으면 권한을 확인합니다.
노트북과 CI에서 같은 순서를 사용하고 이미지, Provider, 경로와 명령을 기록하세요.
응답이 된다고 안전한 것은 아닙니다. 변경 가능한 이미지, 넓은 volume, 호스트 접근이 남을 수 있습니다.
- 이미지 확인 이름, tag/digest, base, 업데이트 출처와 사용자를 기록합니다.
- 좁은 workspace 만들기 프로젝트만 mount하고 별도 branch 또는 worktree를 사용합니다.
- Provider 하나 연결 endpoint를 검증하고 키는 이미지와 저장소 밖에 둡니다.
- 모델 확인 컨테이너 안에서 응답, ID, context와 port를 확인합니다.
- 읽기 작업 실행 변경 전에 파일 요약을 요청합니다.
- 작은 diff 검토 문서나 fixture만 바꾸고 관계없는 파일은 거부합니다.
- cleanup 기록 컨테이너를 중지하고 임시 volume을 삭제한 뒤 수정 내용을 남깁니다.
Docker Model Runner와 OpenAI 호환 endpoint
Docker Model Runner는 로컬 또는 private 추론에 쓸 수 있습니다. 코딩 모델을 준비하고 같은 network에서 응답을 확인한 뒤 정확한 URL과 ID를 사용하세요.
endpoint 테스트와 OpenCode 테스트를 분리합니다. 이후 context, 권한과 session의 조합을 확인합니다.
인터페이스와 포트를 제한하고 host gateway, Compose 서비스명, 원격 서버 중 무엇을 쓰는지 기록하세요.
# 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 opencode권한, secret, 포트와 Git 안전
컨테이너 경계는 권한 모델의 일부일 뿐입니다. OpenCode, Docker, Linux 사용자, Provider와 Git 규칙이 맞아야 합니다.
최소 명령, cleanup, 허용 volume, private port와 이미지 재현 방법을 문서화하세요.
첫 쓰기는 README 한 줄이나 fixture처럼 작게 합니다. secret, bundle, 프로젝트 밖 파일이 나오면 중지하세요.
| 검사 | 더 안전한 기본값 | 위험 신호 |
|---|---|---|
| Secret | runtime 주입과 실험 후 교체 | Dockerfile, layer, Compose에 키 |
| 파일 | 프로젝트 하나, non-root, worktree | home, SSH, Docker socket |
| Network | 필요한 endpoint와 port만 | 모든 port 공개 또는 public endpoint |
| Git | 쓰기 후 status와 diff 확인 | worktree 밖 쓰기 |
| 이미지 | 검토한 digest/tag | 책임자 없는 `latest` |
문제 해결: 실패한 계층 분리
`opencode`가 없으면 Provider를 바꾸기 전에 이미지, PATH, entrypoint와 사용자를 확인합니다.
모델이 비어 있으면 컨테이너 안에서 endpoint를 테스트하고 URL, DNS, port, credential과 ID를 확인합니다. `localhost`는 컨테이너 자신일 수 있습니다.
응답은 좋은데 편집이 틀리면 mount와 범위를 줄이고 권한을 확인한 뒤 읽기 작업부터 다시 합니다. digest, 모델과 diff를 남기세요.
| 증상 | 가능한 계층 | 첫 확인 |
|---|---|---|
| 명령이 없음 | 이미지 또는 PATH | 같은 이미지와 디렉터리에서 version 실행 |
| Provider에 모델 없음 | endpoint 또는 ID | 컨테이너 안에서 테스트하고 ID 비교 |
| 파일이 없음 | mount 또는 workdir | workdir와 mount 프로젝트 표시 |
| timeout | network, port, quota, model | 짧은 요청과 컨테이너 network |
| 예상 밖 파일 변경 | mount, 권한, 범위 | 중지 후 Git 확인, mount 축소 |
OpenCode Docker 자주 묻는 질문
OpenCode를 Docker 컨테이너에서 실행할 수 있나요?
가능합니다. 다만 이미지, 프로젝트 mount, credential, network와 명령 권한을 검토해야 합니다.
Docker Sandbox와 자체 이미지 중 무엇을 선택하나요?
관리형 격리는 Sandbox, 고정 의존성을 직접 유지할 수 있으면 자체 이미지가 적합합니다.
Docker Model Runner에 연결하려면 어떻게 하나요?
서비스를 확인하고 같은 network에서 공식 OpenAI 호환 base URL과 정확한 모델 ID를 사용합니다.
무엇을 mount해야 하나요?
대상 프로젝트나 worktree만 mount하고 home, SSH key, cloud credential과 Docker socket은 피하세요.
Compose가 반드시 필요한가요?
아닙니다. 여러 서비스를 private network로 재현할 때 사용합니다.
컨테이너에서 모델이 보이지 않는 이유는 무엇인가요?
base URL, 컨테이너 내부 localhost, ID, port, key와 서비스명을 확인하세요.
확인할 공식 자료
통합 세부사항은 바뀔 수 있습니다. 민감한 저장소에서 명령을 실행하기 전에 공식 문서에서 이미지, 인증, endpoint와 권한을 확인하세요.