stack/docs/guides/admin-guide.md

Mosaic Stack — Admin Guide

Table of Contents

1. User Management
2. System Health Monitoring
3. Provider Configuration
4. MCP Server Configuration
5. 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:

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

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

{ "role": "admin" }

Banning and Unbanning

Banned users cannot sign in. Provide an optional reason:

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

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

To lift a ban:

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

Deleting a User

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.

GET /api/admin/health

Sample response:

{
  "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:

OLLAMA_BASE_URL=http://localhost:11434

Specify which models to expose (comma-separated):

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:

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:

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:

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