fix: Change Ollama default URL to host.docker.internal for Docker compatibility

[tazmon95]

Summary

• Changed default Ollama URL from localhost:11434 to host.docker.internal:11434
• This allows Docker containers to connect to Ollama running on the host machine
• Most users run Archon in Docker but Ollama as a local binary, making this a better default

Changes Made

• Updated backend Python services (provider_discovery_service.py, llm_provider_service.py, credential_service.py)
• Updated frontend React components (RAGSettings.tsx, OllamaConfigurationPanel.tsx)
• Updated database migration script (complete_setup.sql)
• Updated documentation (rag.mdx)

Why This Change?

The current default of localhost:11434 doesn't work when Archon runs in Docker and Ollama runs as a local binary on the host machine. Using host.docker.internal:11434 allows the Docker container to properly connect to the host's Ollama instance, which is the most common deployment scenario.

Test Plan

• Verify Archon in Docker can connect to host Ollama with the new default
• Verify users can still override the URL if needed
• Check that existing configurations are not affected

🤖 Generated with Claude Code

Summary by CodeRabbit

• Chores
  • Changed default Ollama base URLs from localhost to host.docker.internal across the UI, backend services, fallbacks, and provider discovery; updated settings UI placeholders and quick-setup defaults.
• Documentation
  • Updated RAG docs and quick-setup examples to use host.docker.internal:11434/v1 for Ollama.
• Tests
  • Updated tests and fixtures to expect the new Ollama base URL.

[coderabbitai]

Walkthrough

Default Ollama URLs and UI placeholders were switched from localhost to host.docker.internal across UI, backend services, docs, tests, and initial SQL seed text. No logic, control flow, or public API signatures changed.

Changes

Cohort / File(s)	Summary
UI settings placeholders archon-ui-main/src/components/settings/OllamaConfigurationPanel.tsx, archon-ui-main/src/components/settings/RAGSettings.tsx	Updated placeholders and default values from http://localhost:11434[/v1] to http://host.docker.internal:11434[/v1] for Ollama URL fields.
Backend service defaults python/src/server/services/credential_service.py, python/src/server/services/llm_provider_service.py, python/src/server/services/provider_discovery_service.py	Changed default Ollama base URL (and /v1 paths where applicable) to use host.docker.internal instead of localhost, affecting fallback and discovery defaults.
Tests python/tests/test_async_llm_provider_service.py	Updated test fixtures and assertions to expect http://host.docker.internal:11434/v1 for Ollama references.
Docs docs/docs/rag.mdx	Updated example LLM_BASE_URL to http://host.docker.internal:11434/v1.
DB seed text migration/complete_setup.sql	Adjusted example URL in initial archon_settings insert to host.docker.internal.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• Feature: Add Ollama embedding service and model selection functionality #560 — Also modifies Ollama default/base URLs and related UI/placeholders and server defaults, switching from localhost:11434 to host.docker.internal.

Suggested labels

enhancement

Suggested reviewers

• coleam00
• leex279
• Wirasm

Poem

I twitch my whiskers, hop in cheer,
Ports once local now appear near.
From localhost to Docker’s wall,
host.docker.internal answers the call.
A carrot toast to URLs made clear. 🥕

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title succinctly and accurately summarizes the primary change — switching the default Ollama URL to host.docker.internal to fix Docker connectivity — and uses a conventional "fix:" prefix appropriate for a bugfix. It is concise, directly related to the changes in backend, frontend, migrations, and docs, and avoids unnecessary detail or noise. This makes the intent clear to reviewers scanning history.
Description Check	✅ Passed	The PR description provides a clear Summary, enumerates the files changed under "Changes Made", explains the rationale in "Why This Change?", and gives a basic Test Plan, so it conveys the core intent and verification steps reviewers need. However it does not fully follow the repository template: it omits the "Type of Change" selection, the "Affected Services" checkboxes, the formal Testing checklist and concrete Test Evidence, and the general Checklist/Breaking Changes sections. Because the essential context and verification steps are present the description is mostly complete but missing those template-required fields.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

• 📝 Generate Docstrings

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/ollama-default-docker-address

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 2f486e5 and aaca437.

📒 Files selected for processing (1)

• archon-ui-main/src/components/settings/OllamaConfigurationPanel.tsx (2 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• archon-ui-main/src/components/settings/OllamaConfigurationPanel.tsx

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (5)

python/src/server/services/provider_discovery_service.py (1)

26-26: Defaulting to host.docker.internal:11434 is OK; document Linux caveat or add fallback.

On Linux, host.docker.internal may not resolve unless --add-host=host.docker.internal:host-gateway (or compose extra_hosts) is used. Consider:

• Doc note (recommended).
• Or code fallback to also try http://localhost:11434 when no explicit URL is set.

migration/complete_setup.sql (1)

29-31: Comment mismatch: “bcrypt hashed” vs actual Fernet encryption.

encrypted_value is annotated as “bcrypt hashed” but the server uses Fernet (symmetric) encryption. Update the column comment to avoid confusion.

-    encrypted_value TEXT,          -- For encrypted sensitive data (bcrypt hashed)
+    encrypted_value TEXT,          -- For encrypted sensitive data (Fernet-encrypted blob)

archon-ui-main/src/components/settings/OllamaConfigurationPanel.tsx (1)

688-691: Keep placeholders consistent: update “Add New Instance” URL.

The add-instance field still suggests http://localhost:11434. Align with the new default.

-              <Input
+              <Input
                 type="url"
-                placeholder="http://localhost:11434"
+                placeholder="http://host.docker.internal:11434"
                 value={newInstanceUrl}
                 onChange={(e) => setNewInstanceUrl(e.target.value)}
               />

python/src/server/services/llm_provider_service.py (1)

206-219: Broaden final fallback to handle non-Docker hosts.

If RAG settings can’t be read, consider checking an env var and then falling back to localhost before host.docker.internal.

-            return "http://host.docker.internal:11434/v1"
+            import os  # ensure available at module scope if not already
+            return os.getenv("LLM_BASE_URL", "http://localhost:11434/v1")

If os isn’t imported at top-level, add:

# at top of file
import os

docs/docs/rag.mdx (1)

320-326: Add a Linux note for host networking.

Many Linux setups need an explicit host mapping for host.docker.internal. Suggest adding a short tip:

> tip
> On Linux, if `host.docker.internal` doesn’t resolve from inside Docker, add this to docker run or compose:
> - docker run: `--add-host=host.docker.internal:host-gateway`
> - docker-compose: 
>   ```
>   extra_hosts:
>     - "host.docker.internal:host-gateway"
>   ```
> Alternatively, use the Docker bridge IP (often `http://172.17.0.1:11434/v1`).

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 035f90e and d4e80a9.

📒 Files selected for processing (7)

• archon-ui-main/src/components/settings/OllamaConfigurationPanel.tsx (1 hunks)
• archon-ui-main/src/components/settings/RAGSettings.tsx (4 hunks)
• docs/docs/rag.mdx (1 hunks)
• migration/complete_setup.sql (1 hunks)
• python/src/server/services/credential_service.py (1 hunks)
• python/src/server/services/llm_provider_service.py (1 hunks)
• python/src/server/services/provider_discovery_service.py (1 hunks)

🧰 Additional context used

📓 Path-based instructions (6)

python/src/server/**/*.py

📄 CodeRabbit inference engine (CLAUDE.md)

python/src/server/**/*.py: Never accept corrupted data in batch/continuation paths: skip failed items entirely (e.g., do not store zero embeddings, null FKs, or malformed JSON)
Use specific exception types; avoid catching bare Exception
Preserve full stack traces in logs (use exc_info=True with Python logging)
Never return None to indicate failure; raise an exception with details
Authentication/authorization failures must halt the operation and be clearly surfaced
Service startup, missing configuration, database connection, or critical dependency failures should crash fast with clear errors
During crawling/batch/background tasks and WebSocket events, continue processing other items but log failures with context
Include context (operation intent, relevant IDs/URLs/data) in error messages
Pydantic should raise on data corruption or validation errors; do not accept invalid inputs

Files:

• python/src/server/services/credential_service.py
• python/src/server/services/provider_discovery_service.py
• python/src/server/services/llm_provider_service.py

python/src/server/services/**/*.py

📄 CodeRabbit inference engine (CLAUDE.md)

python/src/server/services/**/*.py: For batch operations, report both success count and a detailed failure list
On external API calls, retry with exponential backoff and fail with a clear message after retries
Place business logic in service layer modules (API Route → Service → Database pattern)

Files:

• python/src/server/services/credential_service.py
• python/src/server/services/provider_discovery_service.py
• python/src/server/services/llm_provider_service.py

python/**/*.py

📄 CodeRabbit inference engine (CLAUDE.md)

python/**/*.py: Target Python 3.12 with a 120-character line length
Use Ruff for linting (errors, warnings, unused imports)

Files:

• python/src/server/services/credential_service.py
• python/src/server/services/provider_discovery_service.py
• python/src/server/services/llm_provider_service.py

python/src/**/*.py

📄 CodeRabbit inference engine (CLAUDE.md)

Use MyPy for type checking to ensure type safety

python/src/**/*.py: On service startup, missing configuration, DB connection failures, auth/authorization failures, critical dependency outages, or invalid/corrupting data: fail fast and bubble errors
For batch processing, background tasks, WebSocket events, optional features, and external API calls: continue processing but log errors (with retries/backoff for APIs)
Never accept or persist corrupted data; skip failed items entirely (e.g., zero embeddings, null FKs, malformed JSON)
Error messages must include operation context, IDs/URLs, use specific exception types, preserve full stack traces (logging with exc_info=True), and avoid returning None/null—raise exceptions instead; for batches report success counts and detailed failures
Backend code targets Python 3.12 and adheres to a 120 character line length
Use Ruff for linting (errors, warnings, unused imports) in backend code
Use Mypy for static type checking in backend code

Files:

• python/src/server/services/credential_service.py
• python/src/server/services/provider_discovery_service.py
• python/src/server/services/llm_provider_service.py

archon-ui-main/src/**/*.{ts,tsx}

📄 CodeRabbit inference engine (CLAUDE.md)

Disallow implicit any in TypeScript

archon-ui-main/src/**/*.{ts,tsx}: Frontend TypeScript must use strict mode with no implicit any
Use TanStack Query for all data fetching; avoid prop drilling
Use database values directly in the frontend; avoid mapping layers between BE and FE types

Files:

• archon-ui-main/src/components/settings/OllamaConfigurationPanel.tsx
• archon-ui-main/src/components/settings/RAGSettings.tsx

archon-ui-main/src/**/*.{ts,tsx,py}

📄 CodeRabbit inference engine (CLAUDE.md)

In code comments, avoid meta terms like SIMPLIFIED, ENHANCED, LEGACY, CHANGED, REMOVED; comment only on functionality and reasoning (do not mention beta/global rules)

Files:

• archon-ui-main/src/components/settings/OllamaConfigurationPanel.tsx
• archon-ui-main/src/components/settings/RAGSettings.tsx

🧬 Code graph analysis (1)

python/src/server/services/llm_provider_service.py (1)

python/src/server/services/credential_service.py (1)

• get_credentials_by_category (305-351)

🔇 Additional comments (4)

python/src/server/services/credential_service.py (1)

475-481: Ollama default now includes /v1; confirm cross-file consistency.

This returns "http://host.docker.internal:11434/v1" while discovery/health flows expect the raw Ollama base and strip /v1. It’s fine (they handle both), but please confirm no caller double-appends /v1 and that UI placeholders align with this choice.

migration/complete_setup.sql (1)

95-99: LLGM base URL example updated correctly.

Good alignment with Docker defaults.

archon-ui-main/src/components/settings/OllamaConfigurationPanel.tsx (1)

596-602: Placeholder switch to host.docker.internal looks good.

archon-ui-main/src/components/settings/RAGSettings.tsx (1)

61-69: Verify no remaining localhost:11434 placeholders

LGTM on switching defaults to host.docker.internal (/v1). Health checks strip /v1, so backend flow is unaffected.
Ripgrep returned "No files were searched" — re-run from the repo root and paste the output to confirm there are no lingering localhost placeholders:

rg -n -S "http://localhost:11434" -uu -g '!/node_modules/'
rg -n -S "localhost:11434" -uu -g '!/node_modules/'
rg -n -S "127.0.0.1:11434" -uu -g '!/node_modules/'

Also applies to: archon-ui-main/src/components/settings/RAGSettings.tsx lines 61-69 (also check 66-70, 932-940, 1678-1685, 1753-1758).