diff --git a/osa/application/di.py b/osa/application/di.py
index 4fb5eec..cdd63b3 100644
--- a/osa/application/di.py
+++ b/osa/application/di.py
@@ -1,5 +1,6 @@
 from dishka import AsyncContainer, make_async_container
 
+from osa.cli.util.paths import OSAPaths
 from osa.config import Config
 from osa.domain.deposition.util.di import DepositionProvider
 from osa.domain.validation.util.di import ValidationProvider
@@ -14,6 +15,9 @@
 def create_container() -> AsyncContainer:
     config = Config()
 
+    # OSAPaths reads OSA_DATA_DIR from environment automatically
+    paths = OSAPaths()
+
     return make_async_container(
         PersistenceProvider(),
         OciProvider(),
@@ -22,6 +26,6 @@ def create_container() -> AsyncContainer:
         EventProvider(),
         DepositionProvider(),
         ValidationProvider(),
-        context={Config: config},
+        context={Config: config, OSAPaths: paths},
         scopes=Scope,  # type: ignore[arg-type]  # Custom scope class
     )
diff --git a/osa/cli/commands/admin.py b/osa/cli/commands/admin.py
index e9c5d60..332f48d 100644
--- a/osa/cli/commands/admin.py
+++ b/osa/cli/commands/admin.py
@@ -1,103 +1,15 @@
 """Administrative commands for OSA management."""
 
-import shutil
-import sys
 from pathlib import Path
 
 import cyclopts
 
 from osa.cli.console import get_console
-from osa.cli.util import DaemonManager, OSAPaths, ServerStatus
+from osa.cli.util import OSAPaths, read_server_state
 
 app = cyclopts.App(name="admin", help="Administrative commands")
 
 
-@app.command
-def clean(
-    force: bool = False,
-    keep_config: bool = False,
-    keep_logs: bool = False,
-) -> None:
-    """Wipe OSA data directories to start fresh.
-
-    Stops the server if running, then removes:
-    - ~/.local/share/osa/ (database, vectors)
-    - ~/.local/state/osa/ (server state, logs)
-    - ~/.cache/osa/ (search cache)
-    - ~/.config/osa/ (unless --keep-config)
-
-    Args:
-        force: Skip confirmation prompt.
-        keep_config: Keep the config directory (~/.config/osa).
-        keep_logs: Keep the logs directory.
-    """
-    console = get_console()
-    paths = OSAPaths()
-
-    # Check which directories exist
-    dirs_to_clean: list[tuple[str, Path]] = []
-    if paths.data_dir.exists():
-        dirs_to_clean.append(("Data", paths.data_dir))
-    if paths.state_dir.exists():
-        dirs_to_clean.append(("State", paths.state_dir))
-    if paths.cache_dir.exists():
-        dirs_to_clean.append(("Cache", paths.cache_dir))
-    if paths.config_dir.exists() and not keep_config:
-        dirs_to_clean.append(("Config", paths.config_dir))
-
-    if not dirs_to_clean:
-        console.info("Nothing to clean - no OSA directories exist")
-        return
-
-    # Check if server is running
-    daemon = DaemonManager()
-    status_info = daemon.status()
-
-    if status_info.status == ServerStatus.RUNNING:
-        if not force:
-            console.warning(f"Server is running (PID {status_info.pid})")
-            response = input("Stop server and clean? [y/N] ").strip().lower()
-            if response != "y":
-                console.info("Aborted")
-                sys.exit(1)
-        console.info("Stopping server...")
-        daemon.stop()
-
-    # Confirm before wiping
-    if not force:
-        console.print("[bold]This will delete:[/bold]")
-        for name, path in dirs_to_clean:
-            console.print(f"  [cyan]{path}[/cyan]  [dim]({name.lower()})[/dim]")
-        if keep_logs:
-            console.print(f"  [dim](keeping logs at {paths.logs_dir})[/dim]")
-        if keep_config and paths.config_dir.exists():
-            console.print(f"  [dim](keeping config at {paths.config_dir})[/dim]")
-        console.print()
-        response = input("Are you sure? [y/N] ").strip().lower()
-        if response != "y":
-            console.info("Aborted")
-            sys.exit(1)
-
-    # Perform cleanup
-    for name, path in dirs_to_clean:
-        if name == "State" and keep_logs:
-            # Delete everything in state except logs
-            for item in path.iterdir():
-                if item == paths.logs_dir:
-                    continue
-                if item.is_dir():
-                    shutil.rmtree(item)
-                else:
-                    item.unlink()
-            console.success(f"Cleaned {path} (logs preserved)")
-        else:
-            shutil.rmtree(path)
-            console.success(f"Removed {path}")
-
-    console.print()
-    console.info("Run 'osa init' to set up OSA again")
-
-
 @app.command
 def info() -> None:
     """Show information about OSA directories and status."""
@@ -147,7 +59,7 @@ def exists_marker(path: Path) -> str:
 
     # Server status
     console.print()
-    state = paths.read_server_state()
+    state = read_server_state(paths.server_state_file)
     if state:
         from osa.cli.console import relative_time
 
diff --git a/osa/cli/commands/init.py b/osa/cli/commands/init.py
deleted file mode 100644
index f814da5..0000000
--- a/osa/cli/commands/init.py
+++ /dev/null
@@ -1,143 +0,0 @@
-"""Initialize OSA configuration and directories."""
-
-import sys
-from typing import Literal
-
-import cyclopts
-
-from osa.cli.console import get_console
-from osa.cli.util import OSAPaths
-
-app = cyclopts.App(name="init", help="Initialize OSA with a template")
-
-# Available templates
-Template = Literal["geo", "minimal"]
-TEMPLATES: list[Template] = ["geo", "minimal"]
-
-GEO_TEMPLATE = """\
-# OSA Configuration - GEO Template
-
-server:
-  name: "My OSA Node"
-  domain: "localhost"
-
-# Database (SQLite by default, stored in ~/.local/share/osa/)
-# database:
-#   auto_migrate: true
-
-# Logging
-# logging:
-#   level: "INFO"
-
-# GEO Ingestor - pulls from NCBI Gene Expression Omnibus via Entrez API
-ingestors:
-  - ingestor: geo-entrez
-    config:
-      record_type: gse  # gse (~250k all) or gds (~5k curated)
-      email: your@email.com  # Required by NCBI - please update this
-      # api_key: null  # Optional: NCBI API key for higher rate limits (https://account.ncbi.nlm.nih.gov/settings/)
-    initial_run:
-      enabled: true
-      limit: 50
-    # schedule:
-    #   cron: "0 * * * *"  # Hourly
-    #   limit: 100
-
-# Vector search index
-indexes:
-  - name: vector
-    backend: vector
-    config:
-      persist_dir: {vectors_dir}
-      embedding:
-        model: all-MiniLM-L6-v2
-        fields: [title, summary, organism, platform, entry_type]
-"""
-
-MINIMAL_TEMPLATE = """\
-# OSA Configuration
-
-server:
-  name: "My OSA Node"
-  domain: "localhost"
-
-# Database (SQLite by default, stored in ~/.local/share/osa/)
-# database:
-#   auto_migrate: true
-
-# Logging
-# logging:
-#   level: "INFO"
-
-# Add your ingestors here:
-# ingestors:
-#   - ingestor: geo-entrez
-#     config:
-#       email: your@email.com
-
-# Add your indexes here:
-# indexes:
-#   - name: my-index
-#     backend: vector
-#     config:
-#       persist_dir: {vectors_dir}
-"""
-
-
-@app.default
-def init(
-    template: Template | None = None,
-    /,
-    force: bool = False,
-) -> None:
-    """Initialize OSA configuration and directories.
-
-    Creates the config file and directory structure needed to run OSA.
-
-    Args:
-        template: Template to use (geo, minimal).
-        force: Overwrite existing configuration.
-    """
-    console = get_console()
-    paths = OSAPaths()
-
-    # If no template specified, show available options
-    if template is None:
-        console.print("[bold]Available templates:[/bold]\n")
-        console.print("  [cyan]geo[/cyan]      NCBI GEO integration with vector search")
-        console.print("  [cyan]minimal[/cyan]  Blank configuration to customize")
-        console.print()
-        console.print("Usage: [bold]osa init <template>[/bold]")
-        console.print()
-        console.print("Example: [dim]osa init geo[/dim]")
-        sys.exit(0)
-
-    # Check if already initialized
-    if paths.is_initialized() and not force:
-        console.warning("OSA is already initialized")
-        console.print(f"  [dim]Config:[/dim] {paths.config_file}")
-        console.info("Use --force to reinitialize")
-        sys.exit(0)
-
-    # Generate config content
-    if template == "geo":
-        config_content = GEO_TEMPLATE.format(vectors_dir=paths.vectors_dir)
-    else:  # minimal
-        config_content = MINIMAL_TEMPLATE.format(vectors_dir=paths.vectors_dir)
-
-    # Create directories
-    paths.ensure_directories()
-
-    # Write config file
-    paths.config_file.write_text(config_content)
-
-    # Show results
-    console.success(f"Initialized OSA with '{template}' template")
-    console.print()
-    console.print(f"  [cyan]Config:[/cyan]  {paths.config_file}")
-    console.print(f"  [cyan]Data:[/cyan]    {paths.data_dir}/")
-    console.print(f"  [cyan]State:[/cyan]   {paths.state_dir}/")
-    console.print(f"  [cyan]Cache:[/cyan]   {paths.cache_dir}/")
-    console.print()
-    console.print(f"Edit your config: [bold]{paths.config_file}[/bold]")
-    console.print("Then run: [bold]osa server start[/bold]")
diff --git a/osa/cli/commands/local.py b/osa/cli/commands/local.py
new file mode 100644
index 0000000..80dc013
--- /dev/null
+++ b/osa/cli/commands/local.py
@@ -0,0 +1,436 @@
+"""Local development server commands (start/stop/logs/status/clean)."""
+
+import shutil
+import sys
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING, Literal
+
+import cyclopts
+
+from osa.cli.console import get_console, relative_time
+
+if TYPE_CHECKING:
+    from osa.cli.console import Console
+from osa.cli.util import ConfigError, DaemonManager, OSAPaths, ServerStatus
+
+app = cyclopts.App(name="local", help="Local development server")
+
+# Local config override (for development)
+LOCAL_CONFIG = Path("osa.yaml")
+
+# Available templates
+Template = Literal["geo", "minimal"]
+
+GEO_TEMPLATE = """\
+# OSA Configuration - GEO Template
+
+server:
+  name: "My OSA Node"
+  domain: "localhost"
+
+# Database (SQLite by default, stored in $OSA_DATA_DIR or ~/.local/share/osa/)
+# database:
+#   auto_migrate: true
+
+# Logging
+# logging:
+#   level: "INFO"
+
+# GEO Ingestor - pulls from NCBI Gene Expression Omnibus via Entrez API
+ingestors:
+  - ingestor: geo-entrez
+    config:
+      record_type: gse  # gse (~250k all) or gds (~5k curated)
+      email: your@email.com  # Required by NCBI - please update this
+      # api_key: null  # Optional: NCBI API key for higher rate limits (https://account.ncbi.nlm.nih.gov/settings/)
+    initial_run:
+      enabled: true
+      limit: 50
+    # schedule:
+    #   cron: "0 * * * *"  # Hourly
+    #   limit: 100
+
+# Vector search index
+indexes:
+  - name: vector
+    backend: vector
+    config:
+      persist_dir: {vectors_dir}
+      embedding:
+        model: all-MiniLM-L6-v2
+        fields: [title, summary, organism, platform, entry_type]
+"""
+
+MINIMAL_TEMPLATE = """\
+# OSA Configuration
+
+server:
+  name: "My OSA Node"
+  domain: "localhost"
+
+# Database (SQLite by default, stored in $OSA_DATA_DIR or ~/.local/share/osa/)
+# database:
+#   auto_migrate: true
+
+# Logging
+# logging:
+#   level: "INFO"
+
+# Add your ingestors here:
+# ingestors:
+#   - ingestor: geo-entrez
+#     config:
+#       email: your@email.com
+
+# Add your indexes here:
+# indexes:
+#   - name: my-index
+#     backend: vector
+#     config:
+#       persist_dir: {vectors_dir}
+"""
+
+
+def _get_template_content(template: Template, paths: OSAPaths) -> str:
+    """Get template content with paths substituted."""
+    if template == "geo":
+        return GEO_TEMPLATE.format(vectors_dir=paths.vectors_dir)
+    else:
+        return MINIMAL_TEMPLATE.format(vectors_dir=paths.vectors_dir)
+
+
+def _resolve_config(paths: OSAPaths, console: "Console") -> Path:
+    """Resolve config file path.
+
+    Resolution order:
+    1. ./osa.yaml (local development override)
+    2. $OSA_DATA_DIR/config/config.yaml (unified mode)
+    3. ~/.config/osa/config.yaml (XDG standard location)
+
+    Returns:
+        Path to config file.
+
+    Exits:
+        If no config found, prints helpful message and exits.
+    """
+    if LOCAL_CONFIG.exists():
+        return LOCAL_CONFIG
+    elif paths.config_file.exists():
+        return paths.config_file
+    else:
+        console.error("No configuration found")
+        console.print()
+        console.print("Create a config file first:")
+        console.print("  [bold]osa local init geo[/bold]      # GEO template with vector search")
+        console.print("  [bold]osa local init minimal[/bold]  # Blank template")
+        console.print()
+        console.print("Then run: [bold]osa local start[/bold]")
+        sys.exit(1)
+
+
+@app.command
+def start(
+    host: str = "0.0.0.0",
+    port: int = 8000,
+) -> None:
+    """Start the OSA server in the background.
+
+    Args:
+        host: Host to bind to.
+        port: Port to listen on.
+    """
+    console = get_console()
+    paths = OSAPaths()
+
+    # Ensure directories exist
+    paths.ensure_directories()
+
+    # Resolve config (exits if not found)
+    config = _resolve_config(paths, console)
+
+    daemon = DaemonManager(paths)
+
+    try:
+        config_path = str(config.resolve())
+        info = daemon.start(host=host, port=port, config_file=config_path)
+        console.success(f"Server started on http://{host}:{port}")
+        console.print(f"  [dim]PID:[/dim] {info.pid}")
+        console.print(f"  [dim]Config:[/dim] {config}")
+        console.print(f"  [dim]Logs:[/dim] {daemon.paths.server_log}")
+    except ConfigError as e:
+        console.error(e.message)
+        for detail in e.details:
+            console.print(f"  [dim]•[/dim] {detail}")
+        console.print()
+        if config:
+            console.info(f"Config file: {config}")
+        sys.exit(1)
+    except RuntimeError as e:
+        console.error(str(e))
+        sys.exit(1)
+
+
+@app.command
+def stop() -> None:
+    """Stop the OSA server."""
+    console = get_console()
+    daemon = DaemonManager()
+
+    try:
+        daemon.stop()
+        console.success("Server stopped")
+    except RuntimeError as e:
+        console.error(str(e))
+        sys.exit(1)
+
+
+@app.command
+def restart() -> None:
+    """Restart the OSA server (stop + start)."""
+    console = get_console()
+    paths = OSAPaths()
+    daemon = DaemonManager(paths)
+
+    # Get current server info before stopping
+    info = daemon.status()
+    if info.status == ServerStatus.RUNNING:
+        host = info.host or "0.0.0.0"
+        port = info.port or 8000
+        console.print(f"Stopping server (PID {info.pid})...")
+        try:
+            daemon.stop()
+        except RuntimeError:
+            pass  # Continue to start even if stop fails
+    else:
+        host = "0.0.0.0"
+        port = 8000
+        if info.status == ServerStatus.STALE:
+            try:
+                daemon.stop()
+            except RuntimeError:
+                pass
+
+    # Start with resolved config
+    start(host=host, port=port)
+
+
+@app.command
+def status() -> None:
+    """Check server status."""
+    console = get_console()
+    daemon = DaemonManager()
+    info = daemon.status()
+
+    if info.status == ServerStatus.RUNNING:
+        console.success(f"Server running on http://{info.host}:{info.port}")
+        console.print(f"  [dim]PID:[/dim] {info.pid}")
+        if info.started_at:
+            console.print(f"  [dim]Started:[/dim] {relative_time(info.started_at)}")
+    elif info.status == ServerStatus.STOPPED:
+        console.print("[dim]Server is not running[/dim]")
+    elif info.status == ServerStatus.STALE:
+        console.warning(f"Stale server state (PID {info.pid} is dead)")
+        console.info("Run 'osa local stop' to clean up, or 'osa local start' to start fresh")
+
+
+@app.command
+def logs(
+    follow: bool = False,
+    lines: int = 50,
+) -> None:
+    """View server logs.
+
+    Args:
+        follow: Follow log output (like tail -f).
+        lines: Number of lines to show (default 50). Use 0 for all.
+    """
+    console = get_console()
+    paths = OSAPaths()
+    log_file = paths.server_log
+
+    if not log_file.exists():
+        console.error(
+            f"No log file found at {log_file}",
+            hint="Has the server been started?",
+        )
+        sys.exit(1)
+
+    if follow:
+        _follow_logs(log_file, lines)
+    else:
+        _show_logs(log_file, lines)
+
+
+def _show_logs(log_file: Path, lines: int) -> None:
+    """Show the last N lines of the log file."""
+    with open(log_file) as f:
+        all_lines = f.readlines()
+
+    if lines == 0:
+        for line in all_lines:
+            print(line, end="")
+    else:
+        for line in all_lines[-lines:]:
+            print(line, end="")
+
+
+def _follow_logs(log_file: Path, initial_lines: int) -> None:
+    """Follow log output, similar to tail -f."""
+    _show_logs(log_file, initial_lines)
+
+    try:
+        with open(log_file) as f:
+            f.seek(0, 2)  # Seek to end
+            while True:
+                line = f.readline()
+                if line:
+                    print(line, end="", flush=True)
+                else:
+                    time.sleep(0.1)
+    except KeyboardInterrupt:
+        print()
+
+
+@app.command
+def clean(
+    force: bool = False,
+    keep_config: bool = False,
+    keep_logs: bool = False,
+) -> None:
+    """Wipe OSA data directories to start fresh.
+
+    Stops the server if running, then removes:
+    - Data directory (database, vectors)
+    - State directory (server state, logs)
+    - Cache directory (search cache)
+    - Config directory (unless --keep-config)
+
+    Args:
+        force: Skip confirmation prompt.
+        keep_config: Keep the config directory.
+        keep_logs: Keep the logs directory.
+    """
+    console = get_console()
+    paths = OSAPaths()
+
+    # Check which directories exist
+    dirs_to_clean: list[tuple[str, Path]] = []
+    if paths.data_dir.exists():
+        dirs_to_clean.append(("Data", paths.data_dir))
+    if paths.state_dir.exists():
+        dirs_to_clean.append(("State", paths.state_dir))
+    if paths.cache_dir.exists():
+        dirs_to_clean.append(("Cache", paths.cache_dir))
+    if paths.config_dir.exists() and not keep_config:
+        dirs_to_clean.append(("Config", paths.config_dir))
+
+    if not dirs_to_clean:
+        console.info("Nothing to clean - no OSA directories exist")
+        return
+
+    # Check if server is running
+    daemon = DaemonManager()
+    status_info = daemon.status()
+
+    if status_info.status == ServerStatus.RUNNING:
+        if not force:
+            console.warning(f"Server is running (PID {status_info.pid})")
+            response = input("Stop server and clean? [y/N] ").strip().lower()
+            if response != "y":
+                console.info("Aborted")
+                sys.exit(1)
+        console.info("Stopping server...")
+        daemon.stop()
+
+    # Confirm before wiping
+    if not force:
+        console.print("[bold]This will delete:[/bold]")
+        for name, path in dirs_to_clean:
+            console.print(f"  [cyan]{path}[/cyan]  [dim]({name.lower()})[/dim]")
+        if keep_logs:
+            console.print(f"  [dim](keeping logs at {paths.logs_dir})[/dim]")
+        if keep_config and paths.config_dir.exists():
+            console.print(f"  [dim](keeping config at {paths.config_dir})[/dim]")
+        console.print()
+        response = input("Are you sure? [y/N] ").strip().lower()
+        if response != "y":
+            console.info("Aborted")
+            sys.exit(1)
+
+    # Perform cleanup
+    for name, path in dirs_to_clean:
+        if name == "State" and keep_logs:
+            # Delete everything in state except logs
+            for item in path.iterdir():
+                if item == paths.logs_dir:
+                    continue
+                if item.is_dir():
+                    shutil.rmtree(item)
+                else:
+                    item.unlink()
+            console.success(f"Cleaned {path} (logs preserved)")
+        else:
+            shutil.rmtree(path)
+            console.success(f"Removed {path}")
+
+    console.print()
+    console.info("Run 'osa local init' to set up OSA again")
+
+
+@app.command
+def init(
+    template: Template | None = None,
+    /,
+    force: bool = False,
+) -> None:
+    """Initialize OSA for local development.
+
+    Creates directories and config file in XDG locations (or $OSA_DATA_DIR).
+    Edit the config to customize your instance, then run 'osa local start'.
+
+    Args:
+        template: Template to use (geo, minimal).
+        force: Overwrite existing configuration.
+    """
+    console = get_console()
+    paths = OSAPaths()
+
+    # If no template specified, show available options
+    if template is None:
+        console.print("[bold]Available templates:[/bold]\n")
+        console.print("  [cyan]geo[/cyan]      NCBI GEO integration with vector search")
+        console.print("  [cyan]minimal[/cyan]  Blank configuration to customize")
+        console.print()
+        console.print("Usage: [bold]osa local init <template>[/bold]")
+        console.print()
+        console.print("Example: [dim]osa local init geo[/dim]")
+        sys.exit(0)
+
+    # At this point template is guaranteed to be set (sys.exit never returns)
+    assert template is not None
+
+    # Check if already initialized
+    if paths.is_initialized() and not force:
+        console.warning("OSA is already initialized")
+        console.print(f"  [dim]Config:[/dim] {paths.config_file}")
+        console.info("Use --force to reinitialize")
+        sys.exit(0)
+
+    # Create all directories
+    paths.ensure_directories()
+
+    # Generate and write config
+    config_content = _get_template_content(template, paths)
+    paths.config_file.write_text(config_content)
+
+    # Show results
+    console.success(f"Initialized OSA with '{template}' template")
+    console.print()
+    console.print(f"  [cyan]Config:[/cyan]  {paths.config_file}")
+    console.print(f"  [cyan]Data:[/cyan]    {paths.data_dir}/")
+    console.print(f"  [cyan]State:[/cyan]   {paths.state_dir}/")
+    console.print(f"  [cyan]Cache:[/cyan]   {paths.cache_dir}/")
+    console.print()
+    console.print(f"Edit your config: [bold]{paths.config_file}[/bold]")
+    console.print("Then run: [bold]osa local start[/bold]")
diff --git a/osa/cli/commands/search.py b/osa/cli/commands/search.py
index fc962a1..85dd7c3 100644
--- a/osa/cli/commands/search.py
+++ b/osa/cli/commands/search.py
@@ -11,7 +11,7 @@
 
 from osa.cli.console import get_console
 from osa.cli.models import RecordMetadata, SearchHit
-from osa.cli.util import OSAPaths
+from osa.cli.util import OSAPaths, write_search_cache
 
 app = cyclopts.App(name="search", help="Search commands")
 
@@ -97,7 +97,7 @@ def search(
         # Save to cache for `osa show <number>` lookup
         if hits:
             paths = OSAPaths()
-            paths.write_search_cache(index=index, query=query, results=hits)
+            write_search_cache(paths.search_cache_file, index=index, query=query, results=hits)
             console.search_hint()
 
     except httpx.ConnectError:
diff --git a/osa/cli/commands/server.py b/osa/cli/commands/server.py
deleted file mode 100644
index b9ad445..0000000
--- a/osa/cli/commands/server.py
+++ /dev/null
@@ -1,215 +0,0 @@
-"""Server start/stop commands."""
-
-import sys
-import time
-from pathlib import Path
-
-import cyclopts
-
-from osa.cli.console import get_console, relative_time
-from osa.cli.util import ConfigError, DaemonManager, OSAPaths, ServerStatus
-
-app = cyclopts.App(name="server", help="Server management commands")
-
-
-# Local config override (for development)
-LOCAL_CONFIG = Path("osa.yaml")
-
-
-def _resolve_config(paths: OSAPaths, config: Path | None = None) -> Path:
-    """Resolve config file path.
-
-    Resolution order:
-    1. Explicit config argument
-    2. ./osa.yaml (local development override)
-    3. ~/.config/osa/config.yaml (standard location)
-
-    Raises:
-        SystemExit: If no config found or config doesn't exist.
-    """
-    console = get_console()
-
-    if config is None:
-        if LOCAL_CONFIG.exists():
-            config = LOCAL_CONFIG
-        elif paths.config_file.exists():
-            config = paths.config_file
-        else:
-            console.error(
-                "No configuration found",
-                hint="Run 'osa init' to set up OSA",
-            )
-            sys.exit(1)
-
-    assert config is not None  # Guaranteed by logic above
-    if not config.exists():
-        console.error(f"Config file not found: {config}")
-        sys.exit(1)
-
-    return config
-
-
-@app.command
-def start(
-    host: str = "0.0.0.0",
-    port: int = 8000,
-) -> None:
-    """Start the OSA server in the background.
-
-    Args:
-        host: Host to bind to.
-        port: Port to listen on.
-        config: Path to config file. Defaults to ~/.config/osa/config.yaml,
-                or ./osa.yaml if present (for local development).
-    """
-    console = get_console()
-    paths = OSAPaths()
-    daemon = DaemonManager(paths)
-
-    config = _resolve_config(paths)
-
-    try:
-        config_path = str(config.resolve())
-        info = daemon.start(host=host, port=port, config_file=config_path)
-        console.success(f"Server started on http://{host}:{port}")
-        console.print(f"  [dim]PID:[/dim] {info.pid}")
-        console.print(f"  [dim]Config:[/dim] {config}")
-        console.print(f"  [dim]Logs:[/dim] {daemon.paths.server_log}")
-    except ConfigError as e:
-        console.error(e.message)
-        for detail in e.details:
-            console.print(f"  [dim]•[/dim] {detail}")
-        console.print()
-        console.info(f"Config file: {config}")
-        sys.exit(1)
-    except RuntimeError as e:
-        console.error(str(e))
-        sys.exit(1)
-
-
-@app.command
-def stop() -> None:
-    """Stop the OSA server."""
-    console = get_console()
-    daemon = DaemonManager()
-
-    try:
-        daemon.stop()
-        console.success("Server stopped")
-    except RuntimeError as e:
-        console.error(str(e))
-        sys.exit(1)
-
-
-@app.command
-def restart(
-    config: Path | None = None,
-) -> None:
-    """Restart the OSA server (stop + start).
-
-    Args:
-        config: Path to config file. If not specified, uses the same resolution
-                as 'start' (./osa.yaml or ~/.config/osa/config.yaml).
-    """
-    console = get_console()
-    paths = OSAPaths()
-    daemon = DaemonManager(paths)
-
-    # Get current server info before stopping
-    info = daemon.status()
-    if info.status == ServerStatus.RUNNING:
-        host = info.host or "0.0.0.0"
-        port = info.port or 8000
-        console.print(f"Stopping server (PID {info.pid})...")
-        try:
-            daemon.stop()
-        except RuntimeError:
-            pass  # Continue to start even if stop fails
-    else:
-        host = "0.0.0.0"
-        port = 8000
-        if info.status == ServerStatus.STALE:
-            try:
-                daemon.stop()
-            except RuntimeError:
-                pass
-
-    # Start with resolved config
-    start(host=host, port=port)
-
-
-@app.command
-def status() -> None:
-    """Check server status."""
-    console = get_console()
-    daemon = DaemonManager()
-    info = daemon.status()
-
-    if info.status == ServerStatus.RUNNING:
-        console.success(f"Server running on http://{info.host}:{info.port}")
-        console.print(f"  [dim]PID:[/dim] {info.pid}")
-        if info.started_at:
-            console.print(f"  [dim]Started:[/dim] {relative_time(info.started_at)}")
-    elif info.status == ServerStatus.STOPPED:
-        console.print("[dim]Server is not running[/dim]")
-    elif info.status == ServerStatus.STALE:
-        console.warning(f"Stale server state (PID {info.pid} is dead)")
-        console.info("Run 'osa server stop' to clean up, or 'osa server start' to start fresh")
-
-
-@app.command
-def logs(
-    follow: bool = False,
-    lines: int = 50,
-) -> None:
-    """View server logs.
-
-    Args:
-        follow: Follow log output (like tail -f).
-        lines: Number of lines to show (default 50). Use 0 for all.
-    """
-    console = get_console()
-    paths = OSAPaths()
-    log_file = paths.server_log
-
-    if not log_file.exists():
-        console.error(
-            f"No log file found at {log_file}",
-            hint="Has the server been started?",
-        )
-        sys.exit(1)
-
-    if follow:
-        _follow_logs(log_file, lines)
-    else:
-        _show_logs(log_file, lines)
-
-
-def _show_logs(log_file: Path, lines: int) -> None:
-    """Show the last N lines of the log file."""
-    with open(log_file) as f:
-        all_lines = f.readlines()
-
-    if lines == 0:
-        for line in all_lines:
-            print(line, end="")
-    else:
-        for line in all_lines[-lines:]:
-            print(line, end="")
-
-
-def _follow_logs(log_file: Path, initial_lines: int) -> None:
-    """Follow log output, similar to tail -f."""
-    _show_logs(log_file, initial_lines)
-
-    try:
-        with open(log_file) as f:
-            f.seek(0, 2)  # Seek to end
-            while True:
-                line = f.readline()
-                if line:
-                    print(line, end="", flush=True)
-                else:
-                    time.sleep(0.1)
-    except KeyboardInterrupt:
-        print()
diff --git a/osa/cli/commands/show.py b/osa/cli/commands/show.py
index a956824..7f064fb 100644
--- a/osa/cli/commands/show.py
+++ b/osa/cli/commands/show.py
@@ -6,7 +6,7 @@
 
 from osa.cli.console import get_console
 from osa.cli.models import SearchHit
-from osa.cli.util import OSAPaths
+from osa.cli.util import OSAPaths, read_search_cache
 
 app = cyclopts.App(name="show", help="Show record details from last search")
 
@@ -20,7 +20,7 @@ def show(ref: str, /) -> None:
     """
     console = get_console()
     paths = OSAPaths()
-    cache = paths.read_search_cache()
+    cache = read_search_cache(paths.search_cache_file)
 
     if cache is None:
         console.error(
diff --git a/osa/cli/main.py b/osa/cli/main.py
index c45b907..da3ac36 100644
--- a/osa/cli/main.py
+++ b/osa/cli/main.py
@@ -6,15 +6,14 @@
 
 import cyclopts
 
-from osa.cli.commands import admin, events, init, search, server, show, stats
+from osa.cli.commands import admin, events, local, search, show, stats
 
 app = cyclopts.App(
     name="osa",
     help="Open Science Archive - CLI",
 )
 
-app.command(init.app, name="init")
-app.command(server.app, name="server")
+app.command(local.app, name="local")
 app.command(search.app, name="search")
 app.command(show.app, name="show")
 app.command(stats.app, name="stats")
diff --git a/osa/cli/util/__init__.py b/osa/cli/util/__init__.py
index 07856d6..dc1c1cc 100644
--- a/osa/cli/util/__init__.py
+++ b/osa/cli/util/__init__.py
@@ -1,7 +1,13 @@
-"""CLI utilities (~/.osa directory, daemon management, caching)."""
+"""CLI utilities (paths, daemon management, caching)."""
 
 from osa.cli.util.daemon import ConfigError, DaemonManager, ServerInfo, ServerStatus
 from osa.cli.util.paths import OSAPaths, ServerState
+from osa.cli.util.search_cache import read_search_cache, write_search_cache
+from osa.cli.util.server_state import (
+    read_server_state,
+    remove_server_state,
+    write_server_state,
+)
 
 __all__ = [
     "ConfigError",
@@ -10,4 +16,11 @@
     "ServerInfo",
     "ServerState",
     "ServerStatus",
+    # Server state I/O
+    "read_server_state",
+    "write_server_state",
+    "remove_server_state",
+    # Search cache I/O
+    "read_search_cache",
+    "write_search_cache",
 ]
diff --git a/osa/cli/util/daemon.py b/osa/cli/util/daemon.py
index 42509e9..e7d99e2 100644
--- a/osa/cli/util/daemon.py
+++ b/osa/cli/util/daemon.py
@@ -11,6 +11,11 @@
 from pydantic import ValidationError
 
 from osa.cli.util.paths import OSAPaths
+from osa.cli.util.server_state import (
+    read_server_state,
+    remove_server_state,
+    write_server_state,
+)
 
 
 class ServerStatus(Enum):
@@ -54,7 +59,7 @@ def paths(self) -> OSAPaths:
 
     def status(self) -> ServerInfo:
         """Get server status."""
-        state = self._paths.read_server_state()
+        state = read_server_state(self._paths.server_state_file)
 
         if state is None:
             return ServerInfo(status=ServerStatus.STOPPED)
@@ -105,7 +110,7 @@ def start(
 
         if current.status == ServerStatus.STALE:
             # Clean up stale state file
-            self._paths.remove_server_state()
+            remove_server_state(self._paths.server_state_file)
 
         self._paths.ensure_directories()
 
@@ -165,13 +170,13 @@ def start(
         )
 
         # Write server state
-        state = self._paths.write_server_state(process.pid, host, port)
+        state = write_server_state(self._paths.server_state_file, process.pid, host, port)
 
         # Wait briefly and verify it started
         time.sleep(0.5)
         if process.poll() is not None:
             # Process exited immediately - error
-            self._paths.remove_server_state()
+            remove_server_state(self._paths.server_state_file)
             raise RuntimeError(f"Server failed to start. Check logs at {self._paths.server_log}")
 
         return ServerInfo(
@@ -201,7 +206,7 @@ def stop(self, timeout: float = 10.0) -> ServerInfo:
 
         if current.status == ServerStatus.STALE:
             # Just clean up the stale state file
-            self._paths.remove_server_state()
+            remove_server_state(self._paths.server_state_file)
             return ServerInfo(status=ServerStatus.STOPPED)
 
         pid = current.pid
@@ -212,14 +217,14 @@ def stop(self, timeout: float = 10.0) -> ServerInfo:
             os.kill(pid, signal.SIGTERM)
         except ProcessLookupError:
             # Process already dead
-            self._paths.remove_server_state()
+            remove_server_state(self._paths.server_state_file)
             return ServerInfo(status=ServerStatus.STOPPED)
 
         # Wait for process to exit
         start_time = time.time()
         while time.time() - start_time < timeout:
             if not self._is_process_running(pid):
-                self._paths.remove_server_state()
+                remove_server_state(self._paths.server_state_file)
                 return ServerInfo(status=ServerStatus.STOPPED)
             time.sleep(0.1)
 
@@ -230,7 +235,7 @@ def stop(self, timeout: float = 10.0) -> ServerInfo:
         except ProcessLookupError:
             pass
 
-        self._paths.remove_server_state()
+        remove_server_state(self._paths.server_state_file)
         return ServerInfo(status=ServerStatus.STOPPED)
 
     def _is_process_running(self, pid: int) -> bool:
diff --git a/osa/cli/util/paths.py b/osa/cli/util/paths.py
index 1914f02..250de93 100644
--- a/osa/cli/util/paths.py
+++ b/osa/cli/util/paths.py
@@ -1,31 +1,29 @@
-"""Manages OSA directory structure following XDG Base Directory spec.
+"""Manages OSA directory structure.
 
-Directory layout:
-    ~/.config/osa/
-        config.yaml         # User configuration
+Supports two modes:
 
-    ~/.local/share/osa/
-        osa.db              # SQLite database
-        vectors/            # Vector index (ChromaDB)
+1. **Unified mode** (OSA_DATA_DIR set): All data under a single directory
+   for container deployments with single volume mount.
 
-    ~/.local/state/osa/
-        server.json         # Daemon state (PID, host, port)
-        logs/
-            server.log      # Server logs
+   OSA_DATA_DIR=/data
+     /data/config/     → config files
+     /data/data/       → database, vectors
+     /data/state/      → logs, server state
+     /data/cache/      → CLI cache
 
-    ~/.cache/osa/
-        last_search.json    # CLI search cache
+2. **XDG mode** (default): Follows XDG Base Directory specification
+   for local development.
+
+   ~/.config/osa/      → config files
+   ~/.local/share/osa/ → database, vectors
+   ~/.local/state/osa/ → logs, server state
+   ~/.cache/osa/       → CLI cache
 """
 
-import json
-from dataclasses import asdict, dataclass
-from datetime import UTC, datetime
+import os
+from dataclasses import dataclass
 from pathlib import Path
 
-from pydantic import ValidationError
-
-from osa.cli.models import SearchCache, SearchHit
-
 
 @dataclass
 class ServerState:
@@ -38,32 +36,34 @@ class ServerState:
 
 
 class OSAPaths:
-    """Manages OSA paths following XDG Base Directory specification.
+    """Computes OSA paths for unified or XDG mode.
+
+    Reads OSA_DATA_DIR environment variable to determine mode:
+    - If set: unified mode (all paths under OSA_DATA_DIR)
+    - If not set: XDG mode (standard ~/.config, ~/.local paths)
 
-    Supports overriding individual directories for testing.
+    This class is purely for path computation - no file I/O operations.
+    Use server_state.py and search_cache.py for reading/writing files.
     """
 
-    def __init__(
-        self,
-        *,
-        config_dir: Path | None = None,
-        data_dir: Path | None = None,
-        state_dir: Path | None = None,
-        cache_dir: Path | None = None,
-    ) -> None:
-        """Initialize paths.
-
-        Args:
-            config_dir: Override config directory (default: ~/.config/osa).
-            data_dir: Override data directory (default: ~/.local/share/osa).
-            state_dir: Override state directory (default: ~/.local/state/osa).
-            cache_dir: Override cache directory (default: ~/.cache/osa).
-        """
-        home = Path.home()
-        self._config_dir = config_dir or home / ".config" / "osa"
-        self._data_dir = data_dir or home / ".local" / "share" / "osa"
-        self._state_dir = state_dir or home / ".local" / "state" / "osa"
-        self._cache_dir = cache_dir or home / ".cache" / "osa"
+    def __init__(self) -> None:
+        """Initialize paths based on OSA_DATA_DIR environment variable."""
+        env_data_dir = os.environ.get("OSA_DATA_DIR")
+
+        if env_data_dir:
+            # Unified mode: all paths under single directory
+            unified_data_dir = Path(env_data_dir)
+            self._config_dir = unified_data_dir / "config"
+            self._data_dir = unified_data_dir / "data"
+            self._state_dir = unified_data_dir / "state"
+            self._cache_dir = unified_data_dir / "cache"
+        else:
+            # XDG mode: standard paths for local development
+            home = Path.home()
+            self._config_dir = home / ".config" / "osa"
+            self._data_dir = home / ".local" / "share" / "osa"
+            self._state_dir = home / ".local" / "state" / "osa"
+            self._cache_dir = home / ".cache" / "osa"
 
     # -------------------------------------------------------------------------
     # Base directories
@@ -156,65 +156,3 @@ def ensure_directories(self) -> None:
     def is_initialized(self) -> bool:
         """Check if OSA has been initialized (config file exists)."""
         return self.config_file.exists()
-
-    # -------------------------------------------------------------------------
-    # Server state
-    # -------------------------------------------------------------------------
-
-    def read_server_state(self) -> ServerState | None:
-        """Read server state from file."""
-        if not self.server_state_file.exists():
-            return None
-        try:
-            data = json.loads(self.server_state_file.read_text())
-            return ServerState(**data)
-        except (json.JSONDecodeError, TypeError, KeyError, OSError):
-            return None
-
-    def write_server_state(self, pid: int, host: str, port: int) -> ServerState:
-        """Write server state to file."""
-        self._state_dir.mkdir(parents=True, exist_ok=True)
-        state = ServerState(
-            pid=pid,
-            host=host,
-            port=port,
-            started_at=datetime.now(UTC).isoformat(),
-        )
-        self.server_state_file.write_text(json.dumps(asdict(state), indent=2))
-        return state
-
-    def remove_server_state(self) -> None:
-        """Remove server state file."""
-        if self.server_state_file.exists():
-            self.server_state_file.unlink()
-
-    # -------------------------------------------------------------------------
-    # Search cache
-    # -------------------------------------------------------------------------
-
-    def read_search_cache(self) -> SearchCache | None:
-        """Read cached search results."""
-        if not self.search_cache_file.exists():
-            return None
-        try:
-            data = json.loads(self.search_cache_file.read_text())
-            return SearchCache.model_validate(data)
-        except (json.JSONDecodeError, ValidationError, OSError):
-            return None
-
-    def write_search_cache(
-        self,
-        index: str,
-        query: str,
-        results: list[SearchHit],
-    ) -> SearchCache:
-        """Write search results to cache for numbered lookup."""
-        self._cache_dir.mkdir(parents=True, exist_ok=True)
-        cache = SearchCache(
-            index=index,
-            query=query,
-            searched_at=datetime.now(UTC).isoformat(),
-            results=results,
-        )
-        self.search_cache_file.write_text(cache.model_dump_json(indent=2))
-        return cache
diff --git a/osa/cli/util/search_cache.py b/osa/cli/util/search_cache.py
new file mode 100644
index 0000000..ebde485
--- /dev/null
+++ b/osa/cli/util/search_cache.py
@@ -0,0 +1,60 @@
+"""Search cache file I/O utilities.
+
+Handles reading and writing the search results cache file that enables
+numbered result lookup in CLI (e.g., `osa show 1`).
+"""
+
+from datetime import UTC, datetime
+from pathlib import Path
+
+from pydantic import ValidationError
+
+from osa.cli.models import SearchCache, SearchHit
+
+
+def read_search_cache(cache_file: Path) -> SearchCache | None:
+    """Read cached search results.
+
+    Args:
+        cache_file: Path to the cache file (e.g., last_search.json).
+
+    Returns:
+        SearchCache if file exists and is valid, None otherwise.
+    """
+    if not cache_file.exists():
+        return None
+    try:
+        data = cache_file.read_text()
+        return SearchCache.model_validate_json(data)
+    except (ValidationError, OSError):
+        return None
+
+
+def write_search_cache(
+    cache_file: Path,
+    index: str,
+    query: str,
+    results: list[SearchHit],
+) -> SearchCache:
+    """Write search results to cache for numbered lookup.
+
+    Creates parent directories if they don't exist.
+
+    Args:
+        cache_file: Path to the cache file.
+        index: Name of the index that was searched.
+        query: The search query string.
+        results: List of search result hits.
+
+    Returns:
+        The created SearchCache.
+    """
+    cache_file.parent.mkdir(parents=True, exist_ok=True)
+    cache = SearchCache(
+        index=index,
+        query=query,
+        searched_at=datetime.now(UTC).isoformat(),
+        results=results,
+    )
+    cache_file.write_text(cache.model_dump_json(indent=2))
+    return cache
diff --git a/osa/cli/util/server_state.py b/osa/cli/util/server_state.py
new file mode 100644
index 0000000..8688bc0
--- /dev/null
+++ b/osa/cli/util/server_state.py
@@ -0,0 +1,65 @@
+"""Server state file I/O utilities.
+
+Handles reading and writing the server.json state file that tracks
+the running daemon's PID, host, port, and start time.
+"""
+
+import json
+from dataclasses import asdict
+from datetime import UTC, datetime
+from pathlib import Path
+
+from osa.cli.util.paths import ServerState
+
+
+def read_server_state(state_file: Path) -> ServerState | None:
+    """Read server state from file.
+
+    Args:
+        state_file: Path to the server.json file.
+
+    Returns:
+        ServerState if file exists and is valid, None otherwise.
+    """
+    if not state_file.exists():
+        return None
+    try:
+        data = json.loads(state_file.read_text())
+        return ServerState(**data)
+    except (json.JSONDecodeError, TypeError, KeyError, OSError):
+        return None
+
+
+def write_server_state(state_file: Path, pid: int, host: str, port: int) -> ServerState:
+    """Write server state to file.
+
+    Creates parent directories if they don't exist.
+
+    Args:
+        state_file: Path to the server.json file.
+        pid: Process ID of the running server.
+        host: Host the server is listening on.
+        port: Port the server is listening on.
+
+    Returns:
+        The created ServerState.
+    """
+    state_file.parent.mkdir(parents=True, exist_ok=True)
+    state = ServerState(
+        pid=pid,
+        host=host,
+        port=port,
+        started_at=datetime.now(UTC).isoformat(),
+    )
+    state_file.write_text(json.dumps(asdict(state), indent=2))
+    return state
+
+
+def remove_server_state(state_file: Path) -> None:
+    """Remove server state file.
+
+    Args:
+        state_file: Path to the server.json file.
+    """
+    if state_file.exists():
+        state_file.unlink()
diff --git a/osa/config.py b/osa/config.py
index 96b3375..316c23a 100644
--- a/osa/config.py
+++ b/osa/config.py
@@ -6,9 +6,11 @@
 from typing import Annotated, Any, Union
 
 import yaml
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, model_validator
 from pydantic_settings import BaseSettings, PydanticBaseSettingsSource
+from typing_extensions import Self
 
+from osa.cli.util.paths import OSAPaths
 from osa.infrastructure.index.vector.config import VectorBackendConfig
 
 
@@ -97,24 +99,37 @@ def _load_yaml_config(self) -> dict[str, Any]:
         return {}
 
 
-class Frontend(BaseSettings):
+class Frontend(BaseModel):
+    """Frontend configuration (nested in Config, uses env_nested_delimiter)."""
+
     url: str = "http://localhost:3000"
 
 
-class Server(BaseSettings):
+class Server(BaseModel):
+    """Server configuration (nested in Config, uses env_nested_delimiter)."""
+
     name: str = "Open Science Archive"
     version: str = "0.0.1"  # TODO: better type?
     description: str = "An open platform for depositing scientific data"
     domain: str = "localhost"  # Node domain for SRN construction
 
 
-class DatabaseConfig(BaseSettings):
-    url: str = "sqlite+aiosqlite:///~/.local/share/osa/osa.db"  # XDG data directory
+class DatabaseConfig(BaseModel):
+    """Database configuration (nested in Config, uses env_nested_delimiter).
+
+    The url field uses empty string as sentinel to indicate "derive from OSAPaths".
+    When user doesn't override via OSA_DATABASE__URL, we compute the actual path
+    in Config's model_validator.
+    """
+
+    url: str = ""  # Empty string = derive from paths; explicit value = use as-is
     echo: bool = False
     auto_migrate: bool = True  # Auto-migrate for SQLite, manual for PostgreSQL
 
 
-class LoggingConfig(BaseSettings):
+class LoggingConfig(BaseModel):
+    """Logging configuration (nested in Config, uses env_nested_delimiter)."""
+
     level: str = "DEBUG"  # Root log level (DEBUG for development)
     format: str = "%(asctime)s %(levelname)-8s [%(name)s] %(message)s"
     date_format: str = "%Y-%m-%d %H:%M:%S"
@@ -126,6 +141,7 @@ def file(self) -> str | None:
 
 
 class Config(BaseSettings):
+    # These are BaseModel, so env_nested_delimiter handles their env vars
     server: Server = Server()
     frontend: Frontend = Frontend()
     database: DatabaseConfig = DatabaseConfig()
@@ -133,10 +149,31 @@ class Config(BaseSettings):
     indexes: list[IndexConfig] = []  # list of index configs
     ingestors: list[IngestConfig] = []  # list of ingestor configs
 
-    class Config:
-        env_file = ".env"
-        env_file_encoding = "utf-8"
-        env_nested_delimiter = "__"  # Allows OSA_DATABASE__URL override
+    model_config = {
+        "env_prefix": "OSA_",
+        "env_file": ".env",
+        "env_file_encoding": "utf-8",
+        "env_nested_delimiter": "__",  # Allows OSA_DATABASE__URL override
+    }
+
+    @model_validator(mode="after")
+    def derive_database_url(self) -> Self:
+        """Derive database URL from OSAPaths if not explicitly set.
+
+        When database.url is empty (sentinel value), compute the path from OSAPaths.
+        OSAPaths reads OSA_DATA_DIR directly from environment.
+        This allows OSA_DATA_DIR to control the database location while still
+        allowing explicit OSA_DATABASE__URL override.
+        """
+        if not self.database.url:
+            # URL is sentinel (empty), derive from OSAPaths
+            osa_paths = OSAPaths()
+            self.database = DatabaseConfig(
+                url=f"sqlite+aiosqlite:///{osa_paths.database_file}",
+                echo=self.database.echo,
+                auto_migrate=self.database.auto_migrate,
+            )
+        return self
 
     @classmethod
     def settings_customise_sources(
diff --git a/osa/infrastructure/index/di.py b/osa/infrastructure/index/di.py
index b0b02ee..8e5ee3a 100644
--- a/osa/infrastructure/index/di.py
+++ b/osa/infrastructure/index/di.py
@@ -2,10 +2,12 @@
 
 from dishka import Provider, provide
 
+from osa.cli.util.paths import OSAPaths
 from osa.config import Config
 from osa.domain.index.model.registry import IndexRegistry
 from osa.domain.index.service import IndexService
 from osa.infrastructure.index.vector.backend import VectorStorageBackend
+from osa.infrastructure.index.vector.config import VectorBackendConfig
 from osa.sdk.index.backend import StorageBackend
 from osa.util.di.scope import Scope
 
@@ -14,9 +16,13 @@ class IndexProvider(Provider):
     """Provides configured index backends."""
 
     @provide(scope=Scope.APP)
-    def get_backends(self, config: Config) -> IndexRegistry:
+    def get_backends(self, config: Config, paths: OSAPaths) -> IndexRegistry:
         """Build all configured index backends.
 
+        Args:
+            config: Application configuration with index configs.
+            paths: OSAPaths for deriving default persist_dir.
+
         Returns:
             Registry of index backends.
         """
@@ -24,7 +30,17 @@ def get_backends(self, config: Config) -> IndexRegistry:
 
         for idx_config in config.indexes:
             if idx_config.backend == "vector":
-                backends[idx_config.name] = VectorStorageBackend(idx_config.name, idx_config.config)
+                vector_config = idx_config.config
+                # Derive persist_dir from OSAPaths if not explicitly set
+                if (
+                    isinstance(vector_config, VectorBackendConfig)
+                    and vector_config.persist_dir is None
+                ):
+                    vector_config = VectorBackendConfig(
+                        persist_dir=paths.vectors_dir,
+                        embedding=vector_config.embedding,
+                    )
+                backends[idx_config.name] = VectorStorageBackend(idx_config.name, vector_config)
             # Add more backend types here as they're implemented
             # elif idx_config.backend == "keyword":
             #     backends[idx_config.name] = KeywordStorageBackend(
diff --git a/osa/infrastructure/index/vector/backend.py b/osa/infrastructure/index/vector/backend.py
index 46c95ed..b3a853f 100644
--- a/osa/infrastructure/index/vector/backend.py
+++ b/osa/infrastructure/index/vector/backend.py
@@ -22,6 +22,10 @@ def __init__(self, name: str, config: VectorBackendConfig) -> None:
         self._config = config
         self._model = SentenceTransformer(config.embedding.model.value)
 
+        # persist_dir must be set by DI (derived from OSAPaths if not explicit)
+        if config.persist_dir is None:
+            raise ValueError("VectorBackendConfig.persist_dir must be set")
+
         # Expand ~ to home directory and ensure persist directory exists
         persist_dir = config.persist_dir.expanduser()
         persist_dir.mkdir(parents=True, exist_ok=True)
diff --git a/osa/infrastructure/index/vector/config.py b/osa/infrastructure/index/vector/config.py
index 495fda5..6c9cf2b 100644
--- a/osa/infrastructure/index/vector/config.py
+++ b/osa/infrastructure/index/vector/config.py
@@ -31,7 +31,11 @@ class EmbeddingConfig(BaseModel):
 
 
 class VectorBackendConfig(BackendConfig):
-    """ChromaDB + sentence-transformers specific configuration."""
+    """ChromaDB + sentence-transformers specific configuration.
 
-    persist_dir: Path
+    If persist_dir is not specified (None), it will be derived from OSAPaths.vectors_dir
+    in the DI provider, respecting OSA_DATA_DIR for container deployments.
+    """
+
+    persist_dir: Path | None = None  # None = derive from OSAPaths
     embedding: EmbeddingConfig = EmbeddingConfig()
diff --git a/tests/unit/cli/__init__.py b/tests/unit/cli/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/unit/cli/util/__init__.py b/tests/unit/cli/util/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/unit/cli/util/test_paths.py b/tests/unit/cli/util/test_paths.py
new file mode 100644
index 0000000..7112b04
--- /dev/null
+++ b/tests/unit/cli/util/test_paths.py
@@ -0,0 +1,150 @@
+"""Tests for OSAPaths path computation."""
+
+from pathlib import Path
+
+import pytest
+
+from osa.cli.util.paths import OSAPaths
+
+
+class TestOSAPathsXDGMode:
+    """Tests for XDG mode (default, when OSA_DATA_DIR is not set)."""
+
+    def test_xdg_mode_uses_home_directory(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """XDG mode should derive paths from home directory."""
+        # Ensure OSA_DATA_DIR is not set
+        monkeypatch.delenv("OSA_DATA_DIR", raising=False)
+        # Patch Path.home() to use a test path
+        test_home = Path("/test/home")
+        monkeypatch.setattr(Path, "home", lambda: test_home)
+
+        paths = OSAPaths()
+
+        assert paths.config_dir == test_home / ".config" / "osa"
+        assert paths.data_dir == test_home / ".local" / "share" / "osa"
+        assert paths.state_dir == test_home / ".local" / "state" / "osa"
+        assert paths.cache_dir == test_home / ".cache" / "osa"
+
+    def test_xdg_mode_file_paths(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """XDG mode should derive file paths correctly."""
+        monkeypatch.delenv("OSA_DATA_DIR", raising=False)
+        test_home = Path("/test/home")
+        monkeypatch.setattr(Path, "home", lambda: test_home)
+
+        paths = OSAPaths()
+
+        assert paths.config_file == test_home / ".config" / "osa" / "config.yaml"
+        assert paths.database_file == test_home / ".local" / "share" / "osa" / "osa.db"
+        assert paths.vectors_dir == test_home / ".local" / "share" / "osa" / "vectors"
+        assert paths.server_state_file == test_home / ".local" / "state" / "osa" / "server.json"
+        assert paths.logs_dir == test_home / ".local" / "state" / "osa" / "logs"
+        assert paths.server_log == test_home / ".local" / "state" / "osa" / "logs" / "server.log"
+        assert paths.search_cache_file == test_home / ".cache" / "osa" / "last_search.json"
+
+
+class TestOSAPathsUnifiedMode:
+    """Tests for unified mode (when OSA_DATA_DIR is set)."""
+
+    def test_unified_mode_derives_all_paths_from_data_dir(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Unified mode should derive all paths from OSA_DATA_DIR."""
+        monkeypatch.setenv("OSA_DATA_DIR", "/data")
+
+        paths = OSAPaths()
+
+        assert paths.config_dir == Path("/data/config")
+        assert paths.data_dir == Path("/data/data")
+        assert paths.state_dir == Path("/data/state")
+        assert paths.cache_dir == Path("/data/cache")
+
+    def test_unified_mode_file_paths(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Unified mode should derive file paths correctly."""
+        monkeypatch.setenv("OSA_DATA_DIR", "/data")
+
+        paths = OSAPaths()
+
+        assert paths.config_file == Path("/data/config/config.yaml")
+        assert paths.database_file == Path("/data/data/osa.db")
+        assert paths.vectors_dir == Path("/data/data/vectors")
+        assert paths.server_state_file == Path("/data/state/server.json")
+        assert paths.logs_dir == Path("/data/state/logs")
+        assert paths.server_log == Path("/data/state/logs/server.log")
+        assert paths.search_cache_file == Path("/data/cache/last_search.json")
+
+    def test_unified_mode_with_absolute_path(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Unified mode should work with absolute paths."""
+        monkeypatch.setenv("OSA_DATA_DIR", "/var/lib/osa")
+
+        paths = OSAPaths()
+
+        assert paths.data_dir == Path("/var/lib/osa/data")
+        assert paths.database_file == Path("/var/lib/osa/data/osa.db")
+
+    def test_unified_mode_subdirectory_structure(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Unified mode should create expected subdirectory structure."""
+        monkeypatch.setenv("OSA_DATA_DIR", "/data")
+
+        paths = OSAPaths()
+
+        # Verify the structure matches the spec
+        assert paths.config_dir.parent == Path("/data")
+        assert paths.data_dir.parent == Path("/data")
+        assert paths.state_dir.parent == Path("/data")
+        assert paths.cache_dir.parent == Path("/data")
+
+
+class TestOSAPathsEnsureDirectories:
+    """Tests for ensure_directories method."""
+
+    def test_ensure_directories_creates_all_dirs(
+        self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+    ) -> None:
+        """ensure_directories should create all required directories."""
+        monkeypatch.setenv("OSA_DATA_DIR", str(tmp_path))
+
+        paths = OSAPaths()
+        paths.ensure_directories()
+
+        assert paths.config_dir.exists()
+        assert paths.data_dir.exists()
+        assert paths.state_dir.exists()
+        assert paths.cache_dir.exists()
+        assert paths.logs_dir.exists()
+        assert paths.vectors_dir.exists()
+
+    def test_ensure_directories_is_idempotent(
+        self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+    ) -> None:
+        """ensure_directories should be safe to call multiple times."""
+        monkeypatch.setenv("OSA_DATA_DIR", str(tmp_path))
+
+        paths = OSAPaths()
+        paths.ensure_directories()
+        paths.ensure_directories()  # Should not raise
+
+        assert paths.config_dir.exists()
+
+
+class TestOSAPathsIsInitialized:
+    """Tests for is_initialized method."""
+
+    def test_is_initialized_returns_false_when_no_config(
+        self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+    ) -> None:
+        """is_initialized should return False when config file doesn't exist."""
+        monkeypatch.setenv("OSA_DATA_DIR", str(tmp_path))
+
+        paths = OSAPaths()
+        assert not paths.is_initialized()
+
+    def test_is_initialized_returns_true_when_config_exists(
+        self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+    ) -> None:
+        """is_initialized should return True when config file exists."""
+        monkeypatch.setenv("OSA_DATA_DIR", str(tmp_path))
+
+        paths = OSAPaths()
+        paths.ensure_directories()
+        paths.config_file.write_text("server:\n  name: test")
+        assert paths.is_initialized()
diff --git a/tests/unit/config/__init__.py b/tests/unit/config/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/unit/config/test_paths_config.py b/tests/unit/config/test_paths_config.py
new file mode 100644
index 0000000..91ac4f8
--- /dev/null
+++ b/tests/unit/config/test_paths_config.py
@@ -0,0 +1,64 @@
+"""Tests for Config database URL derivation."""
+
+from pathlib import Path
+
+import pytest
+
+from osa.config import Config
+
+
+class TestDatabaseUrlDerivation:
+    """Tests for database URL derivation from OSAPaths."""
+
+    def test_database_url_derived_from_osa_data_dir(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Database URL should derive from OSA_DATA_DIR when set."""
+        monkeypatch.setenv("OSA_DATA_DIR", "/data")
+        # Clear any existing database URL override
+        monkeypatch.delenv("OSA_DATABASE__URL", raising=False)
+
+        config = Config()
+
+        # Should derive database path from /data/data/osa.db
+        assert config.database.url == "sqlite+aiosqlite:////data/data/osa.db"
+
+    def test_database_url_derived_from_xdg_defaults(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Database URL should derive from XDG defaults when OSA_DATA_DIR not set."""
+        # Clear OSA_DATA_DIR to use XDG mode
+        monkeypatch.delenv("OSA_DATA_DIR", raising=False)
+        monkeypatch.delenv("OSA_DATABASE__URL", raising=False)
+
+        # Patch Path.home() to use a test path
+        test_home = Path("/test/home")
+        monkeypatch.setattr(Path, "home", lambda: test_home)
+
+        config = Config()
+
+        # Should derive database path from XDG data directory
+        expected_path = test_home / ".local" / "share" / "osa" / "osa.db"
+        assert config.database.url == f"sqlite+aiosqlite:///{expected_path}"
+
+    def test_explicit_database_url_override(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Explicit OSA_DATABASE__URL should override derived path."""
+        # Set both OSA_DATA_DIR and explicit database URL
+        monkeypatch.setenv("OSA_DATA_DIR", "/data")
+        monkeypatch.setenv("OSA_DATABASE__URL", "postgresql+asyncpg://user:pass@db:5432/osa")
+
+        config = Config()
+
+        # Should use explicit URL, not derived
+        assert config.database.url == "postgresql+asyncpg://user:pass@db:5432/osa"
+
+    def test_database_url_preserves_other_settings(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Database URL derivation should preserve echo and auto_migrate settings."""
+        monkeypatch.setenv("OSA_DATA_DIR", "/data")
+        monkeypatch.delenv("OSA_DATABASE__URL", raising=False)
+        monkeypatch.setenv("OSA_DATABASE__ECHO", "true")
+        monkeypatch.setenv("OSA_DATABASE__AUTO_MIGRATE", "false")
+
+        config = Config()
+
+        # URL should be derived
+        assert "sqlite+aiosqlite" in config.database.url
+        # But other settings should be preserved from env vars
+        assert config.database.echo is True
+        assert config.database.auto_migrate is False
diff --git a/tests/unit/infrastructure/index/test_vector_config.py b/tests/unit/infrastructure/index/test_vector_config.py
new file mode 100644
index 0000000..cf14083
--- /dev/null
+++ b/tests/unit/infrastructure/index/test_vector_config.py
@@ -0,0 +1,61 @@
+"""Tests for vector index configuration with OSA_DATA_DIR support."""
+
+from pathlib import Path
+
+import pytest
+
+from osa.cli.util.paths import OSAPaths
+from osa.infrastructure.index.vector.config import VectorBackendConfig
+
+
+class TestVectorBackendConfig:
+    """Tests for VectorBackendConfig persist_dir handling."""
+
+    def test_persist_dir_defaults_to_none(self) -> None:
+        """persist_dir should default to None (derive from OSAPaths)."""
+        config = VectorBackendConfig()
+        assert config.persist_dir is None
+
+    def test_persist_dir_accepts_explicit_path(self) -> None:
+        """persist_dir should accept explicit path values."""
+        config = VectorBackendConfig(persist_dir=Path("/custom/vectors"))
+        assert config.persist_dir == Path("/custom/vectors")
+
+
+class TestVectorPersistDirDerivation:
+    """Tests for vector persist_dir derivation from OSAPaths."""
+
+    def test_persist_dir_derived_from_osa_data_dir(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Vector persist_dir should derive from OSA_DATA_DIR when set."""
+        monkeypatch.setenv("OSA_DATA_DIR", "/data")
+
+        paths = OSAPaths()
+
+        # Verify paths derives vectors_dir correctly
+        assert paths.vectors_dir == Path("/data/data/vectors")
+
+    def test_persist_dir_derived_from_xdg_defaults(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Vector persist_dir should derive from XDG defaults when OSA_DATA_DIR not set."""
+        monkeypatch.delenv("OSA_DATA_DIR", raising=False)
+        # Patch Path.home() to use a test path
+        test_home = Path("/test/home")
+        monkeypatch.setattr(Path, "home", lambda: test_home)
+
+        paths = OSAPaths()
+
+        # Should derive vectors path from XDG data directory
+        expected_path = test_home / ".local" / "share" / "osa" / "vectors"
+        assert paths.vectors_dir == expected_path
+
+    def test_persist_dir_with_tmp_path(
+        self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+    ) -> None:
+        """Vector persist_dir should work with actual tmp directories."""
+        monkeypatch.setenv("OSA_DATA_DIR", str(tmp_path))
+
+        paths = OSAPaths()
+        paths.ensure_directories()
+
+        # Verify the vectors directory exists
+        assert paths.vectors_dir.exists()
+        assert paths.vectors_dir == tmp_path / "data" / "vectors"