Site Settings

Site settings determine the logged-out pages, authentication flow, resource limits, and runtime policies. Only users with the corresponding admin:settings:* permissions or super administrator status can see the matching tabs.

Accessing System Settings

1. Log in as administrator.
2. Navigate to Admin → Site Settings (Settings section in the sidebar).
3. Choose a category from the settings sub-navigation.

Settings categories:

• General (/site-settings)
• Security (/site-settings/security)
• Notifications (/site-settings/notifications)
• Storage (/site-settings/storage)
• Memory (/site-settings/memory)
• SSO (/site-settings/sso)

Settings are stored as key-value site settings and exposed through GET /api/v1/admin/site-settings (single key: GET/PUT /api/v1/admin/site-settings/{key}, bulk update: PUT /api/v1/admin/site-settings). Viewing requires admin:settings:read; updating requires admin:settings:update.

General Settings

Site Information

Configure site name, URL, description, icon, default language, and authentication page layout:

Update site information: Navigate to Settings → General, update fields, and click Save Changes.

Theme and Display

Configure theme mode, primary color, branding display, and interface elements:

Additional theme tokens (primary foreground, background, card, sidebar, navbar, accent, chart colors, etc.) can also be customized.

Update branding: Navigate to Settings → General, adjust theme mode and color tokens, and click Save Changes.

Language Settings

Configure site default language and multilingual support:

Users can switch the interface language in their personal settings. After switching, interface text and notification messages use the corresponding language translation.

Legal & Compliance

Configure ICP record, terms of service, and privacy policy:

Terms and privacy entries are shown only when enabled and a URL or text is provided. Registration acceptance is enforced only when require_terms_acceptance_on_register is true.

Security Settings

Registration

Configure registration, approval, email verification, and account deletion policies:

Password Policy

Configure password complexity requirements:

Password expiration configuration:

Session Settings

Configure session timeout, login attempt limits, and CAPTCHA:

Two-Factor Authentication

Admin TOTP statistics and per-user status/disable endpoints are available under /api/v1/admin/totp.

Human Verification

Once enabled, password logins must carry a one-time verification credential (captcha_id + captcha_token): the front end first calls POST /api/v1/login/captcha/click to exchange a valid click interaction for a private one-time proof, then submits it with the login. A missing credential raises captcha_required; a failed check raises captcha_invalid.

Model Endpoint Allowlist

Before saving or testing a model with a new API endpoint:

1. Navigate to Settings → Security.
2. Add the endpoint Origin to Model Endpoint Allowlist, one per line.
3. Include only the scheme, hostname, and non-default port, for example https://gateway.example.com or http://ollama.internal:11434.
4. Save the Security settings, then save or test the model again.

Matching is exact. URL paths are ignored, but the scheme, hostname, and port must all match. Removing an Origin blocks subsequent model discovery, connection tests, and runtime requests without restarting the service. The default allowlist ships with 20 known provider origins (e.g. https://api.openai.com, https://api.anthropic.com, http://localhost:11434) and stores at most 200 entries.

Outbound Network Allowlist (SSRF Exemption)

Clouisle applies one shared SSRF check to custom HTTP tools, workflow HTTP request nodes, knowledge base URL imports, and database tool connection tests: the host is resolved to IPs first, and any resolved IP falling into the private (is_private) / loopback (is_loopback) / link-local (is_link_local) / reserved (is_reserved) / multicast (is_multicast) / unspecified (is_unspecified) categories is rejected. Typical members: 127.0.0.1, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.169.254, fe80::/10, 0.0.0.0, ::, and the hostnames localhost, local, metadata.google.internal.

To call internal APIs, microservices, or intranet databases, add the approved targets one per line under Settings → Security → Outbound Network Allowlist (SSRF Exemption) (setting key ssrf_allowed_targets, a JSON array):

Other constraints and behaviour:

• The allowlist holds at most 200 entries; duplicates are de-duplicated. Hostnames without a . (such as localhost) cannot be an entry — use an IP or CIDR instead.
• An empty allowlist blocks every internal target — that is the default posture. The wider you open it, the easier tools and workflows become an intranet-probing pivot.
• Validation re-reads the setting and resolves the host on every request, so changes take effect immediately with no restart.
• The Fake-IP benchmark pool 198.18.0.0/15 (Clash/Surge/Mihomo TUN mode) is automatically allowed so public domains are not falsely flagged as SSRF.

Notification Settings

SMTP (Email)

Configure email sending:

Update SMTP settings: Navigate to Settings → Notifications, enter SMTP details, set sender name and address, click Test (POST /api/v1/admin/site-settings/test-email), then click Save Changes.

External Notification Channels

The following channels can be enabled and configured (each with its own settings page section and a test endpoint):

Auto Notifications

The Auto Notifications tab (GET/PUT /api/v1/admin/site-settings/auto-notifications) controls which event types create notifications and which external channels receive them. See Notifications & External Channels for details.

Email Templates

Notification Preferences

Notification delivery in Clouisle is configured globally by administrators — there is no per-user notification preference system. Individual users cannot customize which notifications they receive.

Note: Per-user preferences (email frequency/digests, per-type toggles, quiet hours / do-not-disturb, push notifications, notification grouping, priority levels, custom rules, and user webhook endpoints) are not implemented.

In-App Notifications

Every user sees their notifications in the notification center and at /app/notifications. Notifications are scoped as:

• global: visible to all users
• team: visible to members of the target team
• user: visible to a specific user

External Channels (Admin-Configured)

Administrators configure external delivery channels globally for automatic notification types. Available channels:

• Email (requires SMTP configuration)
• DingTalk
• WeChat
• Feishu
• Webhook (generic webhook)
• Slack

A channel only sends notifications when it is both selected in the global config and enabled/configured by the administrator. If no channels are configured, notifications stay in-app only.

What Administrators Can Configure

Administrators choose which automatic event types are enabled (enabled_types). By default the following types are enabled:

Additional types (e.g. workflow.run_success, agent.published, agent.unpublished, password.expiring) exist and can be enabled.

Admins configure this under Admin Dashboard → Site Settings → Notifications → Auto Notifications (and the corresponding channel tabs: Email, DingTalk, WeChat, Feishu, Webhook, Slack).

What Users Can Do

As a user you can:

• View notifications in the notification center and at /app/notifications
• Mark individual notifications as read
• Mark all notifications as read
• Filter the notification list (by type, level, scope, unread, and search)

See Notifications & External Channels for details.

Notification API

• GET /api/v1/notifications — list visible notifications (filters: scope, type, level, unread, search)
• GET /api/v1/notifications/unread-count — unread count
• POST /api/v1/notifications/read — mark notifications read (notification_ids or mark_all)
• Admin endpoints (/api/v1/admin/notifications) — create/delete notifications, manage auto-notification config

Best Practices

For users:

• Check the notification center regularly
• Review security notifications immediately

For administrators:

• Enable external channels only after configuring them (SMTP, DingTalk, etc.)
• Choose enabled types deliberately to avoid notification noise

Background Memory Extraction Settings

Memory (/site-settings/memory) queues extraction for pending user turns after the configured cooldown, or immediately when the pending-turn threshold is reached. The Agent must also have memory enabled; disabling either the Agent memory feature or the global switch prevents extraction tasks.

The extraction model falls back in this order: explicitly configured enabled model, the Agent's assigned model, the system default chat model, then the first available chat model. The cooldown debounces extraction; reaching the pending-turn threshold queues it immediately.

Storage Settings

File Storage

Configure storage backend and knowledge base upload size limits:

Update storage settings: Navigate to Settings → Storage, configure storage backend and max upload size, then click Save Changes.

Object Storage (S3-compatible)

Configure S3-compatible object storage:

Configure object storage: Navigate to Settings → Storage, enter the endpoint, bucket, region, access key, and secret key, configure path-style and HTTPS options, then click Save Changes.

Audit Log Retention

Logs older than the retention period are archived (manually triggered) to monthly JSON files under the archive path and then deleted. See Audit Log Management for details.

Audit Alerts (Not Wired Up)

The following five keys are seeded into the database at initialization, but no code reads them — there is no detection task and no delivery path, so configuring them produces no alerts:

For real security alerting, use the implemented path: the security.* events and external channels of Auto Notifications.

SSO Settings

Global SSO Behavior

Configured in Settings → Security (SSO section) or Settings → SSO:

SSO Providers

SSO providers are managed in Settings → SSO. Providers are created generically with a name and protocol — there is no preset picker (Google, GitHub, Azure AD, etc.); each provider's configuration and attribute mapping are entered manually. See SSO Configuration for the full guide.

Team Settings

Teams group users and resources (agents, workflows, and knowledge bases). Team admins manage members and basic team information; model authorization can only be changed by a superuser.

Note: Team slugs, visibility, invitation flows, join requests, member limits, per-team resource limits, per-team security/API settings, billing, data retention, custom domains, and branding are not implemented.

Accessing Team Management

There are two entry points with completely different permissions and capabilities:

Open them from the Team switcher: Manage All Teams (Admin) goes to /teams (shown only with admin:team:read) and Manage Current Team goes to /app/team (shown only with team:manage).

Team Information

Only three fields can be edited:

Note: There is no team slug — teams are identified by ID and referenced by name in the UI.

Model Authorization

Team model authorization can only be performed by a superuser. On /app/team → Model Authorization, a team admin or owner sees a read-only view: authorized models, enable state, and a "today's usage / limit" bar (limits are assigned by the system administrator; no limit means uncapped). Changing authorizations requires the team detail under /teams, which itself requires admin:team:read.

Only authorized models appear in the team's Agent and knowledge base model pickers.

Member Management

Members must already have Clouisle accounts; there is no email-invitation or join-request flow.

Adding Members

1. Open Manage Teams (/teams) and select a team.
2. Open the Members tab.
3. Click Add Member.
4. Choose an existing user and a role (Admin, Member, or Viewer — Owner cannot be assigned here).
5. Confirm.

Only the team Owner or Admin can add members. The Owner cannot add another member as Owner.

Changing Member Roles

1. Find the member in the member list
2. Choose "Change Role"
3. Select the new role (Admin, Member, or Viewer)

Only the team Owner can change member roles (except for the Owner themselves).

Removing Members

1. Find the member in the member list
2. Click "Remove"
3. Confirm

The Owner cannot be removed by other members.

Leaving a Team

1. Open Manage Teams (/teams) and select the team.
2. Open Members.
3. Confirm

The Owner cannot leave until ownership is transferred.

Transferring Ownership

1. Open Manage Teams (/teams) and select the team.
2. Open Members.
3. Confirm the transfer

The previous owner becomes an Admin, and the new owner gains full control.

Team Roles

Roles are fixed: Owner, Admin, Member, Viewer. There are no per-team custom roles. See Teams & Members for the full permission matrix.

What Does NOT Exist

The following team-level features are not implemented:

• Team slug / custom URL
• Team visibility (private/internal/public) and discovery
• Invitation expiry, require-approval, allowed email domains
• Member limits
• Resource limits (agents, KBs, workflows, conversations)
• Per-team password/2FA/session/IP policies
• Team API settings, API key policies, rate limits
• Billing / subscriptions / payment methods
• Data retention / export / deletion policies
• Audit alerts, custom domain, branding

See also:

• Teams & Members — Detailed team management guide
• Roles & Permissions — Roles and permissions

Rollout Settings (Private)

These keys live in the retrieval category with public=false: they are absent from the site-settings UI and from the public settings API, and exist for operators to control the staged rollout of hybrid retrieval:

Precedence: the environment variable RETRIEVAL_HYBRID_KILL_SWITCH=true wins over everything and disables hybrid retrieval; disabled turns it off globally; enabled turns it on globally; under rollout, a team matching the allowlist is enabled, otherwise the hash bucket < percentage decides.

Feature Flags and Other Settings

• Feature flags (enabling/disabling agents, workflows, KBs, etc.)
• Email templates
• Security headers (HSTS, CSP, X-Frame-Options)
• CORS configuration
• IP whitelisting
• API rate limiting
• Webhook configuration as a general system feature
• Third-party integrations (Salesforce, HubSpot, Slack apps, analytics like Google Analytics/Mixpanel)
• Maintenance mode
• Database pool / cache settings
• Settings export/import and reset-to-defaults workflows

Model endpoints are restricted via the Model Endpoint Allowlist (Security) instead of a global integration registry.

Key Defaults

Default public settings for a new site: site name Clouisle, centered authentication pages, theme follows system, icon and name displayed, registration allowed, email verification on, CAPTCHA off, SSO off, password login allowed, and knowledge base single-file upload 50MB.

When Changes Take Effect

Page settings usually affect the public site and subsequent requests immediately after saving; model endpoints, storage, and deployment environment variables are read by the server, so restart the relevant services according to your deployment after changing them. After saving, verify the login and sign-up pages in an incognito window.

Security Principles

• Store SECRET_KEY, SMTP passwords, SSO client secrets, object storage keys, and model API Keys only as server-side secrets.
• The allowlist matches against full Origins; an empty allowlist blocks model endpoints.
• Before enabling SSO-only, confirm at least one connection works and keep an administrator recovery path.
• Before changing the audit log retention days, confirm the archive path and backup policy.

See the Site settings reference for the field-level checklist.