# Aphoria Configuration

**Last Updated:** 2026-02-04
**Confidence:** High

## Summary

Aphoria uses `aphoria.toml` for project-level configuration. Two key sections handle where observations are stored: `[episteme]` for local storage and `[hosted]` for team server sync. When `[hosted].url` is set, observations automatically sync to the team's StemeDB server.

**Key Facts:**
- Config file: `aphoria.toml` at project root
- Local storage: `[episteme].data_dir` (default: `~/.aphoria/db`)
- Hosted mode: `[hosted].url` enables team aggregation
- Sync is implicit when hosted mode is configured (no `--sync` needed)
- `sync_mode`: `remote-only` (default) or `local-and-remote`

**File Pointer:** `applications/aphoria/src/config.rs:1-400`

## Configuration Sections

### Project Identity

```toml
[project]
name = "my-service"     # Auto-detected if not set
language = "rust"       # Auto-detected if not set
```

### Local Storage (`[episteme]`)

```toml
[episteme]
data_dir = "~/.aphoria/db"    # Local Episteme storage
url = "http://localhost:18180" # Remote Episteme (future)
```

**File Pointer:** `applications/aphoria/src/config.rs:68-83`

### Hosted Mode (`[hosted]`)

Enables team-wide observation aggregation:

```toml
[hosted]
url = "https://episteme.acme.corp"  # Enables hosted mode
project_id = "billing-service"       # 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 for auth token
max_retries = 3                      # HTTP retry attempts
retry_delay_ms = 1000                # Delay between retries
```

**File Pointer:** `applications/aphoria/src/config.rs:298-380`

### Sync Mode Options

| Mode | Local Storage | Remote Push | Use Case |
|------|---------------|-------------|----------|
| `remote-only` | No | Yes | Teams want single source of truth |
| `local-and-remote` | Yes | Yes | Need local history + team sync |

### Offline Fallback Options

| Mode | Behavior | Use Case |
|------|----------|----------|
| `skip` | Warn and continue | Don't block developers |
| `fail` | Error and abort | CI/CD mandatory sync |
| `queue` | Queue for later (not implemented) | Future offline support |

## Server Endpoint

Hosted clients POST to `/v1/aphoria/observations`:

**File Pointer:** `crates/stemedb-api/src/handlers/aphoria.rs:340-430`

## Related Topics

- [Aphoria Roadmap](../../applications/aphoria/roadmap.md) - Phase 4E details
- [API Surface](./api.md) - HTTP API reference