로컬·호스팅 모델 사용하기

로컬·호스팅 모델 사용하기 (Use local and hosted models)

sbx run --model로 에이전트 요청에 응답할 모델과 서비스를 고르는 방법을 알아볼게요.

출처: 문서

본문

sbx run --model을 사용해 에이전트의 요청에 응답할 모델과 서비스를 선택해요. 에이전트는 로컬 샌드박스 안에서 실행돼요. 모델은 호스트에서, 호스팅 제공 업체에서, 또는 여러분이 구성한 추론 엔드포인트에서 실행될 수 있어요.

이 페이지는 기본 제공 claude, codex, opencode 에이전트를 다뤄요. 에이전트가 필요로 하는 도구 호출과 컨텍스트 길이를 지원하는 모델을 고르세요. --model은 클라우드 샌드박스나 v3 키트와는 지원되지 않아요.

참고 (Note): 모델 선택은 실험적이에요. 이 예시들을 따르기 전에 활성화하세요.

번들된 모델 서비스 (Bundled model service)

Docker Sandboxes에는 sbx와 함께 설치되는 모델 관리 도구 llmman이 포함돼 있어요. 로컬 모델을 제공하고 호스팅 제공 업체나 커스텀 엔드포인트로 요청을 전달해요. 별도로 설치할 필요 없어요.

Docker Sandboxes를 설치하거나 모델 선택을 활성화해도 llmman이 시작되지는 않아요. Docker Sandboxes는 --provider ollama를 선택하지 않는 한, sbx run --model을 처음 쓸 때 호스트에서 백그라운드 프로세스로 llmman을 시작해요. --model 없이 실행하면 시작하지 않아요.

시작되면 llmman은 샌드박스나 CLI가 종료된 뒤에도 계속 실행돼요. 이후 모델 활성 실행은 그 서비스를 재사용하므로 샌드박스들이 모델 저장소와 로드된 모델을 공유해요.

Linux에서 서비스를 시작하려면 추론 서버 이미지를 pull 하기 위해 호스트에 Docker Engine이 필요해요.

모델 선택 활성화하기 (Enable model selection)

호스트에서 이 명령들을 실행해요:

$ sbx settings set platform.allowExperimentalFeatures true
$ sbx settings set feature.model true

--provider 플래그는 모델이 실행될 곳을 선택해요:

제공 업체 (Provider)	모델 목적지 (Model destination)
생략 또는 `llmman`	`llmman`이 관리하는 로컬 모델
`ollama`	호스트의 기존 Ollama 설치
호스팅 제공 업체 ID	`openai`나 `anthropic`처럼 `llmman`이 지원하는 제공 업체
`model.providers`의 ID	여러분이 구성한 엔드포인트

로컬 모델 실행하기 (Run a local model)

--model에 GGUF 모델 참조나 짧은 이름을 전달해요:

$ sbx run --model gemma4 claude

Docker Sandboxes는 필요하면 모델을 내려받아요. 모델은 호스트에서 실행되므로, 그 메모리와 컴퓨트 요구사항은 샌드박스의 리소스 한도와 분리돼요. claude를 codex나 opencode로 바꿔 같은 모델로 다른 에이전트를 쓸 수 있어요.

Ollama 사용하기 (Use Ollama)

호스트에 Ollama를 설치해 시작한 뒤 --provider로 선택해요:

$ sbx run --model gemma4 --provider ollama claude

Docker Sandboxes는 localhost:11434에서 Ollama에 연결해요. Ollama 프로세스를 설치·시작·관리하지 않아요.

Docker Model Runner는 "Run Claude Code in a Docker Sandbox with Docker Model Runner" 문서를 보세요.

호스팅 제공 업체 사용하기 (Use a hosted provider)

llmman이 지원하는 제공 업체와 그 업체에서 제공하는 모델을 선택해요. 예를 들어 OpenAI 모델로 Codex를 실행하려면 호스트 셸에서 OPENAI_API_KEY를 내보내고 실행해요:

$ sbx run --provider openai --model gpt-5-nano codex

호스트의 llmman 서비스가 요청을 제공 업체로 전달해요. 호스팅 모델을 내려받거나 실행하지 않아요. 사용 가능한 제공 업체와 API 키 변수 이름은 llmman provider 문서를 보세요.

제공 업체 인증 (Provider authentication)

첫 sbx run --model 명령이 llmman을 시작하기 전에 제공 업체의 API 키를 호스트 셸에서 사용할 수 있게 하세요. 커스텀 엔드포인트라면 apiKeyEnv로 변수 이름을 고르세요.

llmman은 그 서비스를 시작한 프로세스의 환경을 상속해요. 다른 셸에서 변수를 바꿔도 이미 실행 중인 서비스는 갱신되지 않아요. 키를 바꾼 뒤에는 호스트의 llmman serve 프로세스를 멈추고, 갱신된 변수가 있는 셸에서 sbx run --model을 실행하세요. 이는 그 서비스를 쓰는 다른 샌드박스의 모델 요청을 중단해요.

이 경로의 제공 업체 인증은 호스트의 llmman이 처리해요. sbx secret set으로 저장한 자격 증명은 자동으로 제공되지 않아요. 에이전트의 기본 인증 흐름은 Manage credentials 문서를 보세요.

커스텀 엔드포인트 연결하기 (Connect a custom endpoint)

OpenAI 또는 Anthropic 호환 추론 엔드포인트(예: 내부 GPU 서버)에 연결하려면 model.providers를 사용해요. 엔드포인트는 호스트에서 도달 가능해야 해요.

이 설정은 제공 업체 ID로 키가 지정된 JSON 객체예요. 바꾸기 전에 기존 값을 확인해요:

$ sbx settings get model.providers

OpenAI 호환 엔드포인트라면 company라는 제공 업체를 정의해요:

$ sbx settings set model.providers '{"company":{"url":"https://inference.example.com/v1","wire":"openai","apiKeyEnv":"COMPANY_API_KEY"}}'

URL을 여러분의 엔드포인트 기본 URL로 바꾸세요. model.providers를 설정하면 전체 객체를 대체하므로 유지하고 싶은 기존 제공 업체를 포함하세요.

필드 (Field)	설명 (Description)
`url`	필수 HTTP 또는 HTTPS 기본 URL. 보통 `/v1`로 끝남. `/chat/completions`나 `/messages` 없는 기본 URL 사용
`wire`	엔드포인트의 API 형식: `openai`(기본) 또는 `anthropic`. 어느 에이전트를 실행하든 엔드포인트를 설명함
`apiKeyEnv`	API 키를 담은 호스트 환경 변수 이름. 키가 필요 없는 엔드포인트면 생략
`name`	선택적 표시 이름. 기본값은 제공 업체 ID

Provider authentication에서 설명한 대로 호스트 셸에서 COMPANY_API_KEY를 내보내고, 제공 업체와 그 엔드포인트가 제공하는 모델을 선택해요:

$ sbx run --provider company --model <MODEL_NAME> claude

Docker Sandboxes는 --model로 실행할 때 제공 업체 구성을 적용해요. 같은 제공 업체를 codex나 opencode와 함께 쓸 수 있어요.

기존 샌드박스의 모델 바꾸기 (Change an existing sandbox's model)

샌드박스 이름과 모델 선택을 전달해요:

$ sbx run --name <SANDBOX_NAME> --model <MODEL_NAME> --provider <PROVIDER_ID>

모델을 바꾸면 샌드박스 컨테이너가 다시 만들어져요. 워크스페이스와 키트 소유 볼륨은 유지돼요. --provider를 생략하면 llmman이 관리하는 로컬 모델을 선택해요.

큰 요청에 다른 제공 업체 사용하기 (Use another provider for larger requests)

로컬 모델의 컨텍스트 용량을 초과하는 요청을 처리하려면 로컬 모델을 다른 제공 업체와 짝지어요:

$ sbx run --model gemma4 \
  --overflow-provider openai --overflow-model gpt-5-nano claude

모델 서비스를 시작하기 전에 제공 업체 인증을 구성하세요. model.providers에 정의된 제공 업체를 쓸 수도 있어요. 두 overflow 플래그가 모두 필요하고, 로컬 모델은 기본 llmman 제공 업체를 사용해야 해요. 이 옵션은 --provider ollama나 --provider로 선택한 호스팅 제공 업체와 함께 쓸 수 없어요.

로컬 모델에 들어맞는 요청은 로컬에 유지돼요. overflow 제공 업체로 라우팅된 요청은 그 내용을 그 엔드포인트로 보내고 제공 업체 요금이 발생할 수 있어요.

더 알아보기 (Learn more)

관련 문서와 심화 내용은 원문을 참고해 주세요.