Configuration

Configuration is the central settings page for your organisation, organised into eleven tabs. This is where you set deployment-level URLs, branding, default models, SSO, ambient context, memory, voice features, and roles.

Find it at Admin → Organisation → Settings → Configuration in the sidebar.

Inheritance: every setting on this page can either inherit from the platform-wide default, or override it for this organisation. The header banner reminds you of the inheritance order: Organisation → Partner → Platform. Keep inheritance on for most fields, then override only the values you specifically need to change for your organisation.

The eleven tabs are documented below in the same order they appear in the UI.

1. Deployment

Defines deployment-level URL defaults used across PebbleAI services.

What you set here

• UI Allowed Hosts — additional hostnames PebbleAI’s UI will serve from (under the Advanced disclosure). Useful when you have a custom domain or alternate access URL beside the default.

Step-by-step: adding a custom UI hostname

1. Open the Advanced section
2. Add the hostname (e.g. pebbleai.acme-corp.internal)
3. Click Save Settings

Most organisations using the default URL won’t need to touch this tab.

2. OAuth

Configures the OAuth callback base URL used when integrations (Microsoft 365, Google Workspace, etc.) redirect back to PebbleAI after the user authenticates.

What you set here

• OAuth External Callback Base URL — the public URL of your PebbleAI install (e.g. https://demo.pebblecloud.io/oauth/callback)
• Value Source — Override for this organisation, or inherit from platform
• Advanced OAuth Debug & Scope Controls — diagnostic toggles for tracing OAuth flows
• Reset OAuth Registration — reset stored OAuth registration for a specific integration (e.g. Google Workspace) when something has gone wrong and you need to re-register from scratch

Step-by-step: setting the callback URL

1. Enter the public-facing PebbleAI base URL plus /oauth/callback
2. Set Value Source to Override for this organisation
3. Click Save OAuth Settings

The Effective value below the field shows what’s currently in effect after inheritance.

Step-by-step: resetting an OAuth registration

1. Pick the integration from the dropdown (e.g. Google Workspace)
2. Click Reset OAuth Registration
3. Confirm

Use this when an integration’s stored client ID/secret or scopes are out of sync with the provider and you need PebbleAI to forget what it knows and start over.

3. Email

Configures the SMTP server PebbleAI uses to send transactional emails — invitations, password resets, alerts.

What you set here

• Enable Email Integration — global on/off
• Email source on SMTP setup name
• SMTP host, SMTP port — the server PebbleAI connects to
• Use SSL/TLS — encryption mode
• SMTP username, SMTP password — credentials for the SMTP server
• From address — what users see in the “From” field

Each field has an Override / Use inherited value toggle, so you can override individual fields without re-entering everything.

When to configure

• After installing PebbleAI fresh — to enable user invitation emails
• After changing SMTP providers
• When test emails aren’t arriving (re-check host, port, credentials)

Tip

Test the SMTP setup by inviting yourself to a second test account before rolling invitations out to your team.

4. Theme

Defines the organisation theme profile. This is where branding and visual customisation live — there is no separate “Branding” page in PebbleAI; everything is here.

The Theme tab itself has four sub-tabs:

Branding sub-tab

• Client Logo URL + Upload Client Logo — the logo shown in the sidebar header and on the sign-in page
• Auth Hero Image URL + Upload Auth Hero Image — the image shown beside the sign-in form
• Primary Color, Secondary Color, Accent Color — colour pickers for buttons, links, and accent elements
• Light Mode Structural Colors — additional colour controls for backgrounds and surfaces

Typography sub-tab

Font scale and font family controls.

Layout & Components sub-tab

Component-level overrides for spacing, radius, and shadows.

Reporting sub-tab

Dedicated colour palette for charts in PebbleObserve dashboards (spend, tokens, requests, cache, multi-series). Configured separately so admin charts don’t inherit the same colours as primary action buttons, which would make them illegible.

Step-by-step: rebranding for your organisation

1. Upload your logo as PNG or SVG (transparent background recommended)
2. Set Client Logo URL to the uploaded file
3. Pick a Primary Color that matches your brand
4. Optionally upload an Auth Hero Image
5. Click Save at the bottom of the tab
6. Hard-refresh the browser to see the new branding

The new theme applies immediately to everyone in the organisation.

5. Ambient Context

Defines the organisation layer of PebbleChat’s ambient context — the system prompt that shapes how PebbleChat responds for everyone in the org.

What you set here

• Scope tabs — Global Tenant, Draft Tenant, Prompt Budget (300 tokens), Audit (Last week 26 days), Draft Tenant
• Enable this layer toggle
• Ambient Context Draft — the rich-text editor for the prompt content with live token counter and remaining budget
• AI-powered Enhance action — expands a short draft into a comprehensive prompt-safe version while respecting the token budget

How layers stack

Ambient context combines four layers in this order:

1. Platform (set by platform admin)
2. Organisation (this page)
3. Workspace (set by workspace admins)
4. Personal (set by users in their profile — see Profile & Account)

Each layer adds on top of the previous; later layers can refine but can’t override the earlier ones. Each layer has its own token budget so the total doesn’t blow the model’s context window.

Step-by-step: writing your organisation prompt

1. Toggle Enable this layer on
2. Write your instructions in the editor — focus on persistent organisation-wide rules:
   • “Always respond in Australian English”
   • “We are a financial services firm regulated by APRA — never give financial advice”
   • “When citing data, use APA referencing”
   • “Default to terse responses unless asked for detail”
3. Watch the token counter — if you’re hitting the limit, click Enhance to have AI rewrite for clarity at a smaller token cost
4. Click Save Personal Context at the bottom (the button label changes per scope)

Tips

• Don’t put secrets here. Ambient context is included in every PebbleChat request and is visible to users.
• Be specific about format and tone. Vague rules (“be helpful”) add token cost without changing behaviour.
• Iterate. Set it once, watch what users get from PebbleChat for a week, refine.

6. Memory

Configures how PebbleChat manages conversation memory — the system that lets PebbleChat remember context across sessions and personalise responses to individual users.

What you set here

• Enabled toggle — turn the memory system on/off for the organisation
• Embedding Provider Configuration — which provider to use for memory embeddings (e.g. AWS Bedrock)
• Embedding model — the specific model (e.g. Cohere Embed English v3 (1024))
• Vector dimensions: 1024 — auto-derived from the embedding model
• Memory Extraction LLM — the language model that extracts memories from conversations (this should be a fast, cheap model — Claude Haiku is a good default)
• Provider for the extraction LLM

When to configure

• After setting up a new organisation, before users start having conversations
• When you want to switch embedding providers (e.g. moving from OpenAI embeddings to Bedrock)
• When you need to tune memory extraction quality (try a different extraction LLM)

How users interact with memory

Once enabled, memories are extracted automatically from every PebbleChat conversation. Users see and manage their own memories at User Settings → Memory.

7. Default Models

Configures the default models used for background system tasks like context compression, summarisation, and other automated work that PebbleChat does behind the scenes.

This is not the model users chat with. Users pick their own model in the PebbleChat composer. Default Models is for the system — things like compression that need to be cheap and fast.

What you set here

Fast Model

• Model — the model used for context compression, summarisation, and other automated tasks where speed and cost matter more than capability
• Credential — which credential authenticates calls

A typical Fast Model: au.anthropic.claude-haiku-4-5-20251001-v1:0 (AWS Bedrock).

Smart Model

• Model — a more capable model for complex tasks that need quality. Can be used as the default chat model when no user preference exists.
• Credential — which credential authenticates calls

A typical Smart Model: au.anthropic.claude-opus-4-6-v1 (AWS Bedrock).

Embedding Model

The embedding model used for asset discovery in PebbleChat — generates the vector embeddings that PebbleChat uses to match user messages with discoverable workspace assets (flows, document stores, agents).

Step-by-step: configuring defaults

1. Pick a Fast Model — Claude Haiku, GPT-4o mini, or similar
2. Make sure the Credential field shows the right credential (must already exist in Credentials)
3. Pick a Smart Model — Claude Opus, GPT-4o, or similar
4. Pick an Embedding Model — Cohere Embed English v3, AWS Titan Embed, etc.
5. Click Save at the bottom of the tab

Why both Fast and Smart

Background work has two flavours: cheap-and-routine (compression, classification) and expensive-but-rare (synthesis, planning). Using a fast model for the routine work keeps cost down by orders of magnitude; using a smart model for the rare work keeps quality up where it matters.

8. Chat Settings

Controls how PebbleChat manages conversation context window usage — specifically, the automatic compression that prevents long conversations from hitting the model’s context limit.

What you set here

Context Compression

• Enabled toggle — automatic compression on/off for the organisation
• Trigger Threshold — slider, 10% to 95% (default 70%). Compression starts when the conversation reaches this percentage of the model’s context window. Lower = more proactive (compresses earlier).
• Drain Target — slider, 5% to 50% (default 50%). After compression, target this percentage. Lower = more aggressive compression (frees more space).

Tuning advice

• 70% / 50% — the default, balanced for most conversations
• 80% / 60% — for long, nuance-heavy conversations where every turn matters
• 60% / 40% — for chat-heavy use where users have lots of throwaway back-and-forth

How compression works in detail

See PebbleChat → Advanced Features → Context Window for the user-side view. The compression itself runs on the Fast model configured in Default Models.

Step-by-step: tightening compression

1. Set Trigger Threshold lower (e.g. 60%) — more proactive
2. Set Drain Target lower (e.g. 35%) — more aggressive
3. Click Save Chat Settings
4. Tell users the change has happened — they may notice older messages being summarised more aggressively

9. Voice Settings

Configures the speech-to-text and text-to-speech providers used by PebbleChat’s voice input feature.

What you set here

• Speech to Text Model — the STT model. Amazon Transcribe Streaming is recommended for Australian sovereignty (ap-southeast-2 region)
• Text to Speech (TTS) Model — the TTS model. Amazon Polly Neural is recommended for Australian sovereignty (ap-southeast-2 region)

Step-by-step: enabling voice for the organisation

1. Pick an STT model (Amazon Transcribe Streaming for AU)
2. Pick a TTS model (Amazon Polly Neural for AU)
3. Click Save Voice Settings
4. Voice features now appear for users in the PebbleChat composer

Users see the Voice Input feature once it’s configured.

Why Amazon Transcribe and Polly

Amazon’s models are AWS-native, meaning they run inside your AWS account and never leave your region. For Australian government and regulated industries, this matters more than the marginal accuracy difference between providers.

10. SSO Config

Configures Single Sign-On for your organisation.

What you set here

• Enable SSO Login toggle
• Provider tabs — Microsoft, Google, Auth0, GitHub
• Callback URL — auto-populated from the OAuth Callback URL set in the OAuth tab
• Tenant ID, Client ID, Client Secret — provider-specific credentials
• Provisioning and SCIM — auto-create users on first SSO login, or require manual provisioning

Step-by-step: enabling Microsoft Entra ID SSO

1. Toggle Enable SSO Login on
2. Pick the Microsoft tab
3. Register an Azure AD app (see your Microsoft 365 documentation for app registration)
4. Copy the Tenant ID, Client ID, and Client Secret into the form
5. Set the redirect URI in Azure AD to the Callback URL shown on this tab
6. Optionally enable Provisioning — auto-create new PebbleAI users when they sign in via SSO
7. Click Save SSO Settings
8. Test by signing out, then signing back in via the SSO flow

11. Roles

Defines the roles available in your organisation and which permissions each role grants.

What you see here

A table of roles with columns:

• Role — the role name (e.g. viewer, editor, admin)
• Description — a short description
• Permissions — which permission groups this role has (chatflows, agentflows, document stores, credentials, tools, etc.)
• Assigned Users — how many users currently hold this role

Step-by-step: creating a custom role

1. Click Add Role in the top-right
2. Give the role a name and description
3. Tick the permission groups you want this role to have
4. Save
5. Now assign the role to users in Users

Default roles

Most installs ship with these defaults:

• viewer — read-only access; can see assets but not run or edit them
• editor — can create and edit chatflows, agentflows, tools, document stores, and use PebbleChat with full capabilities
• admin — everything; full control

You can clone and customise any default role to create variations.

Saving and inheritance

Each tab has its own Save button at the bottom (Save Settings, Save OAuth Settings, Save Chat Settings, etc.). Changes don’t take effect until you click Save.

Most fields have a Use inherited value / Override dropdown beside them. Pick Override to set an organisation-specific value; pick Use inherited value to fall back to the platform default.

Troubleshooting

“My change didn’t take effect” — Confirm you clicked the Save button on the specific tab. Saves are scoped to the tab they’re on.

“I overrode a value but it still shows the old behaviour” — Hard-refresh the browser. Some caches don’t pick up settings changes until the next page load.

“The page won’t load” — You may not have organisation admin role. Check with whoever runs PebbleAI for your org.

Related

• Credentials — must exist before you can pick them in OAuth, Email, Default Models
• PebbleRouter — picks up the Default Models you set here as fallbacks
• Profile & Account — where users set the personal layer of ambient context