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
6. Local Fleet Canary

---

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_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
DISCORD_INTERACTION_BINDINGS	Required JSON bindings from guild/channel to logical agent and paired Discord users with viewer, operator, or admin roles
DISCORD_MESSAGE_RATE_LIMIT_PER_MINUTE	Optional positive integer; authorized turns per guild/channel/user each minute (default: 30)
DISCORD_THREAD_RATE_LIMIT_PER_MINUTE	Optional positive integer; mention-thread routes per guild/channel/user each minute (default: 5)
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 and configured parent channel, come from an allowed and paired user whose role permits sending, and carry a signed envelope containing the native Discord message ID and a generated correlation ID. Attachment references are limited in count, metadata size, field length, and declared size; only query-free HTTPS URLs without credentials or fragments are accepted, so bearer or presigned URLs never reach persistence or an agent prompt. The gateway validates the service identity, envelope signature, allowlists, pairing, and role 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.

Configured channels are dedicated agent interaction surfaces. An authorized untagged message routes to the bound logical agent and the response returns in that channel. Mentioning the bot on a normal channel message creates a public Discord thread, or reuses the thread already attached to that same message; the response and later thread messages stay in that thread without repeated mentions. A normal channel's category is not an authorization parent—only a Discord thread inherits authorization from its configured parent channel. Runtime control commands such as /approve and /stop <approval> remain on the current channel/thread because they target that durable session rather than opening a new topic.

Authorization and per-user/channel rate limits are evaluated before thread creation, so an unlisted guild/channel/user, unpaired user, viewer, or rate-limited sender cannot create bot threads or dispatch gateway work. The bot needs Discord permissions to view/send in configured channels and create/send in public threads. If thread creation fails, the turn is not dispatched because the requested response destination cannot be honored.

Conversation handles use the configured logical agent plus Discord channel/thread identity. They do not contain a Claude, Codex, Pi, OpenCode, model, process, or runtime-provider identifier; changing the runtime behind the logical session therefore does not require reconnecting the Discord bot.

Interaction binding format

DISCORD_INTERACTION_BINDINGS must be a non-empty JSON array. Each item requires instanceId, trusted agentConfigId, guildId, channelId, and a non-empty pairedUsers object. instanceId is the configured logical-agent name; its trusted database agentConfigId must resolve to an agent configuration with exactly that name, preserving provider/model/prompt/tool selection per binding. The guild/channel must also appear in their corresponding allowlists. IDs below are placeholders:

[
  {
    "instanceId": "interaction-agent",
    "agentConfigId": "agent-config-id",
    "guildId": "guild-id",
    "channelId": "channel-id",
    "pairedUsers": {
      "discord-user-id": {
        "role": "operator",
        "mosaicUserId": "mosaic-user-id"
      }
    }
  }
]

Pairing role	Send message	Create/continue thread	Approve	Stop
viewer	No	No	No	No
operator	Yes	Yes	No	No
admin	Yes	Yes	Yes	Yes

A legacy role-only value such as "discord-user-id": "operator" remains valid for non-privileged ingress. Approval and stop require the object form with a provisioned mosaicUserId; gateway policy checks that Mosaic identity and consumes one exact-action approval once. Do not make the Discord service principal an approving administrator.

After changing bindings or allowlists, restart the gateway/plugin through the normal service manager and verify both Discord and gateway connectivity. The adapter reports connected only when both links are ready, degraded when one is ready, and disconnected when neither is ready. Test one authorized untagged channel turn, one mention-created thread, one thread follow-up, and one unauthorized user denial without using production credential values in logs or evidence.

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