321 lines
12 KiB
Markdown
321 lines
12 KiB
Markdown
# 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)
|
|
|
|
---
|
|
|
|
## 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_GUILD_ID` | Discord guild/server ID |
|
|
| `DISCORD_GATEWAY_URL` | Gateway URL for Discord plugin to call (default: `http://localhost:14242`) |
|
|
| `TELEGRAM_BOT_TOKEN` | Telegram bot token (enables Telegram plugin) |
|
|
| `TELEGRAM_GATEWAY_URL` | Gateway URL for Telegram plugin to call |
|
|
|
|
### 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 |
|