# Mosaic Stack — Admin Guide

## Table of Contents

1. [User Management](#user-management)
2. [System Health Monitoring](#system-health-monitoring)
3. [Provider Configuration](#provider-configuration)
4. [MCP Server Configuration](#mcp-server-configuration)
5. [Environment Variables Reference](#environment-variables-reference)
6. [Local Fleet Canary](./fleet-local-canary.md)

---

## User Management

Admins access user management at `/admin` in the web dashboard. All admin
endpoints require a session with `role = admin`.

### Creating a User

**Via the web admin panel:**

1. Navigate to `/admin`.
2. Click **Create User**.
3. Enter name, email, password, and role (`admin` or `member`).
4. Submit.

**Via the API:**

```http
POST /api/admin/users
Content-Type: application/json

{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "password": "securepassword",
  "role": "member"
}
```

Passwords are hashed by BetterAuth before storage. Passwords are never stored in
plaintext.

### Roles

| Role     | Permissions                                                           |
| -------- | --------------------------------------------------------------------- |
| `admin`  | Full access: user management, health, all agent tools                 |
| `member` | Standard user access; agent tool set restricted by `AGENT_USER_TOOLS` |

### Updating a User's Role

```http
PATCH /api/admin/users/:id/role
Content-Type: application/json

{ "role": "admin" }
```

### Banning and Unbanning

Banned users cannot sign in. Provide an optional reason:

```http
POST /api/admin/users/:id/ban
Content-Type: application/json

{ "reason": "Violated terms of service" }
```

To lift a ban:

```http
POST /api/admin/users/:id/unban
```

### Deleting a User

```http
DELETE /api/admin/users/:id
```

This permanently deletes the user. Related data (sessions, accounts) is
cascade-deleted. Conversations and tasks reference the user via `owner_id`
which is set to `NULL` on delete (`set null`).

---

## System Health Monitoring

The health endpoint is available to admin users only.

```http
GET /api/admin/health
```

Sample response:

```json
{
  "status": "ok",
  "database": { "status": "ok", "latencyMs": 2 },
  "cache": { "status": "ok", "latencyMs": 1 },
  "agentPool": { "activeSessions": 3 },
  "providers": [{ "id": "ollama", "name": "ollama", "available": true, "modelCount": 3 }],
  "checkedAt": "2026-03-15T12:00:00.000Z"
}
```

`status` is `ok` when both database and cache pass. It is `degraded` when either
service fails.

The web admin panel at `/admin` polls this endpoint and renders the results in a
status dashboard.

---

## Provider Configuration

Providers are configured via environment variables and loaded at gateway startup.
No restart-free hot reload is supported; the gateway must be restarted after
changing provider env vars.

### Ollama

Set `OLLAMA_BASE_URL` (or the legacy `OLLAMA_HOST`) to the base URL of your
Ollama instance:

```env
OLLAMA_BASE_URL=http://localhost:11434
```

Specify which models to expose (comma-separated):

```env
OLLAMA_MODELS=llama3.2,codellama,mistral
```

Default when unset: `llama3.2,codellama,mistral`.

The gateway registers Ollama models using the OpenAI-compatible completions API
(`/v1/chat/completions`).

### Custom Providers (OpenAI-compatible APIs)

Any OpenAI-compatible API (LM Studio, llama.cpp HTTP server, etc.) can be
registered via `MOSAIC_CUSTOM_PROVIDERS`. The value is a JSON array:

```env
MOSAIC_CUSTOM_PROVIDERS='[
  {
    "id": "lmstudio",
    "name": "LM Studio",
    "baseUrl": "http://localhost:1234",
    "models": ["mistral-7b-instruct"]
  }
]'
```

Each entry must include:

| Field     | Required | Description                         |
| --------- | -------- | ----------------------------------- |
| `id`      | Yes      | Unique provider identifier          |
| `name`    | Yes      | Display name                        |
| `baseUrl` | Yes      | API base URL (no trailing slash)    |
| `models`  | Yes      | Array of model ID strings to expose |
| `apiKey`  | No       | API key if required by the endpoint |

### Testing Provider Connectivity

From the web admin panel or settings page, click **Test** next to a provider.
This calls:

```http
POST /api/agent/providers/:id/test
```

The response includes `reachable`, `latencyMs`, and optionally
`discoveredModels`.

---

## MCP Server Configuration

The gateway can connect to external MCP (Model Context Protocol) servers and
expose their tools to agent sessions.

Set `MCP_SERVERS` to a JSON array of server configurations:

```env
MCP_SERVERS='[
  {
    "name": "my-tools",
    "url": "http://localhost:3001/mcp",
    "headers": {
      "Authorization": "Bearer my-token"
    }
  }
]'
```

Each entry:

| Field     | Required | Description                         |
| --------- | -------- | ----------------------------------- |
| `name`    | Yes      | Unique server name                  |
| `url`     | Yes      | MCP server URL (`/mcp` endpoint)    |
| `headers` | No       | Additional HTTP headers (e.g. auth) |

On gateway startup, each configured server is connected and its tools are
discovered. Tools are bridged into the Pi SDK tool format and become available
in agent sessions.

The gateway itself also exposes an MCP server endpoint at `POST /mcp` for
external clients. Authentication requires a valid BetterAuth session (cookie or
`Authorization` header).

---

## Environment Variables Reference

### Required

| Variable             | Description                                                                               |
| -------------------- | ----------------------------------------------------------------------------------------- |
| `BETTER_AUTH_SECRET` | Secret key for BetterAuth session signing. Must be set or gateway will not start.         |
| `DATABASE_URL`       | PostgreSQL connection string. Default: `postgresql://mosaic:mosaic@localhost:5433/mosaic` |

### Gateway

| Variable              | Default                  | Description                                    |
| --------------------- | ------------------------ | ---------------------------------------------- |
| `GATEWAY_PORT`        | `14242`                  | Port the gateway listens on                    |
| `GATEWAY_CORS_ORIGIN` | `http://localhost:3000`  | Allowed CORS origin for browser clients        |
| `BETTER_AUTH_URL`     | `http://localhost:14242` | Public URL of the gateway (used by BetterAuth) |

### SSO (Optional)

| Variable                    | Description                                                                  |
| --------------------------- | ---------------------------------------------------------------------------- |
| `AUTHENTIK_CLIENT_ID`       | Authentik OAuth2 client ID                                                   |
| `AUTHENTIK_CLIENT_SECRET`   | Authentik OAuth2 client secret                                               |
| `AUTHENTIK_ISSUER`          | Authentik OIDC issuer URL                                                    |
| `AUTHENTIK_TEAM_SYNC_CLAIM` | Optional claim used to derive team sync data (defaults to `groups`)          |
| `WORKOS_CLIENT_ID`          | WorkOS OAuth client ID                                                       |
| `WORKOS_CLIENT_SECRET`      | WorkOS OAuth client secret                                                   |
| `WORKOS_ISSUER`             | WorkOS OIDC issuer URL                                                       |
| `WORKOS_TEAM_SYNC_CLAIM`    | Optional claim used to derive team sync data (defaults to `organization_id`) |
| `KEYCLOAK_CLIENT_ID`        | Keycloak OAuth client ID                                                     |
| `KEYCLOAK_CLIENT_SECRET`    | Keycloak OAuth client secret                                                 |
| `KEYCLOAK_ISSUER`           | Keycloak realm issuer URL                                                    |
| `KEYCLOAK_TEAM_SYNC_CLAIM`  | Optional claim used to derive team sync data (defaults to `groups`)          |
| `KEYCLOAK_SAML_LOGIN_URL`   | Optional SAML login URL used when OIDC is unavailable                        |

Each OIDC provider requires its client ID, client secret, and issuer URL together. If only part of a provider configuration is set, gateway startup logs a warning and that provider is skipped. Keycloak can fall back to SAML when `KEYCLOAK_SAML_LOGIN_URL` is configured.

### Agent

| Variable                 | Default         | Description                                             |
| ------------------------ | --------------- | ------------------------------------------------------- |
| `AGENT_FILE_SANDBOX_DIR` | `process.cwd()` | Root directory for file/git/shell tool access           |
| `AGENT_SYSTEM_PROMPT`    | —               | Platform-level system prompt injected into all sessions |
| `AGENT_USER_TOOLS`       | all tools       | Comma-separated allowlist of tools for non-admin users  |

### Providers

| Variable                  | Default                      | Description                                      |
| ------------------------- | ---------------------------- | ------------------------------------------------ |
| `OLLAMA_BASE_URL`         | —                            | Ollama API base URL                              |
| `OLLAMA_HOST`             | —                            | Alias for `OLLAMA_BASE_URL` (legacy)             |
| `OLLAMA_MODELS`           | `llama3.2,codellama,mistral` | Comma-separated Ollama model IDs                 |
| `MOSAIC_CUSTOM_PROVIDERS` | —                            | JSON array of custom OpenAI-compatible providers |

### Memory and Embeddings

| Variable                | Default                     | Description                                          |
| ----------------------- | --------------------------- | ---------------------------------------------------- |
| `OPENAI_API_KEY`        | —                           | API key for OpenAI embedding and summarization calls |
| `EMBEDDING_API_URL`     | `https://api.openai.com/v1` | Base URL for embedding API                           |
| `EMBEDDING_MODEL`       | `text-embedding-3-small`    | Embedding model ID                                   |
| `SUMMARIZATION_API_URL` | `https://api.openai.com/v1` | Base URL for log summarization API                   |
| `SUMMARIZATION_MODEL`   | `gpt-4o-mini`               | Model used for log summarization                     |
| `SUMMARIZATION_CRON`    | `0 */6 * * *`               | Cron schedule for log summarization (every 6 hours)  |
| `TIER_MANAGEMENT_CRON`  | `0 3 * * *`                 | Cron schedule for log tier management (daily at 3am) |

### MCP

| Variable      | Description                                      |
| ------------- | ------------------------------------------------ |
| `MCP_SERVERS` | JSON array of external MCP server configurations |

### Plugins

| Variable                      | Description                                                                                                                               |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `DISCORD_BOT_TOKEN`           | Discord bot token (enables Discord plugin)                                                                                                |
| `DISCORD_SERVICE_TOKEN`       | Required high-entropy service credential used to authenticate and sign Discord ingress; inject through the approved secret mechanism only |
| `DISCORD_SERVICE_USER_ID`     | Required Mosaic service-principal user ID that owns persisted Discord conversations; the original Discord user ID remains audit metadata  |
| `DISCORD_GUILD_ID`            | Discord guild/server ID                                                                                                                   |
| `DISCORD_GATEWAY_URL`         | Gateway URL for Discord plugin to call (default: `http://localhost:14242`)                                                                |
| `DISCORD_ALLOWED_GUILD_IDS`   | Required comma-separated Discord guild snowflake allowlist; default-deny                                                                  |
| `DISCORD_ALLOWED_CHANNEL_IDS` | Required comma-separated Discord channel snowflake allowlist; default-deny                                                                |
| `DISCORD_ALLOWED_USER_IDS`    | Required comma-separated Discord user snowflake allowlist; default-deny                                                                   |
| `TELEGRAM_BOT_TOKEN`          | Telegram bot token (enables Telegram plugin)                                                                                              |
| `TELEGRAM_GATEWAY_URL`        | Gateway URL for Telegram plugin to call                                                                                                   |

### Discord ingress security

When `DISCORD_BOT_TOKEN` is configured, `DISCORD_SERVICE_TOKEN`, `DISCORD_SERVICE_USER_ID`, and all three Discord allowlists are required. Gateway startup fails rather than enabling a broad or unauthenticated remote-control surface. The service user ID identifies a provisioned Mosaic service principal for persistence; the original Discord user ID is retained in ingress audit metadata. The service token is a secret supplied by the approved runtime secret mechanism and is never committed or logged.

Inbound Discord messages must originate from an allowed guild, channel, and user, mention the bot, and carry a signed envelope containing the native Discord message ID and a generated correlation ID. The gateway validates the service identity, envelope signature, and allowlists again before dispatching. Replayed Discord message IDs are rejected during the bounded ingress replay window. Durable inbox/idempotency retention is introduced with Tess durable state.

### Session retention and garbage collection

Session cleanup is scoped to one session identifier and only removes that session's Valkey keys and demotes that session's hot logs. Gateway startup and scheduled jobs do not perform global session cleanup; startup removes legacy repeatable `session-gc` schedules created by older deployments. The `/gc` command is intentionally disabled until a distinct global-retention job supplies explicit authorization and audit evidence. This prevents one tenant or session's cleanup from changing another's retained data.

### Observability

| Variable                      | Default                 | Description                      |
| ----------------------------- | ----------------------- | -------------------------------- |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4318` | OpenTelemetry collector endpoint |
| `OTEL_SERVICE_NAME`           | `mosaic-gateway`        | Service name in traces           |

### Web App

| Variable                  | Default                  | Description                            |
| ------------------------- | ------------------------ | -------------------------------------- |
| `NEXT_PUBLIC_GATEWAY_URL` | `http://localhost:14242` | Gateway URL used by the Next.js client |

### Coordination

| Variable                | Default                       | Description                                |
| ----------------------- | ----------------------------- | ------------------------------------------ |
| `MOSAIC_WORKSPACE_ROOT` | monorepo root (auto-detected) | Root path for mission workspace operations |
