URL Safety Restrictions for Remote Sources in claude-obsidian: A Complete Security Guide

To prevent accidental data leakage, claude-obsidian treats all external requests as remote egress and enforces strict URL safety rules including HTTPS-only endpoints, localhost blocking, and mandatory explicit user consent via the --allow-remote-ollama flag.

The AgriciDaniel/claude-obsidian repository implements a defense-in-depth strategy for URL safety restrictions for remote sources in claude-obsidian. Every external network request undergoes multiple validation layers to ensure that sensitive vault data cannot be exfiltrated to unauthorized endpoints without deliberate user approval.

HTTPS-Only Enforcement

Any remote source must use an absolute URL with the https scheme. The validation logic in claude_obsidian/ledgers.py (lines 531–542) explicitly rejects plain HTTP, protocol-relative URLs, or malformed strings before any network connection is attempted.

This check ensures that data transmitted outside the local vault benefits from TLS encryption. If you attempt to pass an insecure URL, the system raises a ValueError with the message that remote sources require an absolute HTTPS URL.

Localhost and Private Network Blocking

By default, claude-obsidian denies URLs that resolve to local addresses such as http://localhost:11434. The blocking logic resides in scripts/tiling-check.py (lines 544–562), which screens for loopback and private IP ranges during the URL validation phase.

This restriction prevents plugins or scripts from accidentally sending vault contents to a locally running service that the user did not intend to expose. Access to localhost Ollama instances requires an explicit opt-in flag rather than implicit trust.

Explicit Consent Architecture

Remote egress is governed by a contract-driven policy defined in claude_obsidian/contracts.py (line 476). The product contract specifies remote_egress: "explicit_consent", which runtime checks consult before allowing any external request.

At the CLI level, scripts/retrieve.py (line 244) implements this requirement through the --allow-remote-ollama flag. When present, this flag is forwarded to low-level helpers such as the rerank module, signaling that the user has deliberately approved remote communication. Without this flag, the system exits with a "remote Ollama default-deny" error.

Centralized URL Validation

The claude_obsidian/url_safety.py module centralizes all safety checks into a single validate_remote_url() function. This utility validates the URL scheme, ensures the path is absolute, and confirms the host is not local. If any test fails, the function raises a ValueError immediately, preventing the request from reaching the network stack.

Practical Implementation Examples

Rejecting Non-HTTPS URLs

from claude_obsidian.url_safety import validate_remote_url

# This raises ValueError: "remote sources require an absolute HTTPS URL"

validate_remote_url("http://example.com/data.json")

Enabling Localhost Ollama Access

# Without the flag → exit with error "remote Ollama default-deny"

claude-obsidian retrieve --model my-model

# With the explicit opt-in flag → request is permitted

claude-obsidian retrieve --model my-model --allow-remote-ollama

Using the Low-Level Rerank Helper

python -m claude_obsidian.rerank \
    --query "What is AI?" \
    --candidates candidates.json \
    --allow-remote-ollama   # ← enables remote OLLAMA_URL

Verifying the Contract Policy

from claude_obsidian.contracts import get_product_contract

contract = get_product_contract()
assert contract["privacy_defaults"]["remote_egress"] == "explicit_consent"

Summary

• HTTPS is mandatory: Absolute URLs must use the https scheme as enforced in claude_obsidian/ledgers.py.
• Localhost is blocked by default: Private addresses like localhost:11434 are rejected unless explicitly allowed via scripts/tiling-check.py logic.
• Explicit consent required: The --allow-remote-ollama flag and the contract-defined remote_egress: "explicit_consent" policy ensure users must deliberately approve remote egress.
• Centralized validation: All URL checks run through claude_obsidian/url_safety.py, raising ValueError for any violation before network access occurs.

Frequently Asked Questions

What happens if I try to use an HTTP URL instead of HTTPS?

The validate_remote_url() function in claude_obsidian/url_safety.py raises a ValueError stating that remote sources require an absolute HTTPS URL. This check occurs in claude_obsidian/ledgers.py (lines 531–542) before any network request is dispatched, ensuring unencrypted transmission is impossible.

How do I enable remote Ollama endpoints on localhost?

You must provide the --allow-remote-ollama flag when running CLI commands such as retrieve or rerank. This flag signals explicit consent as required by the contract policy in claude_obsidian/contracts.py, overriding the default localhost block implemented in scripts/tiling-check.py.

Where is the remote egress policy defined in the codebase?

The policy is codified in claude_obsidian/contracts.py (line 476) as remote_egress: "explicit_consent". This contract value is consulted by validation logic throughout the repository, ensuring the safety rules cannot be bypassed without modifying the contract itself.

Can the URL safety restrictions be bypassed or disabled?

No. The restrictions are enforced at multiple layers: the contract definition in contracts.py, the validation logic in url_safety.py, and the CLI argument parsing in scripts/retrieve.py. Because the contract-driven policy is checked at runtime, disabling the safety features requires changing the contract source code and rebuilding the package, not merely toggling a configuration option.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}