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

1"""Docker container lifecycle management. 

2 

3Replaces docker-compose.yml by using Docker SDK to create and manage containers 

4with the exact same configuration. 

5""" 

6 

7from __future__ import annotations 

8 

9import json 

10import logging 

11import os 

12import subprocess 

13import sys 

14import time 

15from pathlib import Path 

16from typing import TYPE_CHECKING, NoReturn 

17 

18from docker.errors import APIError, ImageNotFound, NotFound 

19from docker.types import DeviceRequest, Mount 

20 

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 

69 

70if TYPE_CHECKING: 

71 from docker.models.containers import Container 

72 from docker.models.images import Image 

73 

74 from ai_shell.config import AiShellConfig 

75 

76logger = logging.getLogger(__name__) 

77 

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" 

81 

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) 

90 

91 

92def _host_port_available(port: int) -> bool: 

93 """Check whether *port* can be bound on the host running ai-shell. 

94 

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 

100 

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 

107 

108 

109def _exec_docker(args: list[str]) -> NoReturn: 

110 """Execute a docker CLI command with cross-platform TTY support. 

111 

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) 

120 

121 

122def _run_docker(args: list[str]) -> tuple[int, float]: 

123 """Run a docker CLI command and return (exit_code, elapsed_seconds). 

124 

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 

134 

135 

136def _run_docker_with_typeahead(args: list[str], typeahead: bytes) -> tuple[int, float]: 

137 """Run docker exec under a PTY, pre-injecting typeahead bytes. 

138 

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 

149 

150 logger.debug("run+pty: %s", " ".join(args)) 

151 sys.stdout.flush() 

152 sys.stderr.flush() 

153 

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) 

158 

159 # Match the PTY size to the host terminal so curses-based tools render correctly. 

160 try: 

161 import fcntl 

162 

163 size = fcntl.ioctl(stdout_fd, termios.TIOCGWINSZ, b"\x00" * 8) 

164 fcntl.ioctl(slave_fd, termios.TIOCSWINSZ, size) 

165 except OSError: 

166 pass 

167 

168 def _on_winch(_signum: int, _frame: object) -> None: 

169 try: 

170 import fcntl 

171 

172 size = fcntl.ioctl(stdout_fd, termios.TIOCGWINSZ, b"\x00" * 8) 

173 fcntl.ioctl(slave_fd, termios.TIOCSWINSZ, size) 

174 except OSError: 

175 pass 

176 

177 previous_winch = signal.signal(signal.SIGWINCH, _on_winch) 

178 

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) 

188 

189 try: 

190 tty.setraw(stdin_fd) 

191 if typeahead: 

192 os.write(master_fd, typeahead) 

193 

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() 

234 

235 elapsed = time.monotonic() - start 

236 return proc.returncode, elapsed 

237 

238 

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 

249 

250 

251class ContainerManager: 

252 """Manages Docker containers for ai-shell. 

253 

254 Handles the dev container (per-project) and LLM stack (host-level singletons). 

255 """ 

256 

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 

266 

267 # ========================================================================= 

268 # Dev container (per-project) 

269 # ========================================================================= 

270 

271 def resolve_dev_container(self) -> tuple[str, Container | None]: 

272 """Resolve the dev container, checking both current and legacy names. 

273 

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 

283 

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 

290 

291 return name, None 

292 

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 

296 

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] 

307 

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 

324 

325 def ensure_dev_container(self) -> str: 

326 """Get or create the dev container for the current project. 

327 

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. 

333 

334 Returns the container name. 

335 """ 

336 name, container = self.resolve_dev_container() 

337 

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 

370 

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 

375 

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 ) 

391 

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 ) 

398 

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__ 

403 

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 ) 

420 

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 

427 

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 ) 

442 

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) 

467 

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) 

472 

473 return container 

474 

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. 

484 

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 

496 

497 from ai_shell import __version__ 

498 

499 template = ( 

500 resources.files("ai_shell.templates") 

501 .joinpath("container", "context.md") 

502 .read_text(encoding="utf-8") 

503 ) 

504 

505 port_rows = "\n".join( 

506 f"| {port} | http://localhost:{host_port} |" 

507 for port, host_port in sorted(port_map.items()) 

508 ) 

509 

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." 

526 

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 ) 

538 

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 ) 

544 

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 ) 

555 

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()) 

565 

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. 

575 

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"] 

583 

584 if sys.stdin.isatty(): 

585 args.append("-it") 

586 

587 if workdir: 

588 args.extend(["-w", workdir]) 

589 

590 if extra_env: 

591 for key, value in extra_env.items(): 

592 args.extend(["-e", f"{key}={value}"]) 

593 

594 args.append(container_name) 

595 args.extend(command) 

596 

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) 

600 

601 _exec_docker(args) 

602 

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). 

612 

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"] 

620 

621 if sys.stdin.isatty(): 

622 args.append("-it") 

623 

624 if workdir: 

625 args.extend(["-w", workdir]) 

626 

627 if extra_env: 

628 for key, value in extra_env.items(): 

629 args.extend(["-e", f"{key}={value}"]) 

630 

631 args.append(container_name) 

632 args.extend(command) 

633 

634 if typeahead and sys.platform != "win32" and sys.stdin.isatty(): 

635 return _run_docker_with_typeahead(args, typeahead) 

636 

637 return _run_docker(args) 

638 

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) 

657 

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 

679 

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) 

691 

692 # ========================================================================= 

693 # LLM stack (host-level singletons) 

694 # ========================================================================= 

695 

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 ) 

704 

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*. 

709 

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 

725 

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. 

728 

729 Only acts when the configured tag is ``latest``. For pinned 

730 version tags the image is immutable so staleness doesn't apply. 

731 

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. 

735 

736 Returns True if the container was removed (caller must recreate). 

737 """ 

738 from ai_shell.cache import is_fresh, mark_fresh 

739 

740 tag = self.config.image_tag 

741 if tag != "latest": 

742 return False 

743 

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 

748 

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 

754 

755 mark_fresh("image-pull", image_ref) 

756 self._warn_if_image_below_minimum(pulled) 

757 

758 container_image_id = container.image.id 

759 pulled_image_id = pulled.id 

760 

761 if container_image_id == pulled_image_id: 

762 return False 

763 

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 

771 

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__ 

776 

777 labels = image.labels or {} 

778 image_version_str = labels.get("org.opencontainers.image.version", "") 

779 if not image_version_str: 

780 return 

781 

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 

787 

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 

792 

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 ) 

800 

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 

809 

810 def ensure_ollama(self) -> str: 

811 """Get or create the Ollama container with GPU auto-detection. 

812 

813 Recreates the container if GPU availability has changed since creation. 

814 """ 

815 gpu_available = detect_gpu() 

816 container = self._get_container(OLLAMA_CONTAINER) 

817 

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 

826 

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)") 

858 

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 } 

875 

876 if device_requests: 

877 kwargs["device_requests"] = device_requests 

878 if env: 

879 kwargs["environment"] = env 

880 

881 self.client.containers.run(**kwargs) 

882 logger.info("Ollama container created on port %d", self.config.ollama_port) 

883 return OLLAMA_CONTAINER 

884 

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. 

893 

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) 

902 

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 

908 

909 logger.info("Creating Open WebUI container") 

910 self._pull_image_if_needed(WEBUI_IMAGE) 

911 network_name = self._ensure_llm_network() 

912 

913 from dotenv import dotenv_values 

914 

915 from ai_shell.defaults import _resolve_env 

916 

917 dotenv: dict[str, str | None] = {} 

918 if env_file is not None: 

919 dotenv = dotenv_values(env_file) 

920 

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 ) 

962 

963 # External LLM providers — pass through API keys when available. 

964 openai_urls: list[str] = [] 

965 openai_keys: list[str] = [] 

966 

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) 

971 

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) 

976 

977 if openai_urls: 

978 environment["OPENAI_API_BASE_URLS"] = ";".join(openai_urls) 

979 environment["OPENAI_API_KEYS"] = ";".join(openai_keys) 

980 

981 anthropic_key = _resolve_env(dotenv, "ANTHROPIC_API_KEY") 

982 if anthropic_key: 

983 environment["ANTHROPIC_API_KEY"] = anthropic_key 

984 

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 ) 

1001 

1002 logger.info("Open WebUI container created on port %d", self.config.webui_port) 

1003 return WEBUI_CONTAINER 

1004 

1005 def ensure_kokoro(self) -> str: 

1006 """Get or create the Kokoro-FastAPI (local TTS) container. 

1007 

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() 

1026 

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"]])] 

1037 

1038 self.client.containers.run(**kwargs) 

1039 logger.info("Kokoro container created on port %d", self.config.kokoro_port) 

1040 return KOKORO_CONTAINER 

1041 

1042 def ensure_whisper(self) -> str: 

1043 """Get or create the Speaches (local STT) container. 

1044 

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() 

1066 

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 } 

1073 

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"]])] 

1092 

1093 self.client.containers.run(**kwargs) 

1094 logger.info("Whisper container created on port %d", self.config.whisper_port) 

1095 return WHISPER_CONTAINER 

1096 

1097 def ensure_voice_agent(self) -> str: 

1098 """Get or create the voice-agent container. 

1099 

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 

1115 

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() 

1119 

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 } 

1138 

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 

1142 

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") 

1152 

1153 def ensure_comfyui(self, env_file: Path | None = None) -> str: 

1154 """Get or create the ComfyUI image-generation container. 

1155 

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 

1165 

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 

1176 

1177 if not gpu_available: 

1178 raise GpuRequiredError("ComfyUI") 

1179 

1180 logger.info("Creating ComfyUI container") 

1181 self._pull_image_if_needed(COMFYUI_IMAGE) 

1182 network_name = self._ensure_llm_network() 

1183 

1184 dotenv: dict[str, str | None] = {} 

1185 if env_file is not None: 

1186 dotenv = dotenv_values(env_file) 

1187 

1188 hf_token = _resolve_env(dotenv, "HF_TOKEN") or _resolve_env( 

1189 dotenv, "HUGGING_FACE_HUB_TOKEN" 

1190 ) 

1191 

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 

1212 

1213 from ai_shell.standalone import persistent_asset_path 

1214 

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 ) 

1235 

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 } 

1247 

1248 self.client.containers.run(**kwargs) 

1249 logger.info("ComfyUI container created on port %d", self.config.comfyui_port) 

1250 return COMFYUI_CONTAINER 

1251 

1252 def ensure_n8n(self, env_file: Path | None = None) -> str: 

1253 """Get or create the n8n workflow automation container. 

1254 

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) 

1262 

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 

1268 

1269 logger.info("Creating n8n container") 

1270 self._pull_image_if_needed(N8N_IMAGE) 

1271 network_name = self._ensure_llm_network() 

1272 

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 ) 

1278 

1279 from ai_shell.standalone import persistent_asset_path 

1280 

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 ) 

1288 

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 ) 

1300 

1301 logger.info("n8n container created on port %d", self.config.n8n_port) 

1302 

1303 if created and workflow_dir.is_dir(): 

1304 self._seed_n8n_workflows() 

1305 

1306 return N8N_CONTAINER 

1307 

1308 def _seed_n8n_workflows(self) -> None: 

1309 """Import starter workflow templates into a freshly-created n8n. 

1310 

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 

1318 

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 

1331 

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 

1337 

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 

1343 

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()) 

1352 

1353 # Write seed marker so we don't re-import on next restart. 

1354 container.exec_run("touch /home/node/.n8n/.workflows-seeded") 

1355 

1356 def exec_in_ollama(self, command: list[str]) -> str: 

1357 """Run a command in the Ollama container and return stdout. 

1358 

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) 

1364 

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 

1374 

1375 # ========================================================================= 

1376 # Container lifecycle 

1377 # ========================================================================= 

1378 

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) 

1387 

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) 

1398 

1399 def remove_volume(self, name: str) -> bool: 

1400 """Remove a named Docker volume. 

1401 

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 

1411 

1412 def remove_project_volumes(self) -> list[str]: 

1413 """Remove per-project named volumes (node_modules, vendor, T3 data). 

1414 

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) 

1432 

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 

1438 

1439 def container_ports(self, name: str) -> dict[str, str] | None: 

1440 """Get the port mappings for a container. 

1441 

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 

1456 

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 

1467 

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"]) 

1491 

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] 

1498 

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) 

1511 

1512 # ========================================================================= 

1513 # Internal helpers 

1514 # ========================================================================= 

1515 

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 

1522 

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 

1531 

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. 

1535 

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. 

1539 

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 

1547 

1548 update_script = "/usr/local/bin/update-tools.sh" 

1549 

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 

1561 

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 

1570 

1571 # Tool is stale — update it in foreground (--tool also backgrounds the rest) 

1572 from rich.console import Console 

1573 

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) 

1587 

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. 

1590 

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 

1602 

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 

1609 

1610 def _pull_image_if_needed(self, image: str) -> None: 

1611 """Pull a Docker image if not available locally. 

1612 

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" 

1619 

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 

1628 

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