stemedb/.claude/guides/services/aphoria-hosted-mode.md

# Configure Aphoria Hosted Mode

**When to use:** Setting up Aphoria for team-wide observation aggregation via a central StemeDB server.

> **What syncs today vs what doesn't:**
> - **Observations** -- synced to hosted StemeDB via `push_observations()`. Working.
> - **Patterns** -- synced to hosted StemeDB via `push_patterns()`. Working.
> - **Claims** -- stored locally in `claims.toml` only. No `push_claims()` exists. Claims never leave the local machine.
> - **Extractors** -- stored locally in `.aphoria/extractors/*.toml` only. No `push_extractors()` exists.
>
> Claim and extractor sync are tracked in the gap closure roadmap (Phases 1-3).

## Prerequisites

- Aphoria installed (`cargo install --path applications/aphoria`)
- A running StemeDB server (for the team)
- Network access to the server

## Quick Start

```toml
# aphoria.toml
[hosted]
url = "https://episteme.acme.corp"
```

That's it. Observations now sync automatically on every scan.

## Architecture

```
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│ Developer A  │  │ Developer B  │  │ Developer C  │
│ aphoria scan │  │ aphoria scan │  │ aphoria scan │
└──────┬───────┘  └──────┬───────┘  └──────┬───────┘
       │                 │                 │
       └─────────────────┼─────────────────┘
                         ▼
              ┌─────────────────────┐
              │ Team StemeDB Server │
              │ POST /v1/aphoria/   │
              │      observations   │
              └─────────────────────┘
```

## Configuration Options

### Minimal (recommended for most teams)

```toml
[project]
name = "billing-service"

[hosted]
url = "https://episteme.acme.corp"
```

### Full Configuration

```toml
[project]
name = "billing-service"

[hosted]
url = "https://episteme.acme.corp"    # Required: enables hosted mode
project_id = "billing-api"             # Optional: defaults to [project.name]
team_id = "platform-team"              # Optional: for multi-team servers
sync_mode = "remote-only"              # "remote-only" | "local-and-remote"
offline_fallback = "skip"              # "skip" | "fail" | "queue"
api_key_env = "APHORIA_API_KEY"        # Env var containing auth token
max_retries = 3                        # Retry attempts on failure
retry_delay_ms = 1000                  # Delay between retries
```

## Sync Modes

| Mode | Description | When to Use |
|------|-------------|-------------|
| `remote-only` | Only push to server, no local storage | Single source of truth (default) |
| `local-and-remote` | Store locally AND push to server | Need local history for debugging |

## Offline Handling

| Mode | Behavior | When to Use |
|------|----------|-------------|
| `skip` | Warn and continue scan | Don't block developers (default) |
| `fail` | Abort scan with error | CI/CD where sync is mandatory |
| `queue` | Queue for later (not implemented) | Future offline support |

## Authentication

If your server requires authentication:

```bash
# Set the API key
export APHORIA_API_KEY="your-secret-token"
```

```toml
[hosted]
url = "https://episteme.acme.corp"
api_key_env = "APHORIA_API_KEY"  # Reads from this env var
```

The client sends `Authorization: Bearer <token>` header.

## CI/CD Integration

### GitHub Actions

```yaml
- name: Aphoria Scan
  env:
    APHORIA_API_KEY: ${{ secrets.APHORIA_API_KEY }}
  run: aphoria scan --staged --exit-code
```

### Pre-commit Hook

```bash
#!/bin/sh
# .git/hooks/pre-commit
aphoria scan --staged --exit-code
```

With hosted mode configured, observations sync automatically.

## Verifying Setup

```bash
# Check config is loaded
aphoria status

# Test with verbose output
RUST_LOG=aphoria=debug aphoria scan --persist --sync

# Expected log: "Pushed N observations to hosted server"
```

## Server Setup

Start a StemeDB server:

```bash
# Local testing
cargo run -p stemedb-api -- --bind 127.0.0.1:18180

# Production (with persistence)
stemedb-api --bind 0.0.0.0:18180 --data-dir /var/lib/stemedb
```

The server exposes `POST /v1/aphoria/observations` for receiving observations.

## Troubleshooting

### "Hosted sync failed, continuing"

Server is unreachable. Check:
- URL is correct
- Server is running
- Network/firewall allows connection

### "Failed to sync to hosted server" (error)

You have `offline_fallback = "fail"`. Either:
- Fix the connection issue
- Change to `offline_fallback = "skip"` temporarily

### Observations not appearing on server

Check:
1. `url` is set in `[hosted]` section
2. Scan finds novel claims (no authority conflicts)
3. Server logs show incoming requests

## Related

- [Aphoria Roadmap](../../../applications/aphoria/roadmap.md) - Phase 4E details
- [ai-lookup: Aphoria Config](../../../ai-lookup/features/aphoria-config.md) - Config reference
- [API Endpoints Guide](../backend/api-endpoints.md) - Adding new endpoints