Docker Integration

Three Docker capabilities: Docker Model Runner for GPU-accelerated local inference, Ollama containers via docker-compose, and the MCP Docker Gateway for unified tool catalogs.

Docker Model Runner

Docker Desktop’s built-in inference engine. CodeBuddy enables it, pulls models, and routes to it automatically.

Setup:

1. Docker Desktop installed + running.
2. In CodeBuddy: Docker panel → Enable Model Runner, or ask the agent to enable it.

Runs:

docker desktop enable model-runner --tcp=12434
docker model pull <model-name>

Models accessible at http://localhost:12434/engines/llama.cpp/v1 (OpenAI-compatible API).

Model management:

Action	CLI equivalent
List models	docker model ls --json
Pull	docker model pull <name>
Delete	docker model rm <name>
Use	Auto-sets local.model, local.baseUrl, switches to Local provider

Port fallback: on “Use Model”, CodeBuddy tries port 12434 first (1-second timeout). If unavailable, falls back to Ollama on 11434. local.baseUrl set automatically.

Ollama via Docker Compose

Extension ships a docker-compose.yml for running Ollama in a container:

• 32 GB memory limit
• Optional GPU passthrough
• Persistent volume for models
• Port 11434 exposed

Start via “Start Ollama container” in the Docker panel:

docker compose -f <extension-path>/docker-compose.yml up -d

Model management:

Action	CLI equivalent
Status	docker ps --filter name=ollama --format json
List models	docker exec ollama ollama list
Pull model	docker exec ollama ollama pull <name>

Docker availability detection: CodeBuddy probes the socket directly (/var/run/docker.sock on Unix, \\.\pipe\docker_engine on Windows) to check if Docker is running. Results cached 15 s to avoid repeated spawn failures.

MCP Docker Gateway

Unified MCP tool catalog from a single Docker-managed endpoint.

How it works:

1. CodeBuddy detects the gateway via docker mcp --help + docker info.
2. When docker-gateway is the only enabled MCP server, all MCP tools come from that one endpoint.
3. Transport: stdio or SSE.

Reliability features:

Feature	Behavior
Circuit breaker	3 failures → 5-minute cooldown per server
Idle shutdown	Disconnects after 5 min inactivity, reconnects on-demand
macOS PATH fixup	Injects /usr/local/bin:/opt/homebrew/bin etc. for CLI discovery
Graceful degradation	If Docker is unavailable, agent continues with core tools only

Docker panel commands

Webview commands (docker-* message type):

Command	Purpose
docker-enable-runner	Enable Docker Model Runner
docker-start-compose	Start Ollama container
docker-check-status	Check Docker availability
docker-check-ollama-status	Check Ollama container status
docker-get-models	List all local models
docker-get-local-model	Get current local model config
docker-pull-model	Pull a Docker model
docker-pull-ollama-model	Pull an Ollama model
docker-delete-model	Delete a model
docker-use-model	Switch active model (with port fallback)

Terminal security

Docker commands routed through the terminal are strictly whitelisted. Only these arg patterns pass validation:

• Model ops — model ls, model pull <name>, model rm <name>
• Container ops — ps --filter name=ollama, compose up -d, exec ollama ollama list
• MCP ops — mcp server ls, mcp gateway run
• Setup — desktop enable model-runner --tcp=12434

Model names validated against /^[a-zA-Z0-9/:\-.]+$/ — no injection.

Configuration

No Docker-specific settings — Docker integration re-uses local model settings:

Setting	Purpose
local.model	Model name (auto-set on “Use Model”)
local.baseUrl	Endpoint URL (auto-set with port fallback)
generativeAi.option	"Local" when a Docker model is selected

See Local Models for the full local-provider setup.

Related

• MCP — the transport that powers the Docker Gateway
• Local models — provider abstraction Docker plugs into