# Read-Only Guarantee

## Principle

LLMHosts operates in **read-only mode** with respect to your inference engines and system configuration. We discover and use what's already running — we never change it.

## What LLMHosts Does

### Discovery (Read-Only)
- **GET** requests to Ollama API (`/api/tags`, `/api/show`) to list available models
- **GET** requests to vLLM endpoints to enumerate models
- **System reads** for GPU detection (reads `/proc`, `nvidia-smi`, `lspci` output)
- **Network scans** for mDNS service discovery on local network

### Proxy (Pass-Through)
- Forwards inference requests to your existing engines unchanged
- Returns responses with added metadata headers (`X-Request-ID`, `X-LLMHosts-Cost`, `X-LLMHosts-Model`)
- Never modifies the request payload sent to backends

## What LLMHosts Never Does

- Install, update, or remove models on Ollama or any inference engine
- Modify Ollama, vLLM, or any engine's configuration files
- Change system settings (GPU drivers, CUDA config, network settings)
- Write to any directory outside `~/.llmhosts/` (its own config/cache directory)
- Modify Docker containers or their configurations
- Change firewall rules or network settings
- Install system packages

## API Calls Enumerated

Every external API call LLMHosts makes during discovery:

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `{ollama_host}/api/tags` | GET | List available models |
| `{ollama_host}/api/show` | POST | Get model details (read-only metadata query) |
| `{ollama_host}/api/ps` | GET | List running models |
| `{ollama_host}/api/version` | GET | Get Ollama version |
| `{vllm_host}/v1/models` | GET | List vLLM models |
| `{vllm_host}/health` | GET | Check vLLM health |

During inference proxying:

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `{backend}/v1/chat/completions` | POST | Forward chat completion request |
| `{backend}/v1/messages` | POST | Forward Anthropic-format request |
| `{backend}/v1/models` | GET | List models for client |
| Cloud APIs (OpenAI, Anthropic, etc.) | POST | Forward requests when using BYOK cloud keys |

## Verification

Use `--dry-run` to see exactly what LLMHosts discovers without starting any services:

```bash
# See what serve would discover
llmhosts serve --dry-run

# See what up would provision
llmhosts up --dry-run
```

## Data Storage

LLMHosts stores its own data in `~/.llmhosts/`:
- `config.toml` — User configuration
- `keys.db` — Encrypted API key storage
- `cache/` — Semantic cache data
- `audit.db` — Request audit log

No data is written outside this directory.
