AdminInterface

Admin Interface

The Admin Interface is the application-level control plane for a running Harpyx instance. It is separate from runtime configuration: .env, appsettings.json, Docker Compose variables, and Key Vault decide how the services start, while the Admin Interface changes platform data stored in SQL Server and used by the WebApp and Worker at runtime.

Use Configuration for instance bootstrapping and infrastructure connection settings. Use this page for the settings managed after the application is running.

Access

The Admin area is available only to platform administrators. Access is enforced through the AdminOnly policy and the same authenticated user model described in Authentication and Authorization.

Bootstrap administrators are created from SeedOptions:AdminUsers during startup. After bootstrap, day-to-day user and role management happens through the Admin Interface.

Main Sections

Section	Purpose
Overview	Entry point for platform administration
General Settings	Runtime platform settings stored in SQL Server
Usage Limits	Global caps and feature toggles
Hosted Models	Shared LLM catalog, including local/OpenAI-compatible endpoints
Users	Platform user management
Tenants	Tenant ownership, visibility, activation, and personal tenants
User Invitations	Invite-based onboarding
System Health	Human-readable dependency readiness and impact summary

General Settings

General Settings control platform behavior that can change without redeploying the instance.

They include:

• default system prompt;
• system/user prompt maximum lengths;
• prompt-history and chat-history sizes;
• user self-registration;
• upload quarantine;
• URL document ingestion;
• maximum upload size;
• container extraction limits;
• RAG runtime settings, such as top-K chunks, context length, RRF settings, candidate counts, keyword extraction, cache TTL, and OpenSearch fallback behavior.

These settings are stored in SQL Server and are read by application services at runtime. They should be treated as operational settings: changing them can affect ingestion, retrieval quality, chat behavior, upload acceptance, and user onboarding.

Usage Limits

Usage Limits define platform-level caps and feature availability.

They include limits for:

• tenants per user;
• workspaces per user;
• projects per workspace;
• permanent projects per workspace;
• temporary project lifetime;
• documents per workspace;
• storage per user, tenant, and workspace;
• LLM providers per user;
• OCR, RAG indexing, and API access.

Unlimited values are represented explicitly in the UI. When limits are enabled, services enforce them before creating or expanding the affected resource.

Hosted Models

Hosted Models expose a centrally managed LLM catalog to workspaces and projects. They are configured by platform admins and are useful when the instance should provide shared model access rather than relying only on user-provided API keys.

Harpyx supports two LLM configuration paths:

Path	Managed by	Typical use
Personal providers	Individual users	BYO credentials for managed cloud providers such as OpenAI, Anthropic Claude, or Google Gemini
Hosted models	Platform admins	Shared model catalog, including OpenAI-compatible endpoints and local/self-hosted model servers

Hosted models are stored as LlmConnection and LlmModel records and can be used by workspaces and projects for Chat, RAG Embedding, and OCR capabilities.

Use hosted models when the deployment should expose a centrally managed endpoint to users, for example:

• an OpenAI-compatible gateway;
• a local model server;
• a private inference endpoint inside the same network;
• a managed endpoint whose credentials should be owned by the platform rather than each user.

The endpoint must expose an API shape compatible with Harpyx's hosted model client. For local models, this usually means placing the model behind an OpenAI-compatible HTTP API or gateway.

The admin configures:

• provider/connection type;
• display name and description;
• base URL;
• API key or access token when required;
• one or more published models;
• each model capability: Chat, RAG Embedding, or OCR;
• model identifier and embedding dimensions where applicable.

Workspace and project settings then select whether each capability uses the inherited default, a specific hosted model, a user personal provider, or is disabled.

For RAG embeddings, all documents in a project must use a compatible embedding model and vector dimension. Changing the effective RAG embedding model resets the project index and triggers asynchronous reindexing so stored vectors stay compatible with future queries.

Operational notes:

• Local model endpoints should be reachable from both Harpyx.WebApp and Harpyx.Worker.
• Docker deployments often need container-network addresses rather than localhost.
• If the endpoint is on the Docker host, use a host-reachable name such as host.docker.internal where supported by the deployment.
• Protect local endpoints with network rules and credentials; treat them as production services.
• For GDPR-sensitive deployments, local models can reduce external transfers, but prompts, chunks, and generated responses still remain personal data when they contain personal information.

Users and Tenants

The Users section manages platform users, activation state, global role, provider identifiers, and tenant memberships.

The Tenants section manages tenant records, activation state, public visibility, owner assignment, and personal-tenant metadata. Platform admins bypass tenant-level checks, but tenant ownership and membership still matter for normal users and API keys.

Use these sections for operational maintenance after bootstrap. Use SeedOptions:AdminUsers only for initial administrator provisioning.

User Invitations

The User Invitations section supports invite-based onboarding. Admins can create invitations with scope, expiration, and tenant assignment where required.

This is the preferred path when user self-registration is disabled. The General Settings page indicates when new users must be invited rather than self-registering.

System Health

The System Health page shows a human-readable readiness snapshot for required and optional dependencies, including operational impact. It complements the machine-readable health endpoints used by orchestration and monitoring.

Health checks do not change application behavior; they help admins quickly identify degraded dependencies such as SQL Server, MinIO, RabbitMQ, Redis, OpenSearch, ClamAV, or external services.