Coverage for src/ai_shell/container.py: 75%
729 statements
« prev ^ index » next coverage.py v7.17.0, created at 2026-11-17 21:40 +0000
« prev ^ index » next coverage.py v7.17.0, created at 2026-11-17 21:40 +0000
1"""Docker container lifecycle management.
3Replaces docker-compose.yml by using Docker SDK to create and manage containers
4with the exact same configuration.
5"""
7from __future__ import annotations
9import json
10import logging
11import os
12import subprocess
13import sys
14import time
15from pathlib import Path
16from typing import TYPE_CHECKING, NoReturn
18from docker.errors import APIError, ImageNotFound, NotFound
19from docker.types import DeviceRequest, Mount
21import docker
22from ai_shell.defaults import (
23 COMFYUI_CONTAINER,
24 COMFYUI_DATA_VOLUME,
25 COMFYUI_IMAGE,
26 CONTAINER_PREFIX,
27 KOKORO_CONTAINER,
28 KOKORO_IMAGE_CPU,
29 KOKORO_IMAGE_GPU,
30 LLM_NETWORK,
31 N8N_CONTAINER,
32 N8N_IMAGE,
33 NODE_MODULES_VOLUME_PREFIX,
34 OLLAMA_CONTAINER,
35 OLLAMA_CPU_SHARES,
36 OLLAMA_DATA_VOLUME,
37 OLLAMA_IMAGE,
38 OLLAMA_VRAM_BUFFER_BYTES,
39 SHM_SIZE,
40 VOICE_AGENT_CONTAINER,
41 VOICE_AGENT_DATA_VOLUME,
42 VOICE_AGENT_IMAGE,
43 WEBUI_CONTAINER,
44 WEBUI_DATA_VOLUME,
45 WEBUI_IMAGE,
46 WHISPER_CONTAINER,
47 WHISPER_DATA_VOLUME,
48 WHISPER_IMAGE_CPU,
49 WHISPER_IMAGE_GPU,
50 _resolve_env,
51 build_dev_environment,
52 build_dev_mounts,
53 build_n8n_environment,
54 build_n8n_mounts,
55 dev_container_name,
56 docker_tcp_fallback_host,
57 node_modules_volume_name,
58 project_dev_port_map,
59 t3_home_volume_name,
60 vendor_volume_name,
61)
62from ai_shell.exceptions import (
63 ContainerNotFoundError,
64 DockerNotAvailableError,
65 GpuRequiredError,
66 ImagePullError,
67)
68from ai_shell.gpu import detect_gpu, get_vram_info
70if TYPE_CHECKING:
71 from docker.models.containers import Container
72 from docker.models.images import Image
74 from ai_shell.config import AiShellConfig
76logger = logging.getLogger(__name__)
78#: Docker label recording a digest of the project's mount/port config so
79#: edits to ``.ai-shell.yaml`` automatically recreate the dev container.
80DEV_CONFIG_LABEL = "ai-shell.dev.config"
82# Substrings identifying a container start failure caused by host port
83# bindings (Docker's own allocator vs. OS-level refusal, e.g. another
84# process or a Windows winnat excluded port range).
85_PORT_BIND_ERRORS = (
86 "port is already allocated",
87 "address already in use",
88 "failed to bind host port",
89)
92def _host_port_available(port: int) -> bool:
93 """Check whether *port* can be bound on the host running ai-shell.
95 The CLI runs on the same host where Docker publishes ports, so a brief
96 test-bind sees both live listeners and OS-level reservations (Windows
97 winnat excluded port ranges) that Docker's allocator cannot know about.
98 """
99 import socket
101 try:
102 with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
103 sock.bind(("0.0.0.0", port)) # nosec B104
104 except OSError:
105 return False
106 return True
109def _exec_docker(args: list[str]) -> NoReturn:
110 """Execute a docker CLI command with cross-platform TTY support.
112 Uses subprocess.run instead of os.execvp for Windows compatibility.
113 On Windows, os.execvp doesn't truly replace the process, causing TTY issues.
114 """
115 logger.debug("exec: %s", " ".join(args))
116 sys.stdout.flush()
117 sys.stderr.flush()
118 result = subprocess.run(args)
119 sys.exit(result.returncode)
122def _run_docker(args: list[str]) -> tuple[int, float]:
123 """Run a docker CLI command and return (exit_code, elapsed_seconds).
125 Unlike _exec_docker, this does NOT call sys.exit().
126 """
127 logger.debug("run: %s", " ".join(args))
128 sys.stdout.flush()
129 sys.stderr.flush()
130 start = time.monotonic()
131 result = subprocess.run(args)
132 elapsed = time.monotonic() - start
133 return result.returncode, elapsed
136def _run_docker_with_typeahead(args: list[str], typeahead: bytes) -> tuple[int, float]:
137 """Run docker exec under a PTY, pre-injecting typeahead bytes.
139 Used when the user typed during the slow startup phase: those bytes need to
140 be replayed into the inner process exactly as if they had been typed once
141 the shell attached. Standard subprocess inheritance can't do that because
142 we need to inject our own bytes ahead of the live stdin stream.
143 """
144 import pty
145 import select
146 import signal
147 import termios
148 import tty
150 logger.debug("run+pty: %s", " ".join(args))
151 sys.stdout.flush()
152 sys.stderr.flush()
154 master_fd, slave_fd = pty.openpty()
155 stdin_fd = sys.stdin.fileno()
156 stdout_fd = sys.stdout.fileno()
157 original_termios = termios.tcgetattr(stdin_fd)
159 # Match the PTY size to the host terminal so curses-based tools render correctly.
160 try:
161 import fcntl
163 size = fcntl.ioctl(stdout_fd, termios.TIOCGWINSZ, b"\x00" * 8)
164 fcntl.ioctl(slave_fd, termios.TIOCSWINSZ, size)
165 except OSError:
166 pass
168 def _on_winch(_signum: int, _frame: object) -> None:
169 try:
170 import fcntl
172 size = fcntl.ioctl(stdout_fd, termios.TIOCGWINSZ, b"\x00" * 8)
173 fcntl.ioctl(slave_fd, termios.TIOCSWINSZ, size)
174 except OSError:
175 pass
177 previous_winch = signal.signal(signal.SIGWINCH, _on_winch)
179 start = time.monotonic()
180 proc = subprocess.Popen(
181 args,
182 stdin=slave_fd,
183 stdout=slave_fd,
184 stderr=slave_fd,
185 close_fds=True,
186 )
187 os.close(slave_fd)
189 try:
190 tty.setraw(stdin_fd)
191 if typeahead:
192 os.write(master_fd, typeahead)
194 while True:
195 if proc.poll() is not None:
196 # Drain any final output.
197 try:
198 while True:
199 chunk = os.read(master_fd, 4096)
200 if not chunk:
201 break
202 os.write(stdout_fd, chunk)
203 except OSError:
204 pass
205 break
206 try:
207 ready, _, _ = select.select([master_fd, stdin_fd], [], [], 0.1)
208 except (OSError, ValueError):
209 break
210 if master_fd in ready:
211 try:
212 chunk = os.read(master_fd, 4096)
213 except OSError:
214 chunk = b""
215 if not chunk:
216 break
217 os.write(stdout_fd, chunk)
218 if stdin_fd in ready:
219 try:
220 chunk = os.read(stdin_fd, 4096)
221 except OSError:
222 chunk = b""
223 if chunk:
224 os.write(master_fd, chunk)
225 finally:
226 termios.tcsetattr(stdin_fd, termios.TCSADRAIN, original_termios)
227 signal.signal(signal.SIGWINCH, previous_winch)
228 try:
229 os.close(master_fd)
230 except OSError:
231 pass
232 if proc.poll() is None:
233 proc.wait()
235 elapsed = time.monotonic() - start
236 return proc.returncode, elapsed
239def published_host_port(manager: ContainerManager, name: str, container_port: int) -> int | None:
240 """Return the host port bound to *container_port* on *name*, or None if not published."""
241 ports = manager.container_ports(name) or {}
242 binding = ports.get(f"{container_port}/tcp", "")
243 if ":" not in binding:
244 return None
245 try:
246 return int(binding.rsplit(":", 1)[1])
247 except ValueError:
248 return None
251class ContainerManager:
252 """Manages Docker containers for ai-shell.
254 Handles the dev container (per-project) and LLM stack (host-level singletons).
255 """
257 def __init__(self, config: AiShellConfig) -> None:
258 self.config = config
259 try:
260 self.client = docker.from_env() # type: ignore[attr-defined]
261 self.client.ping()
262 except docker.errors.DockerException as e:
263 raise DockerNotAvailableError(
264 f"Docker is not available. Is the Docker daemon running?\n Error: {e}"
265 ) from e
267 # =========================================================================
268 # Dev container (per-project)
269 # =========================================================================
271 def resolve_dev_container(self) -> tuple[str, Container | None]:
272 """Resolve the dev container, checking both current and legacy names.
274 Returns ``(name, container)`` where *container* is ``None`` when no
275 matching container exists. When no container is found under either
276 name, the current hash-based name is returned so callers can use it
277 for creation.
278 """
279 name = dev_container_name(self.config.project_name, self.config.project_dir)
280 container = self._get_container(name)
281 if container is not None:
282 return name, container
284 legacy_name = dev_container_name(self.config.project_name)
285 legacy_container = self._get_container(legacy_name)
286 if legacy_container is not None and self._container_matches_project(
287 legacy_container, self.config.project_dir
288 ):
289 return legacy_name, legacy_container
291 return name, None
293 def _dev_config_digest(self) -> str:
294 """Return a stable SHA-256 hex digest of the dev container's mount/port config."""
295 from hashlib import sha256
297 payload = json.dumps(
298 {
299 "dev_ports": list(self.config.dev_ports),
300 "extra_volumes": sorted(self.config.extra_volumes),
301 "node_modules_paths": sorted(self.config.node_modules_paths),
302 "isolate_home_paths": sorted(self.config.isolate_home_paths),
303 },
304 sort_keys=True,
305 )
306 return sha256(payload.encode("utf-8")).hexdigest()[:16]
308 def _recreate_if_config_changed(self, container: Container, name: str) -> bool:
309 """Remove *container* when its recorded config digest differs from current config."""
310 labels = getattr(container, "labels", None)
311 if not isinstance(labels, dict):
312 return False
313 recorded = labels.get(DEV_CONFIG_LABEL)
314 if not recorded:
315 return False
316 if recorded == self._dev_config_digest():
317 return False
318 logger.warning(
319 "Dev container %s config changed (.ai-shell.yaml ports/mounts) — recreating",
320 name,
321 )
322 container.remove(force=True)
323 return True
325 def ensure_dev_container(self) -> str:
326 """Get or create the dev container for the current project.
328 If the container exists but is stopped, it is started.
329 If it doesn't exist, it is created with the full configuration.
330 If using the ``latest`` tag and a newer image is available, or if
331 the project's mount/port configuration changed, the existing container
332 is replaced automatically.
334 Returns the container name.
335 """
336 name, container = self.resolve_dev_container()
338 if container is not None:
339 if self._recreate_if_config_changed(container, name) or self._recreate_if_image_stale(
340 container, name
341 ):
342 # Container was removed; fall through to create a new one.
343 container = None
344 else:
345 if container.status != "running":
346 logger.info("Starting existing container: %s", name)
347 try:
348 container.start()
349 except APIError as e:
350 # A port-binding failure means the container's baked
351 # host ports conflict with the current host state
352 # (another container, a live listener, or a Windows
353 # winnat excluded range). Retrying the same bindings
354 # can never succeed — recreate so ports re-resolve
355 # against what the host will actually accept.
356 msg = str(e).lower()
357 if not any(s in msg for s in _PORT_BIND_ERRORS):
358 raise
359 logger.warning(
360 "Container %s failed to start due to a host port "
361 "conflict; recreating with fresh port assignments. "
362 "Error: %s",
363 name,
364 e,
365 )
366 container.remove(force=True)
367 container = None
368 if container is not None:
369 return name
371 logger.info("Creating dev container: %s", name)
372 self._pull_image_if_needed(self.config.full_image)
373 self._create_dev_container(name)
374 return name
376 def _create_dev_container(self, name: str) -> Container:
377 """Create the dev container with all docker-compose config."""
378 mounts = build_dev_mounts(
379 self.config.project_dir,
380 self.config.project_name,
381 extra_node_modules_paths=self.config.node_modules_paths,
382 isolate_home_paths=set(self.config.isolate_home_paths),
383 )
384 environment = build_dev_environment(
385 self.config.extra_env,
386 self.config.project_dir,
387 project_name=self.config.project_name,
388 aws_profile=self.config.ai_profile,
389 aws_region=self.config.aws_region,
390 )
392 port_map = project_dev_port_map(
393 self.config.project_dir,
394 self.config.dev_ports,
395 self.config.project_name,
396 is_available=_host_port_available,
397 )
399 # MOTD metadata — injected at creation time so the in-container
400 # motd.sh script can display version, container identity, and port
401 # mappings without querying Docker from inside the container.
402 from ai_shell import __version__
404 environment["AUGINT_SHELL_VERSION"] = __version__
405 environment["AUGINT_CONTAINER_NAME"] = name
406 environment["AUGINT_PROJECT_NAME"] = self.config.project_name
407 environment["AUGINT_DEV_PORTS"] = ",".join(
408 f"{port}:{host_port}" for port, host_port in sorted(port_map.items())
409 )
410 environment["AUGINT_LLM_PORTS"] = ",".join(
411 [
412 f"ollama:{self.config.ollama_port}",
413 f"webui:{self.config.webui_port}",
414 f"kokoro:{self.config.kokoro_port}",
415 f"whisper:{self.config.whisper_port}",
416 f"n8n:{self.config.n8n_port}",
417 f"comfyui:{self.config.comfyui_port}",
418 ]
419 )
421 # On hosts without a Unix socket (Windows), point the container's
422 # docker CLI at the daemon's tcp endpoint so Docker works out of the
423 # box instead of failing on the nonexistent default socket.
424 docker_host = docker_tcp_fallback_host()
425 if docker_host is not None:
426 environment["DOCKER_HOST"] = docker_host
428 # Add any extra volumes from config
429 for vol_spec in self.config.extra_volumes:
430 parts = vol_spec.split(":")
431 if len(parts) >= 2:
432 source, target = parts[0], parts[1]
433 read_only = len(parts) > 2 and parts[2] == "ro"
434 mounts.append(
435 Mount(
436 target=target,
437 source=source,
438 type="bind",
439 read_only=read_only,
440 )
441 )
443 container: Container = self.client.containers.run(
444 image=self.config.full_image,
445 name=name,
446 mounts=mounts,
447 environment=environment,
448 labels={DEV_CONFIG_LABEL: self._dev_config_digest()},
449 working_dir=f"/root/projects/{self.config.project_name}",
450 command="tail -f /dev/null",
451 stdin_open=True,
452 tty=True,
453 shm_size=SHM_SIZE,
454 init=True,
455 extra_hosts={"host.docker.internal": "host-gateway"},
456 ports={
457 f"{port}/tcp": (
458 ("0.0.0.0", host_port) # nosec B104
459 if self.config.project_dir
460 else None
461 )
462 for port, host_port in port_map.items()
463 },
464 detach=True,
465 )
466 logger.info("Container created: %s", name)
468 try:
469 self._write_container_context(container, name, port_map, mounts, docker_host)
470 except (APIError, OSError) as e:
471 logger.warning("Failed to write container context files: %s", e)
473 return container
475 def _write_container_context(
476 self,
477 container: Container,
478 name: str,
479 port_map: dict[int, int],
480 mounts: list[Mount],
481 docker_host: str | None,
482 ) -> None:
483 """Write container-local CLAUDE.md/AGENTS.md above the project mount.
485 Coding agents (Claude Code, codex, opencode) automatically load these
486 ancestor files into context, so environment facts — the port map,
487 Docker access, host gateway, bind mounts — are always visible to them
488 without relying on the (human-only) MOTD. ``/root/projects`` itself is
489 container-local, so the files never appear in the host project or its
490 repo.
491 """
492 import io
493 import platform
494 import tarfile
495 from importlib import resources
497 from ai_shell import __version__
499 template = (
500 resources.files("ai_shell.templates")
501 .joinpath("container", "context.md")
502 .read_text(encoding="utf-8")
503 )
505 port_rows = "\n".join(
506 f"| {port} | http://localhost:{host_port} |"
507 for port, host_port in sorted(port_map.items())
508 )
510 if docker_host is not None:
511 docker_section = (
512 f"The host Docker daemon is available; `DOCKER_HOST={docker_host}` is preset "
513 "in the environment, so `docker` commands work as-is. Containers you list or "
514 "start are siblings of this container, not children: volume paths you pass to "
515 "`docker run` are host paths, and published ports appear on the host."
516 )
517 elif any(m.get("Target") == "/var/run/docker.sock" for m in mounts):
518 docker_section = (
519 "The host Docker daemon is available via the mounted `/var/run/docker.sock`. "
520 "Containers you list or start are siblings of this container, not children: "
521 "volume paths you pass to `docker run` are host paths, and published ports "
522 "appear on the host."
523 )
524 else:
525 docker_section = "No Docker access is configured in this container."
527 llm_rows = "\n".join(
528 f"- {svc}: `host.docker.internal:{port}`"
529 for svc, port in (
530 ("ollama", self.config.ollama_port),
531 ("open-webui", self.config.webui_port),
532 ("kokoro TTS", self.config.kokoro_port),
533 ("whisper STT", self.config.whisper_port),
534 ("n8n", self.config.n8n_port),
535 ("comfyui", self.config.comfyui_port),
536 )
537 )
539 mount_rows = "\n".join(
540 f"- `{m.get('Target')}`{' (read-only)' if m.get('ReadOnly') else ''}"
541 for m in mounts
542 if m.get("Type") == "bind"
543 )
545 content = template.format(
546 version=__version__,
547 container_name=name,
548 project_name=self.config.project_name,
549 host_os=platform.system(),
550 port_rows=port_rows,
551 docker_section=docker_section,
552 llm_rows=llm_rows,
553 mount_rows=mount_rows,
554 )
556 data = content.encode("utf-8")
557 buf = io.BytesIO()
558 with tarfile.open(fileobj=buf, mode="w") as tar:
559 for fname in ("CLAUDE.md", "AGENTS.md"):
560 info = tarfile.TarInfo(name=fname)
561 info.size = len(data)
562 tar.addfile(info, io.BytesIO(data))
563 buf.seek(0)
564 container.put_archive("/root/projects", buf.getvalue())
566 def exec_interactive(
567 self,
568 container_name: str,
569 command: list[str],
570 extra_env: dict[str, str] | None = None,
571 workdir: str | None = None,
572 typeahead: bytes = b"",
573 ) -> NoReturn:
574 """Execute an interactive command in a container.
576 Uses subprocess.run for cross-platform TTY compatibility.
577 Detects whether stdin is a TTY to decide on -i/-t flags.
578 If *workdir* is given it is passed as ``-w`` to ``docker exec``.
579 When *typeahead* is non-empty and stdin is a TTY, runs the docker exec
580 under a PTY so the captured bytes can be replayed into the inner process.
581 """
582 args = ["docker", "exec"]
584 if sys.stdin.isatty():
585 args.append("-it")
587 if workdir:
588 args.extend(["-w", workdir])
590 if extra_env:
591 for key, value in extra_env.items():
592 args.extend(["-e", f"{key}={value}"])
594 args.append(container_name)
595 args.extend(command)
597 if typeahead and sys.platform != "win32" and sys.stdin.isatty():
598 exit_code, _ = _run_docker_with_typeahead(args, typeahead)
599 sys.exit(exit_code)
601 _exec_docker(args)
603 def run_interactive(
604 self,
605 container_name: str,
606 command: list[str],
607 extra_env: dict[str, str] | None = None,
608 workdir: str | None = None,
609 typeahead: bytes = b"",
610 ) -> tuple[int, float]:
611 """Execute an interactive command, returning (exit_code, elapsed_seconds).
613 Same as exec_interactive but does not call sys.exit().
614 Used for retry logic (e.g., claude -c fallback).
615 If *workdir* is given it is passed as ``-w`` to ``docker exec``.
616 When *typeahead* is non-empty and stdin is a TTY, runs the docker exec
617 under a PTY so the captured bytes can be replayed into the inner process.
618 """
619 args = ["docker", "exec"]
621 if sys.stdin.isatty():
622 args.append("-it")
624 if workdir:
625 args.extend(["-w", workdir])
627 if extra_env:
628 for key, value in extra_env.items():
629 args.extend(["-e", f"{key}={value}"])
631 args.append(container_name)
632 args.extend(command)
634 if typeahead and sys.platform != "win32" and sys.stdin.isatty():
635 return _run_docker_with_typeahead(args, typeahead)
637 return _run_docker(args)
639 def exec_detached(
640 self,
641 container_name: str,
642 command: list[str],
643 extra_env: dict[str, str] | None = None,
644 workdir: str | None = None,
645 ) -> subprocess.CompletedProcess[bytes]:
646 """Run a command in a container without waiting (docker exec -d)."""
647 args = ["docker", "exec", "-d"]
648 if workdir:
649 args.extend(["-w", workdir])
650 if extra_env:
651 for key, value in extra_env.items():
652 args.extend(["-e", f"{key}={value}"])
653 args.append(container_name)
654 args.extend(command)
655 logger.debug("exec-detached: %s", " ".join(args))
656 return subprocess.run(args, check=True)
658 @staticmethod
659 def exec_args(
660 container_name: str,
661 command: list[str],
662 extra_env: dict[str, str] | None = None,
663 workdir: str | None = None,
664 *,
665 stdin: bool = False,
666 ) -> list[str]:
667 """Build a ``docker exec`` argv without a TTY (``-i`` when *stdin* is piped)."""
668 args = ["docker", "exec"]
669 if stdin:
670 args.append("-i")
671 if workdir:
672 args.extend(["-w", workdir])
673 if extra_env:
674 for key, value in extra_env.items():
675 args.extend(["-e", f"{key}={value}"])
676 args.append(container_name)
677 args.extend(command)
678 return args
680 def exec_capture(
681 self,
682 container_name: str,
683 command: list[str],
684 extra_env: dict[str, str] | None = None,
685 workdir: str | None = None,
686 ) -> subprocess.CompletedProcess[str]:
687 """Run a non-interactive command in a container and capture its output."""
688 args = self.exec_args(container_name, command, extra_env, workdir)
689 logger.debug("exec-capture: %s", " ".join(args))
690 return subprocess.run(args, capture_output=True, text=True)
692 # =========================================================================
693 # LLM stack (host-level singletons)
694 # =========================================================================
696 @staticmethod
697 def _container_has_gpu(container: Container) -> bool:
698 """Return True if *container* was created with a GPU device request."""
699 device_requests = container.attrs.get("HostConfig", {}).get("DeviceRequests") or []
700 return any(
701 "gpu" in (cap for caps in (dr.get("Capabilities") or []) for cap in caps)
702 for dr in device_requests
703 )
705 def _recreate_if_gpu_changed(
706 self, container: Container, gpu_available: bool, label: str
707 ) -> bool:
708 """Remove *container* if its GPU state doesn't match *gpu_available*.
710 Returns True if the container was removed (caller must recreate).
711 """
712 has_gpu = self._container_has_gpu(container)
713 if has_gpu == gpu_available:
714 return False
715 want = "GPU" if gpu_available else "CPU-only"
716 had = "GPU" if has_gpu else "CPU-only"
717 logger.warning(
718 "%s container has %s but system now offers %s — recreating",
719 label,
720 had,
721 want,
722 )
723 container.remove(force=True)
724 return True
726 def _recreate_if_image_stale(self, container: Container, name: str) -> bool:
727 """Pull the latest image and recreate the container if it is outdated.
729 Only acts when the configured tag is ``latest``. For pinned
730 version tags the image is immutable so staleness doesn't apply.
732 The pull is skipped when ``config.image_pull_cache_ttl`` seconds have
733 not yet elapsed since the last successful pull (default 15 min) so
734 normal launches don't pay the network round-trip.
736 Returns True if the container was removed (caller must recreate).
737 """
738 from ai_shell.cache import is_fresh, mark_fresh
740 tag = self.config.image_tag
741 if tag != "latest":
742 return False
744 image_ref = self.config.full_image
745 if is_fresh("image-pull", image_ref, self.config.image_pull_cache_ttl):
746 logger.debug("Image-pull cache fresh for %s — skipping pull", image_ref)
747 return False
749 try:
750 pulled = self.client.images.pull(*image_ref.rsplit(":", 1))
751 except APIError:
752 logger.debug("Could not pull %s — skipping staleness check", image_ref)
753 return False
755 mark_fresh("image-pull", image_ref)
756 self._warn_if_image_below_minimum(pulled)
758 container_image_id = container.image.id
759 pulled_image_id = pulled.id
761 if container_image_id == pulled_image_id:
762 return False
764 logger.warning(
765 "Dev container %s uses an outdated image — recreating with %s",
766 name,
767 image_ref,
768 )
769 container.remove(force=True)
770 return True
772 @staticmethod
773 def _warn_if_image_below_minimum(image: Image) -> None:
774 """Log a warning if the pulled image version is below the CLI version."""
775 from ai_shell import __version__
777 labels = image.labels or {}
778 image_version_str = labels.get("org.opencontainers.image.version", "")
779 if not image_version_str:
780 return
782 def _parse_version(v: str) -> tuple[int, ...] | None:
783 try:
784 return tuple(int(x) for x in v.split("."))
785 except (ValueError, AttributeError):
786 return None
788 image_ver = _parse_version(image_version_str)
789 cli_ver = _parse_version(__version__)
790 if image_ver is None or cli_ver is None:
791 return
793 if image_ver < cli_ver:
794 logger.warning(
795 "Container image version %s is older than CLI version %s "
796 "— rebuild the image to get the latest tools",
797 image_version_str,
798 __version__,
799 )
801 def _ensure_llm_network(self) -> str:
802 """Get or create the shared Docker network for the LLM stack."""
803 try:
804 self.client.networks.get(LLM_NETWORK)
805 except NotFound:
806 logger.info("Creating LLM network: %s", LLM_NETWORK)
807 self.client.networks.create(LLM_NETWORK, driver="bridge")
808 return LLM_NETWORK
810 def ensure_ollama(self) -> str:
811 """Get or create the Ollama container with GPU auto-detection.
813 Recreates the container if GPU availability has changed since creation.
814 """
815 gpu_available = detect_gpu()
816 container = self._get_container(OLLAMA_CONTAINER)
818 if container is not None:
819 if self._recreate_if_gpu_changed(container, gpu_available, "Ollama"):
820 pass # fall through to creation
821 else:
822 if container.status != "running":
823 logger.info("Starting existing Ollama container")
824 container.start()
825 return OLLAMA_CONTAINER
827 logger.info("Creating Ollama container")
828 self._pull_image_if_needed(OLLAMA_IMAGE)
829 network_name = self._ensure_llm_network()
830 device_requests = None
831 env: dict[str, str] = {
832 "OLLAMA_CONTEXT_LENGTH": str(self.config.context_size),
833 # Flash attention trims activation memory at no quality cost and
834 # is a prerequisite for KV cache quantization.
835 "OLLAMA_FLASH_ATTENTION": "1",
836 # Quantize the KV cache to 8-bit; near-lossless, halves cache
837 # size. Combined with Ollama's dynamic GPU/CPU offload, this
838 # buys significant headroom for large models without hard-pinning
839 # a num_gpu value in any Modelfile.
840 "OLLAMA_KV_CACHE_TYPE": "q8_0",
841 }
842 if gpu_available:
843 device_requests = [DeviceRequest(count=1, capabilities=[["gpu"]])]
844 vram = get_vram_info()
845 if vram:
846 overhead = vram["used"] + OLLAMA_VRAM_BUFFER_BYTES
847 env["OLLAMA_GPU_OVERHEAD"] = str(overhead)
848 logger.info(
849 "VRAM: %.1f GiB total, %.1f GiB free. Reserving %.1f GiB overhead for Ollama.",
850 vram["total"] / 1024**3,
851 vram["free"] / 1024**3,
852 overhead / 1024**3,
853 )
854 else:
855 logger.info("GPU detected - Ollama will use NVIDIA GPU")
856 else:
857 logger.warning("No GPU detected - Ollama will run on CPU (slower inference)")
859 kwargs: dict = {
860 "image": OLLAMA_IMAGE,
861 "name": OLLAMA_CONTAINER,
862 "ports": {"11434/tcp": ("0.0.0.0", self.config.ollama_port)}, # nosec B104
863 "mounts": [
864 Mount(
865 target="/root/.ollama",
866 source=OLLAMA_DATA_VOLUME,
867 type="volume",
868 )
869 ],
870 "restart_policy": {"Name": "unless-stopped"},
871 "detach": True,
872 "network": network_name,
873 "cpu_shares": OLLAMA_CPU_SHARES,
874 }
876 if device_requests:
877 kwargs["device_requests"] = device_requests
878 if env:
879 kwargs["environment"] = env
881 self.client.containers.run(**kwargs)
882 logger.info("Ollama container created on port %d", self.config.ollama_port)
883 return OLLAMA_CONTAINER
885 def ensure_webui(
886 self,
887 voice_enabled: bool = False,
888 whisper_enabled: bool = False,
889 image_gen_enabled: bool = False,
890 env_file: Path | None = None,
891 ) -> str:
892 """Get or create the Open WebUI container.
894 When *voice_enabled* is True, pre-wires Kokoro TTS as the speech
895 backend. When *whisper_enabled* is True, pre-wires Speaches STT
896 as the transcription backend. When *image_gen_enabled* is True,
897 pre-wires ComfyUI as the image-generation backend. API keys from
898 *env_file* (or host environment) are passed through so WebUI can
899 offer external LLM providers alongside Ollama.
900 """
901 container = self._get_container(WEBUI_CONTAINER)
903 if container is not None:
904 if container.status != "running":
905 logger.info("Starting existing WebUI container")
906 container.start()
907 return WEBUI_CONTAINER
909 logger.info("Creating Open WebUI container")
910 self._pull_image_if_needed(WEBUI_IMAGE)
911 network_name = self._ensure_llm_network()
913 from dotenv import dotenv_values
915 from ai_shell.defaults import _resolve_env
917 dotenv: dict[str, str | None] = {}
918 if env_file is not None:
919 dotenv = dotenv_values(env_file)
921 environment: dict[str, str] = {
922 "OLLAMA_BASE_URL": f"http://{OLLAMA_CONTAINER}:11434",
923 "WEBUI_AUTH": "false",
924 # DEFAULT_MODELS is a PersistentConfig: env seeds the DB on first
925 # boot and UI edits win after that. Point new chats at the
926 # primary chat slot; users can pick the secondary (uncensored)
927 # from the model dropdown.
928 "DEFAULT_MODELS": self.config.primary_chat_model,
929 }
930 if voice_enabled:
931 environment.update(
932 {
933 "AUDIO_TTS_ENGINE": "openai",
934 "AUDIO_TTS_OPENAI_API_BASE_URL": f"http://{KOKORO_CONTAINER}:8880/v1",
935 "AUDIO_TTS_OPENAI_API_KEY": "dummy",
936 "AUDIO_TTS_MODEL": "kokoro",
937 "AUDIO_TTS_VOICE": self.config.kokoro_voice,
938 }
939 )
940 if whisper_enabled:
941 environment.update(
942 {
943 "AUDIO_STT_ENGINE": "openai",
944 "AUDIO_STT_OPENAI_API_BASE_URL": f"http://{WHISPER_CONTAINER}:8000/v1",
945 "AUDIO_STT_OPENAI_API_KEY": "dummy",
946 "AUDIO_STT_MODEL": self.config.whisper_model,
947 }
948 )
949 if image_gen_enabled:
950 # ENABLE_IMAGE_GENERATION + IMAGE_GENERATION_ENGINE=comfyui are
951 # PersistentConfig keys; they seed the DB on first boot. Users can
952 # later override the default workflow or model via Settings > Images.
953 environment.update(
954 {
955 "ENABLE_IMAGE_GENERATION": "true",
956 "IMAGE_GENERATION_ENGINE": "comfyui",
957 "COMFYUI_BASE_URL": f"http://{COMFYUI_CONTAINER}:8188",
958 "IMAGE_SIZE": "1024x1024",
959 "IMAGE_STEPS": "25",
960 }
961 )
963 # External LLM providers — pass through API keys when available.
964 openai_urls: list[str] = []
965 openai_keys: list[str] = []
967 openai_key = _resolve_env(dotenv, "OPENAI_API_KEY")
968 if openai_key:
969 openai_urls.append("https://api.openai.com/v1")
970 openai_keys.append(openai_key)
972 gh_token = _resolve_env(dotenv, "GH_TOKEN")
973 if gh_token:
974 openai_urls.append("https://models.inference.ai.azure.com/v1")
975 openai_keys.append(gh_token)
977 if openai_urls:
978 environment["OPENAI_API_BASE_URLS"] = ";".join(openai_urls)
979 environment["OPENAI_API_KEYS"] = ";".join(openai_keys)
981 anthropic_key = _resolve_env(dotenv, "ANTHROPIC_API_KEY")
982 if anthropic_key:
983 environment["ANTHROPIC_API_KEY"] = anthropic_key
985 self.client.containers.run(
986 image=WEBUI_IMAGE,
987 name=WEBUI_CONTAINER,
988 ports={"8080/tcp": ("0.0.0.0", self.config.webui_port)}, # nosec B104
989 environment=environment,
990 mounts=[
991 Mount(
992 target="/app/backend/data",
993 source=WEBUI_DATA_VOLUME,
994 type="volume",
995 )
996 ],
997 restart_policy={"Name": "unless-stopped"},
998 detach=True,
999 network=network_name,
1000 )
1002 logger.info("Open WebUI container created on port %d", self.config.webui_port)
1003 return WEBUI_CONTAINER
1005 def ensure_kokoro(self) -> str:
1006 """Get or create the Kokoro-FastAPI (local TTS) container.
1008 Exposes an OpenAI-compatible ``/v1/audio/speech`` endpoint on the
1009 configured port. GPU image is used when NVIDIA is detected;
1010 otherwise the CPU image. Recreates if GPU availability has changed.
1011 """
1012 gpu_available = detect_gpu()
1013 container = self._get_container(KOKORO_CONTAINER)
1014 if container is not None:
1015 if self._recreate_if_gpu_changed(container, gpu_available, "Kokoro"):
1016 pass # fall through to creation
1017 else:
1018 if container.status != "running":
1019 logger.info("Starting existing Kokoro container")
1020 container.start()
1021 return KOKORO_CONTAINER
1022 image = KOKORO_IMAGE_GPU if gpu_available else KOKORO_IMAGE_CPU
1023 logger.info("Creating Kokoro container (%s)", "GPU" if gpu_available else "CPU")
1024 self._pull_image_if_needed(image)
1025 network_name = self._ensure_llm_network()
1027 kwargs: dict = {
1028 "image": image,
1029 "name": KOKORO_CONTAINER,
1030 "ports": {"8880/tcp": ("0.0.0.0", self.config.kokoro_port)}, # nosec B104
1031 "restart_policy": {"Name": "unless-stopped"},
1032 "detach": True,
1033 "network": network_name,
1034 }
1035 if gpu_available:
1036 kwargs["device_requests"] = [DeviceRequest(count=1, capabilities=[["gpu"]])]
1038 self.client.containers.run(**kwargs)
1039 logger.info("Kokoro container created on port %d", self.config.kokoro_port)
1040 return KOKORO_CONTAINER
1042 def ensure_whisper(self) -> str:
1043 """Get or create the Speaches (local STT) container.
1045 Exposes an OpenAI-compatible ``/v1/audio/transcriptions`` endpoint on
1046 the configured port. GPU image is used when NVIDIA is detected;
1047 otherwise the CPU image. Recreates if GPU availability has changed.
1048 The Hugging Face model cache persists in a named volume (Speaches runs
1049 as ``ubuntu`` UID 1000 — a named volume inherits the correct ownership;
1050 bind-mounting a host dir here would require an explicit chown).
1051 """
1052 gpu_available = detect_gpu()
1053 container = self._get_container(WHISPER_CONTAINER)
1054 if container is not None:
1055 if self._recreate_if_gpu_changed(container, gpu_available, "Whisper"):
1056 pass # fall through to creation
1057 else:
1058 if container.status != "running":
1059 logger.info("Starting existing Whisper container")
1060 container.start()
1061 return WHISPER_CONTAINER
1062 image = WHISPER_IMAGE_GPU if gpu_available else WHISPER_IMAGE_CPU
1063 logger.info("Creating Whisper container (%s)", "GPU" if gpu_available else "CPU")
1064 self._pull_image_if_needed(image)
1065 network_name = self._ensure_llm_network()
1067 # PRELOAD_MODELS uses pydantic-settings JSON array syntax, not CSV.
1068 # json.dumps guarantees correct escaping for any model id.
1069 environment = {
1070 "WHISPER__INFERENCE_DEVICE": "auto",
1071 "PRELOAD_MODELS": json.dumps([self.config.whisper_model]),
1072 }
1074 kwargs: dict = {
1075 "image": image,
1076 "name": WHISPER_CONTAINER,
1077 "ports": {"8000/tcp": ("0.0.0.0", self.config.whisper_port)}, # nosec B104
1078 "environment": environment,
1079 "mounts": [
1080 Mount(
1081 target="/home/ubuntu/.cache/huggingface/hub",
1082 source=WHISPER_DATA_VOLUME,
1083 type="volume",
1084 )
1085 ],
1086 "restart_policy": {"Name": "unless-stopped"},
1087 "detach": True,
1088 "network": network_name,
1089 }
1090 if gpu_available:
1091 kwargs["device_requests"] = [DeviceRequest(count=1, capabilities=[["gpu"]])]
1093 self.client.containers.run(**kwargs)
1094 logger.info("Whisper container created on port %d", self.config.whisper_port)
1095 return WHISPER_CONTAINER
1097 def ensure_voice_agent(self) -> str:
1098 """Get or create the voice-agent container.
1100 The image is **built locally** from ``docker/voice-agent/`` on first
1101 call because Phase 2 doesn't publish it. Later phases may switch to
1102 a pulled tag. Phase 2 scope: no filesystem / auth / provider-key
1103 mounts — those land in Phases 3-4. A named volume is mounted at
1104 ``/data`` so the Phase 5 sqlite file will survive container
1105 recreations from the start. Service-discovery URLs for sibling
1106 stacks (ComfyUI, etc.) are exported so later phases can dispatch
1107 tool calls without re-reading config.
1108 """
1109 container = self._get_container(VOICE_AGENT_CONTAINER)
1110 if container is not None:
1111 if container.status != "running":
1112 logger.info("Starting existing voice-agent container")
1113 container.start()
1114 return VOICE_AGENT_CONTAINER
1116 logger.info("Creating voice-agent container")
1117 self._build_image_if_needed(VOICE_AGENT_IMAGE, self._voice_agent_build_context())
1118 network_name = self._ensure_llm_network()
1120 kwargs: dict = {
1121 "image": VOICE_AGENT_IMAGE,
1122 "name": VOICE_AGENT_CONTAINER,
1123 "ports": {"8000/tcp": ("0.0.0.0", self.config.voice_agent.port)}, # nosec B104
1124 "environment": {
1125 "COMFYUI_BASE_URL": f"http://{COMFYUI_CONTAINER}:8188",
1126 },
1127 "mounts": [
1128 Mount(
1129 target="/data",
1130 source=VOICE_AGENT_DATA_VOLUME,
1131 type="volume",
1132 )
1133 ],
1134 "restart_policy": {"Name": "unless-stopped"},
1135 "detach": True,
1136 "network": network_name,
1137 }
1139 self.client.containers.run(**kwargs)
1140 logger.info("voice-agent container created on port %d", self.config.voice_agent.port)
1141 return VOICE_AGENT_CONTAINER
1143 @staticmethod
1144 def _voice_agent_build_context() -> str:
1145 """Return the path to the voice-agent Dockerfile build context."""
1146 # Package layout: src/ai_shell/container.py — the Dockerfile lives in
1147 # <repo root>/docker/voice-agent. When installed as a wheel the user
1148 # is expected to have the source checked out; voice-agent is
1149 # experimental and locally built for now.
1150 here = Path(__file__).resolve()
1151 return str(here.parents[2] / "docker" / "voice-agent")
1153 def ensure_comfyui(self, env_file: Path | None = None) -> str:
1154 """Get or create the ComfyUI image-generation container.
1156 GPU-required (the ai-dock image has no CPU variant). On first
1157 boot, ai-dock runs the bind-mounted provisioning script which
1158 downloads SDXL unconditionally and FLUX.1-dev when ``HF_TOKEN``
1159 is present in *env_file* or the host environment. Model files
1160 persist in a named volume so subsequent containers start without
1161 re-downloading ~25 GB. Recreates the container when GPU
1162 availability toggles, matching the Kokoro/Whisper pattern.
1163 """
1164 from dotenv import dotenv_values
1166 gpu_available = detect_gpu()
1167 container = self._get_container(COMFYUI_CONTAINER)
1168 if container is not None:
1169 if self._recreate_if_gpu_changed(container, gpu_available, "ComfyUI"):
1170 pass # fall through to creation
1171 else:
1172 if container.status != "running":
1173 logger.info("Starting existing ComfyUI container")
1174 container.start()
1175 return COMFYUI_CONTAINER
1177 if not gpu_available:
1178 raise GpuRequiredError("ComfyUI")
1180 logger.info("Creating ComfyUI container")
1181 self._pull_image_if_needed(COMFYUI_IMAGE)
1182 network_name = self._ensure_llm_network()
1184 dotenv: dict[str, str | None] = {}
1185 if env_file is not None:
1186 dotenv = dotenv_values(env_file)
1188 hf_token = _resolve_env(dotenv, "HF_TOKEN") or _resolve_env(
1189 dotenv, "HUGGING_FACE_HUB_TOKEN"
1190 )
1192 environment: dict[str, str] = {
1193 # --lowvram keeps FLUX's 12B weights offloading through CPU RAM so
1194 # Ollama can keep a chat model resident on the same GPU. --listen
1195 # binds on 0.0.0.0 so other containers on the LLM network can reach
1196 # the API.
1197 "CLI_ARGS": "--lowvram --listen 0.0.0.0",
1198 # ai-dock runs PROVISIONING_SCRIPT once per workspace. We bind-mount
1199 # our own script at a known path rather than hosting one remotely.
1200 "PROVISIONING_SCRIPT": "/opt/augint/provision.sh",
1201 # Local-dev deployment: disable ai-dock's Caddy basic-auth layer so
1202 # the port-8188 service is reachable without redirect-to-/login.
1203 # Matches WEBUI_AUTH=false on Open WebUI.
1204 "WEB_ENABLE_AUTH": "false",
1205 "CF_QUICK_TUNNELS": "false",
1206 }
1207 if hf_token:
1208 # ai-dock's provisioner reads HF_TOKEN; upstream HF libs read
1209 # HUGGING_FACE_HUB_TOKEN. Set both to avoid edge cases.
1210 environment["HF_TOKEN"] = hf_token
1211 environment["HUGGING_FACE_HUB_TOKEN"] = hf_token
1213 from ai_shell.standalone import persistent_asset_path
1215 provision_path = persistent_asset_path(
1216 Path(__file__).parent / "assets" / "comfyui" / "provision.sh",
1217 "comfyui/provision.sh",
1218 )
1219 mounts: list[Mount] = [
1220 Mount(
1221 target="/opt/ComfyUI/models",
1222 source=COMFYUI_DATA_VOLUME,
1223 type="volume",
1224 )
1225 ]
1226 if provision_path.is_file():
1227 mounts.append(
1228 Mount(
1229 target="/opt/augint/provision.sh",
1230 source=str(provision_path),
1231 type="bind",
1232 read_only=True,
1233 )
1234 )
1236 kwargs: dict = {
1237 "image": COMFYUI_IMAGE,
1238 "name": COMFYUI_CONTAINER,
1239 "ports": {"8188/tcp": ("0.0.0.0", self.config.comfyui_port)}, # nosec B104
1240 "environment": environment,
1241 "mounts": mounts,
1242 "restart_policy": {"Name": "unless-stopped"},
1243 "detach": True,
1244 "network": network_name,
1245 "device_requests": [DeviceRequest(count=1, capabilities=[["gpu"]])],
1246 }
1248 self.client.containers.run(**kwargs)
1249 logger.info("ComfyUI container created on port %d", self.config.comfyui_port)
1250 return COMFYUI_CONTAINER
1252 def ensure_n8n(self, env_file: Path | None = None) -> str:
1253 """Get or create the n8n workflow automation container.
1255 Pre-wires service discovery URLs (Ollama, Kokoro, Speaches,
1256 Voice Agent, WebUI) and passes through API keys (OpenAI,
1257 Anthropic, GitHub, AWS) from *env_file* or the host environment.
1258 Credential directories (``~/.aws``, ``~/.config/gh``) are mounted
1259 read-only so n8n's AWS and GitHub nodes authenticate automatically.
1260 """
1261 container = self._get_container(N8N_CONTAINER)
1263 if container is not None:
1264 if container.status != "running":
1265 logger.info("Starting existing n8n container")
1266 container.start()
1267 return N8N_CONTAINER
1269 logger.info("Creating n8n container")
1270 self._pull_image_if_needed(N8N_IMAGE)
1271 network_name = self._ensure_llm_network()
1273 environment = build_n8n_environment(
1274 env_file=env_file,
1275 aws_profile=self.config.ai_profile,
1276 aws_region=self.config.aws_region,
1277 )
1279 from ai_shell.standalone import persistent_asset_path
1281 workflow_dir = persistent_asset_path(
1282 Path(__file__).parent / "templates" / "n8n" / "workflows",
1283 "n8n/workflows",
1284 )
1285 mounts = build_n8n_mounts(
1286 workflow_dir=workflow_dir if workflow_dir.is_dir() else None,
1287 )
1289 created = True
1290 self.client.containers.run(
1291 image=N8N_IMAGE,
1292 name=N8N_CONTAINER,
1293 ports={"5678/tcp": ("0.0.0.0", self.config.n8n_port)}, # nosec B104
1294 environment=environment,
1295 mounts=mounts,
1296 restart_policy={"Name": "unless-stopped"},
1297 detach=True,
1298 network=network_name,
1299 )
1301 logger.info("n8n container created on port %d", self.config.n8n_port)
1303 if created and workflow_dir.is_dir():
1304 self._seed_n8n_workflows()
1306 return N8N_CONTAINER
1308 def _seed_n8n_workflows(self) -> None:
1309 """Import starter workflow templates into a freshly-created n8n.
1311 Workflows are mounted at ``/workflows`` inside the container. We
1312 wait for n8n to be ready, then use ``n8n import:workflow`` to load
1313 each JSON file. Failures are logged but never fatal.
1314 """
1315 container = self._get_container(N8N_CONTAINER)
1316 if container is None:
1317 return
1319 # Wait for n8n to become ready (max ~30 s).
1320 for _i in range(15):
1321 try:
1322 exit_code, _ = container.exec_run("curl -sf http://localhost:5678/healthz")
1323 if exit_code == 0:
1324 break
1325 except Exception:
1326 pass
1327 time.sleep(2)
1328 else:
1329 logger.warning("n8n did not become healthy in 30 s; skipping workflow seed")
1330 return
1332 # Check for the seed marker to avoid duplicate imports.
1333 exit_code, _ = container.exec_run("test -f /home/node/.n8n/.workflows-seeded")
1334 if exit_code == 0:
1335 logger.debug("n8n workflows already seeded; skipping")
1336 return
1338 # Import each workflow template.
1339 exit_code, output = container.exec_run("ls /workflows/")
1340 if exit_code != 0:
1341 logger.debug("No /workflows directory in n8n container")
1342 return
1344 for line in output.decode().strip().splitlines():
1345 fname = line.strip()
1346 if not fname.endswith(".json"):
1347 continue
1348 logger.info("Importing n8n workflow: %s", fname)
1349 exit_code, out = container.exec_run(f"n8n import:workflow --input=/workflows/{fname}")
1350 if exit_code != 0:
1351 logger.warning("Failed to import %s: %s", fname, out.decode())
1353 # Write seed marker so we don't re-import on next restart.
1354 container.exec_run("touch /home/node/.n8n/.workflows-seeded")
1356 def exec_in_ollama(self, command: list[str]) -> str:
1357 """Run a command in the Ollama container and return stdout.
1359 Used for: ollama pull, ollama list, ollama create.
1360 """
1361 container = self._get_container(OLLAMA_CONTAINER)
1362 if container is None or container.status != "running":
1363 raise ContainerNotFoundError(OLLAMA_CONTAINER)
1365 exit_code, output = container.exec_run(
1366 cmd=command,
1367 stdout=True,
1368 stderr=True,
1369 )
1370 decoded: str = output.decode("utf-8", errors="replace")
1371 if exit_code != 0:
1372 logger.error("Command failed in ollama: %s\n%s", " ".join(command), decoded)
1373 return decoded
1375 # =========================================================================
1376 # Container lifecycle
1377 # =========================================================================
1379 def stop_container(self, name: str) -> None:
1380 """Stop a container by name."""
1381 container = self._get_container(name)
1382 if container is None:
1383 raise ContainerNotFoundError(name)
1384 if container.status == "running":
1385 container.stop()
1386 logger.info("Stopped container: %s", name)
1388 def remove_container(self, name: str) -> None:
1389 """Remove a container by name, stopping it first if running."""
1390 container = self._get_container(name)
1391 if container is None:
1392 raise ContainerNotFoundError(name)
1393 if container.status == "running":
1394 container.stop()
1395 logger.info("Stopped container: %s", name)
1396 container.remove()
1397 logger.info("Removed container: %s", name)
1399 def remove_volume(self, name: str) -> bool:
1400 """Remove a named Docker volume.
1402 Returns True if a volume was removed, False if it did not exist.
1403 """
1404 try:
1405 volume = self.client.volumes.get(name)
1406 except NotFound:
1407 return False
1408 volume.remove()
1409 logger.info("Removed volume: %s", name)
1410 return True
1412 def remove_project_volumes(self) -> list[str]:
1413 """Remove per-project named volumes (node_modules, vendor, T3 data).
1415 Returns the list of volume names that existed and were removed.
1416 """
1417 candidates: list[str] = [
1418 node_modules_volume_name(self.config.project_name),
1419 vendor_volume_name(self.config.project_name),
1420 t3_home_volume_name(self.config.project_dir, self.config.project_name),
1421 ]
1422 # Also include any monorepo workspace node_modules volumes for this project.
1423 mounts = build_dev_mounts(
1424 self.config.project_dir,
1425 self.config.project_name,
1426 extra_node_modules_paths=self.config.node_modules_paths,
1427 )
1428 for m in mounts:
1429 source = str(m.get("Source", ""))
1430 if source.startswith(NODE_MODULES_VOLUME_PREFIX) and source not in candidates:
1431 candidates.append(source)
1433 removed: list[str] = []
1434 for vol_name in candidates:
1435 if self.remove_volume(vol_name):
1436 removed.append(vol_name)
1437 return removed
1439 def container_ports(self, name: str) -> dict[str, str] | None:
1440 """Get the port mappings for a container.
1442 Returns a dict mapping container ports (e.g. '3000/tcp') to host
1443 addresses (e.g. '0.0.0.0:49152'), or None if the container doesn't exist.
1444 """
1445 container = self._get_container(name)
1446 if container is None:
1447 return None
1448 container.reload()
1449 ports_data = container.attrs.get("NetworkSettings", {}).get("Ports") or {}
1450 result: dict[str, str] = {}
1451 for container_port, bindings in sorted(ports_data.items()):
1452 if bindings:
1453 binding = bindings[0]
1454 result[container_port] = f"{binding['HostIp']}:{binding['HostPort']}"
1455 return result
1457 def published_host_port(self, name: str, container_port: int) -> int | None:
1458 """Return the host port bound to *container_port*, or None if not published."""
1459 ports = self.container_ports(name) or {}
1460 binding = ports.get(f"{container_port}/tcp", "")
1461 if ":" not in binding:
1462 return None
1463 try:
1464 return int(binding.rsplit(":", 1)[1])
1465 except ValueError:
1466 return None
1468 def list_dev_containers(self) -> list[dict[str, str]]:
1469 """Return metadata for all existing ai-shell dev containers on this host."""
1470 containers = self.client.containers.list(all=True)
1471 items: list[dict[str, str]] = []
1472 prefix = f"{CONTAINER_PREFIX}-"
1473 for c in containers:
1474 c_name = getattr(c, "name", "") or ""
1475 if not (c_name.startswith(prefix) and c_name.endswith("-dev")):
1476 continue
1477 project_source = ""
1478 for mount in (getattr(c, "attrs", None) or {}).get("Mounts", []):
1479 target = mount.get("Destination") or mount.get("Target") or ""
1480 if target.startswith("/root/projects/") and target.count("/") == 3:
1481 project_source = str(mount.get("Source", ""))
1482 break
1483 items.append(
1484 {
1485 "name": c_name,
1486 "status": str(getattr(c, "status", "unknown")),
1487 "project_dir": project_source,
1488 }
1489 )
1490 return sorted(items, key=lambda item: item["name"])
1492 def container_status(self, name: str) -> str | None:
1493 """Get the status of a container, or None if it doesn't exist."""
1494 container = self._get_container(name)
1495 if container is None:
1496 return None
1497 return container.status # type: ignore[no-any-return]
1499 def container_logs(self, name: str, follow: bool = False, tail: int = 100) -> None:
1500 """Print container logs. If follow=True, streams via docker CLI."""
1501 if follow:
1502 # Use docker CLI for streaming
1503 args = ["docker", "logs", "-f", name]
1504 _exec_docker(args)
1505 else:
1506 container = self._get_container(name)
1507 if container is None:
1508 raise ContainerNotFoundError(name)
1509 logs = container.logs(tail=tail).decode("utf-8", errors="replace")
1510 print(logs)
1512 # =========================================================================
1513 # Internal helpers
1514 # =========================================================================
1516 def _get_container(self, name: str) -> Container | None:
1517 """Get a container by name, or None if it doesn't exist."""
1518 try:
1519 return self.client.containers.get(name)
1520 except NotFound:
1521 return None
1523 def _container_matches_project(self, container: Container, project_dir: Path) -> bool:
1524 """Check whether a container's project mount matches *project_dir*."""
1525 resolved_project_dir = str(project_dir.resolve())
1526 mounts = container.attrs.get("Mounts", [])
1527 for mount in mounts:
1528 if mount.get("Source") == resolved_project_dir:
1529 return True
1530 return False
1532 # AUTO-UPDATE: Pre-launch tool freshness check
1533 def ensure_tool_fresh(self, container_name: str, tool_name: str) -> None:
1534 """Check if a tool is stale and update it before launch.
1536 Runs ``update-tools.sh --check <tool>`` inside the container.
1537 If stale (exit code 1), runs ``--tool <tool>`` in the foreground
1538 (blocking) which also kicks off background updates for other tools.
1540 Silently does nothing if ``update-tools.sh`` is not present in the
1541 container (backward compatibility with older images), or if
1542 ``config.skip_updates`` is True (``--skip-updates`` flag).
1543 """
1544 if self.config.skip_updates:
1545 logger.debug("Skipping tool freshness check (--skip-updates)")
1546 return
1548 update_script = "/usr/local/bin/update-tools.sh"
1550 # Check if update script exists in the container
1551 check_exists = subprocess.run(
1552 ["docker", "exec", container_name, "test", "-x", update_script],
1553 capture_output=True,
1554 )
1555 if check_exists.returncode != 0:
1556 logger.debug(
1557 "update-tools.sh not found in %s, skipping freshness check",
1558 container_name,
1559 )
1560 return
1562 # Check freshness
1563 check_result = subprocess.run(
1564 ["docker", "exec", container_name, update_script, "--check", tool_name],
1565 capture_output=True,
1566 )
1567 if check_result.returncode == 0:
1568 logger.debug("Tool %s is fresh, skipping update", tool_name)
1569 return
1571 # Tool is stale — update it in foreground (--tool also backgrounds the rest)
1572 from rich.console import Console
1574 console = Console(stderr=True)
1575 with console.status(f"[bold]Updating {tool_name}...[/bold]", spinner="dots"):
1576 update_result = subprocess.run(
1577 ["docker", "exec", container_name, update_script, "--tool", tool_name],
1578 capture_output=True,
1579 text=True,
1580 timeout=300, # 5 minute timeout
1581 )
1582 if update_result.returncode == 0:
1583 console.print(f"[green]Updated {tool_name}[/green]")
1584 else:
1585 console.print(f"[yellow]Update for {tool_name} had issues, continuing anyway[/yellow]")
1586 logger.debug("Update stderr: %s", update_result.stderr)
1588 def _build_image_if_needed(self, image: str, context_path: str) -> None:
1589 """Build a Docker image locally if it isn't already present.
1591 Used for images we don't pull from a registry (experimental
1592 components shipped as a Dockerfile in this repo). The local tag
1593 is cached between runs; a rebuild requires removing the image
1594 first (``docker rmi <tag>``).
1595 """
1596 try:
1597 self.client.images.get(image)
1598 logger.debug("Image already built: %s", image)
1599 return
1600 except ImageNotFound:
1601 pass
1603 logger.info("Building image: %s from %s ...", image, context_path)
1604 try:
1605 self.client.images.build(path=context_path, tag=image, rm=True)
1606 logger.info("Image built: %s", image)
1607 except APIError as e:
1608 raise ImagePullError(image, f"build failed: {e}") from e
1610 def _pull_image_if_needed(self, image: str) -> None:
1611 """Pull a Docker image if not available locally.
1613 For the ``latest`` tag, always pull to ensure the freshest digest
1614 since the local cache may be stale. If the pull fails but a
1615 cached copy exists, falls back to the cached version with a
1616 warning.
1617 """
1618 tag = image.rsplit(":", 1)[-1] if ":" in image else "latest"
1620 # AUTO-UPDATE: Always pull 'latest' to get fresh images
1621 if tag != "latest":
1622 try:
1623 self.client.images.get(image)
1624 logger.debug("Image already available: %s", image)
1625 return
1626 except ImageNotFound:
1627 pass
1629 logger.info("Pulling image: %s (this may take a while)...", image)
1630 try:
1631 pulled = self.client.images.pull(*image.rsplit(":", 1))
1632 self._warn_if_image_below_minimum(pulled)
1633 logger.info("Image pulled: %s", image)
1634 except APIError as e:
1635 if tag == "latest":
1636 try:
1637 self.client.images.get(image)
1638 logger.warning("Failed to pull latest image, using cached version: %s", e)
1639 return
1640 except ImageNotFound:
1641 pass
1642 raise ImagePullError(image, str(e)) from e