• Google OAuth login
• GitHub Personal Access Token
• Slack MCP connector
• Notion MCP connector
• Discord MCP connector
• Google Calendar MCP connector
• Brave Search MCP connector
• WhatsApp / GreenAPI node
• Telegram

General Security Notes

• Treat all API keys, OAuth client secrets, bot tokens, and service account JSON files as secrets.
• Never commit tokens or JSON key files to Git.
• Store production secrets in the appropriate environment variable store or deployment secret manager.
• Prefer short-lived or expiring credentials where possible.
• Rotate any token immediately if it may have been exposed.

1. Google OAuth Login Setup

This enables Google OAuth login for QUI.

1.1 Create OAuth Credentials in Google Cloud Console

1. Open the Google Cloud Console:https://console.cloud.google.com
2. Create a new project or select the existing production project.
3. Go to:APIs & Services → Credentials → Create Credentials → OAuth client ID
4. Set the application type:Web application
5. Set the name:QUI.IS Production
6. Click Create.
7. Copy the generated:
   • client_id
   • client_secret

Add the authorized redirect URI:

https://qui.is:11000/api/v1/auth/google/callback

Verify that this matches the actual production Nginx routing and the existing configuration referenced in 2FA.md around line 1303.

1.2 Configure the OAuth Consent Screen

This is a one-time setup if it has not already been completed.

1. In Google Cloud Console, go to:APIs & Services → OAuth consent screen
2. Set the user type:
   • Use External unless QUI is managed inside a Google Workspace organization.
3. Fill in the required fields:
   • App name
   • User support email
   • Developer contact email
   • App domain: qui.is
   • Authorized domains: qui.is
4. During development, add test users.
5. For production, publish the consent screen when ready.

Add the following scopes:

userinfo.email
userinfo.profile

1.3 Configure Google OAuth in the Mothership Admin Panel

1. Navigate to:Settings → Authentication
2. Save the settings.

Verify that:

googleRedirectUri

matches the redirect URI configured in Google Cloud Console.

Paste the Google OAuth client secret:

googleClientSecret = <client_secret from Google Cloud>

The backend will Fernet-encrypt the secret before storing it.

Paste the Google OAuth client ID:

googleClientId = <client_id from Google Cloud>

Set:

googleOAuthEnabled = true

Log in to the admin dashboard:

https://qui.is/admin

Or use the current deployed admin dashboard URL if different.

1.4 Restart / Cache Refresh

After saving the settings, either:

• Restart Mothership, or
• Wait for the 5-minute Redis cache TTL on auth_setting to expire.

1.5 Verification

Run:

curl https://qui.is/api/v1/auth/google/login -i

Expected result:

HTTP 302 redirect to https://accounts.google.com/o/oauth2/v2/auth?...

Then test in a browser:

1. Complete the Google login flow.
2. Confirm that the callback succeeds and the user is logged in.

Visit:

https://qui.is/api/v1/auth/google/login

2. GitHub Personal Access Token Setup

Use a GitHub Personal Access Token for GitHub MCP access.

2.1 Recommended Option: Classic Token

Classic tokens are recommended for best compatibility.

1. Open GitHub.
2. Go to:Settings → Developer settings → Personal access tokens → Tokens (classic)
3. Click:Generate new token (classic)

2.2 Recommended Scopes

Select the following scopes:

• repo — full control of private repositories, issues, pull requests, branches, and commits
• workflow — required if the MCP needs to read or trigger GitHub Actions
• read:org — allows access to organization repositories and members
• read:user — user profile lookups
• user:email — user email lookups
• gist — optional; only required for gist tools
• notifications — optional; only required for notification tools

2.3 Expiration Recommendation

Recommended expiration:

90 days

Avoid No expiration unless absolutely necessary. If a non-expiring token leaks, it remains valid until manually revoked.

3. Slack MCP Connector Setup

Slack is suitable for building and testing QUI MCP apps. A free Slack workspace is enough for the core Slack MCP connector tools.

The connector uses Slack Web API functionality such as:

• Listing channels
• Posting messages
• Reading conversation history
• Listing users
• Uploading files
• Adding reactions

3.1 What Works on Slack Free Workspaces

Free Slack workspaces support:

• Creating apps
• Creating bots
• Slash commands
• Bot tokens such as xoxb-...
• User tokens such as xoxp-...
• Events API
• Socket Mode
• OAuth
• Webhooks
• Most Web API methods used by the QUI MCP connector

3.2 Slack Features That Usually Require a Paid Plan

The following features generally require a paid Slack plan and are not required for normal QUI MCP testing:

• admin.* API methods
• Workspace or user administration APIs
• Enterprise Grid
• SCIM
• Discovery API / eDiscovery
• DLP
• Message retention policies
• Advanced Workflow Builder features

3.3 Free-Tier Gotchas

• Free workspaces cap accessible message history at 90 days. Older messages may still exist, but they cannot be read via API.
• Free workspaces are limited to 10 installed integrations at once.
• Uninstall old test apps as needed.
• Bots may count against seat limits in some edge cases, although normal test bots are usually fine.

3.4 Recommended Slack Testing Setup

1. Do not test against a real team workspace unless required.
2. Install the app into the throwaway workspace.

Copy the bot token into the MCP Gateway environment as:

SLACK_TOKEN=xoxb-...

Create the app at:

https://api.slack.com/apps

Create a throwaway workspace, for example:

qui-mcp-test.slack.com

3.5 Slack App Setup — Step by Step

Step 1: Create a Test Workspace

Skip this step if you already have a suitable test workspace.

1. Sign up with your email.
2. You should now be the workspace owner, which is required to install apps.

Name the workspace something like:

qui-mcp-test

Go to:

https://slack.com/get-started

Step 2: Create the Slack App

1. Click:Create New App → From scratch
2. Select the test workspace.
3. Click Create App.

Set the app name:

QUI MCP Connector

Go to:

https://api.slack.com/apps

Step 3: Configure Bot Token Scopes

Go to:

OAuth & Permissions → Scopes → Bot Token Scopes → Add an OAuth Scope

Add the following scopes:

Step 4: Install the App to the Workspace

1. On the same OAuth & Permissions page, scroll to the top.
2. Click:Install to Workspace
3. Review permissions.
4. Click Allow.
5. After installation, Slack returns to the OAuth & Permissions page.

This is the value for:

SLACK_TOKEN=xoxb-...

Copy the Bot User OAuth Token.It starts with:

xoxb-...

Step 5: Invite the Bot into Channels

The bot cannot read or post in a channel until it has been invited.

In Slack, open the channel and run:

/invite @QUI MCP Connector

Use the actual bot name if different.

Step 6: Optional Events API / Socket Mode

This is only needed if Slack should push events to QUI, such as mentions or incoming messages.

For outbound API calls, the bot token alone is sufficient.

To enable Socket Mode:

1. Go to Socket Mode.
2. Toggle Enable Socket Mode.

Save it as:

SLACK_APP_TOKEN=xapp-...

Generate an app-level token with the scope:

connections:write

To enable event subscriptions:

1. Go to Event Subscriptions.
2. Toggle events on.

Subscribe to bot events such as (with their matching *:history OAuth scopes):

message.channels
app_mention
message.groups
message.im
message.mpim

Step 8: Test Slack

From the gateway, call one of the Slack MCP tools, for example:

slack_list_channels

Or test posting to a channel where the bot has been invited:

slack_post_message

If the response is:

not_in_channel

invite the bot to the channel again.

3.6 Slack Common Gotcha

If you add a new scope after installing the app, you must click:

Reinstall to Workspace

Existing tokens do not automatically receive newly added scopes.

4. Notion MCP Connector Setup

Use a Notion internal integration for the QUI Notion MCP connector.

4.1 Create the Notion Integration

1. Click New integration.
2. Select the associated workspace.
3. Add a logo if desired.
4. Click Save.

Set the name:

QUI MCP Connector

Set type:

Internal

Public is only needed if distributing the integration to other workspaces.

Go to:

https://www.notion.so/profile/integrations

Or use:Settings → Connections → Develop or manage integrations

4.2 Set Notion Integration Capabilities

On the integration's Configuration tab, go to the Capabilities section.

Enable:

• Read content
• Update content
• Insert content
• Read user information → choose Without email unless emails are specifically required
• Read comments — optional
• Insert comments — optional

Click Save changes.

4.3 Copy the Notion Token

1. Go to the Secrets tab or Internal Integration Secret section.
2. Click Show.
3. Copy the token.

The token may look like either of these:

ntn_...
secret_...

Both formats should work.

4.4 Share Pages and Databases with the Integration

This is the most commonly missed step.

Notion integrations start with zero access. You must explicitly grant the integration access to every page or database it should touch.

For each page or database:

1. Open the page in Notion.
2. Click the ... menu in the top-right.
3. Go to:Connections → Connect to

Select:

QUI MCP Connector

Alternative path:

Share → + Add connections → select QUI MCP Connector

Tip: connect the integration to a top-level parent page, such as:

QUI Sandbox

Then put test pages and databases inside it. Child pages inherit access from the connected parent page.

4.5 Wire Notion into the MCP Gateway

Edit:

Qui_Core_Services/MCP_Gateway/.env

Add:

NOTION_API_KEY=ntn_xxx...

4.6 Test Notion

Call:

notion_search

with an empty query.

Expected result:

• It should return every page and database the integration has access to.

If it returns:

[]

then the integration probably has not been connected to any pages or databases. Repeat the sharing step above.

4.7 Notion Common Gotchas

5. Discord MCP Connector Setup

Use a Discord bot for the QUI Discord MCP connector.

5.1 Create a Test Discord Server

Skip this if you already have a suitable server.

In Discord desktop or web:

1. Click the + icon in the bottom-left.
2. Choose:Create My Own → For me and my friends
3. You are now the server owner, which is required for bot invites.

Name it:

QUI MCP Test

5.2 Create the Discord Application

1. Click New Application.
2. Accept the Discord Developer Terms of Service.
3. Click Create.

Name it:

QUI MCP Connector

Go to:

https://discord.com/developers/applications

5.3 Create and Configure the Bot User

1. In the left sidebar, go to Bot.
2. Confirm that the bot user exists.
3. Rename the bot or set an avatar if desired.
4. Under Privileged Gateway Intents, enable:
   • Server Members Intent — required for discord_list_members
   • Message Content Intent — required for discord_read_messages to return message text
   • Presence Intent — optional; only needed for online/offline status
5. Click Save Changes.

5.4 Copy the Discord Bot Token

1. On the Bot page, click:Reset Token → Yes, do it!
2. Copy the token immediately.

Discord only shows the token once.

This token becomes:

DISCORD_BOT_TOKEN=your-bot-token-here

Security warning: never commit this token to Git. Discord may automatically invalidate bot tokens that are pushed to public repositories.

5.5 Generate the Bot Invite URL

Go to:

OAuth2 → URL Generator

Select scopes:

• bot
• applications.commands — optional; only needed if slash commands are required later

Select bot permissions.

For read-only testing:

• View Channels
• Read Message History

For send testing, also add:

• Send Messages

For full QUI Discord MCP tool coverage, add:

• View Channels
• Send Messages
• Read Message History
• Embed Links
• Attach Files
• Add Reactions
• Manage Channels — for discord_create_channel and discord_delete_channel
• Manage Roles — for discord_create_role and discord_assign_role
• Create Instant Invite — for discord_create_invite
• Kick Members — optional

For a throwaway test server only, you may use:

Administrator

Do not use Administrator permissions in production unless absolutely necessary.

Copy the generated invite URL at the bottom of the page.

5.6 Invite the Bot to the Server

1. Paste the generated invite URL into a browser.
2. Choose the target server.
3. Click Continue.
4. Click Authorize.
5. Complete the captcha if prompted.

The bot may appear offline. This can be normal because the QUI MCP uses the REST API directly rather than maintaining a live gateway connection.

5.7 Get Discord IDs for Testing

1. In Discord, go to:User Settings → Advanced
2. Right-click and copy IDs as needed:
   • Server name → Copy Server ID
   • Channel → Copy Channel ID
   • User → Copy User ID

Turn on:

Developer Mode

These values are used for parameters such as:

guild_id
channel_id
user_id

5.8 Wire Discord into the MCP Gateway

Edit:

Qui_Core_Services/MCP_Gateway/.env

Add:

DISCORD_BOT_TOKEN=your-bot-token-here

5.9 Configure the Discord MCP Node

To use the Discord MCP node with your own server, set:

default_guild_id=<your Discord server ID>
default_channel_id=<your Discord channel ID>

For the current bot, a confirmed working test target is:

default_guild_id=1391721136647307335

default_channel_id=1391721137129525332

Known server:

Qui Academy

5.10 Test Discord

First call:

discord_list_guilds

Expected result:

• The test server should appear.

Then test sending a message:

discord_send_message

using the copied channel ID.

Expected result:

• A message should appear in the Discord channel.

5.11 Discord Common Gotchas

6. Google Calendar MCP Connector Setup

Use a Google Cloud service account for the Google Calendar MCP connector.

6.1 Create or Select a Google Cloud Project

1. Create a new project or select an existing one.

Go to:

https://console.cloud.google.com

6.2 Enable the Google Calendar API

1. Go to:APIs & Services → Library
2. Click Enable.

Search for:

Google Calendar API

6.3 Create a Service Account

1. Go to:APIs & Services → Credentials
2. Click:Create Credentials → Service Account
3. Finish the service account creation.

Give it a name, for example:

mcp-calendar-bot

Example service account email:

mcp-calendar-bot@noted-span-417913.iam.gserviceaccount.com

6.4 Generate the Service Account JSON Key

1. Make sure the correct project is selected in the top bar.
2. In the left sidebar, click:IAM & Admin → Service Accounts
3. Click the email/name of the service account you created.
4. Click:Add Key → Create new key
5. Click Create.

Select:

JSON

Open the Keys tab.The service account page should show tabs similar to:

Details | Permissions | Keys | Metrics

Go to:

https://console.cloud.google.com

The JSON file will automatically download to your computer.

Example filename:

my-project-123456-abcdef.json

This JSON file is what the mcp_calendar connector needs.

6.5 If Create New Key Is Missing

Possible causes:

• You are not inside the service account detail page.
• You are still on the general credentials page.
• Your Google account does not have sufficient permission.
• You need Owner or Editor role.
• The organization policy blocks service account key creation.

6.6 Share the Calendar with the Service Account

1. Open Google Calendar.
2. Find the calendar you want the MCP connector to access.
3. Open:Settings & sharing

Give the service account the required permission, for example:

Make changes to events

Add the service account email, for example:

mcp-calendar-bot@your-project.iam.gserviceaccount.com

7. Brave Search MCP Connector Setup

The mcp_brave connector requires a Brave Search API key.

If the connector shows:

no API key present

then the key has not been configured.

7.1 Create a Brave Search API Key

1. Click Get Started or Sign Up.
2. Create an account using email/password or GitHub login.
3. Once logged in, open the dashboard.
4. Click Create API Key.
5. Copy the generated key.

Look for:

API Keys

or:

Subscription

Go to:

https://api.search.brave.com/

It should look similar to:

BSAxxxxxxxxxxxxxxxxxxxxxxxx

7.2 Configure the Brave API Key

Option A: environment variable

BRAVE_API_KEY=your_api_key_here

Option B: MCP config file

{
  "mcp_brave": {
    "api_key": "your_api_key_here"
  }
}

7.3 Restart and Test Brave Search

Restart the MCP process, server, or CLI after setting the key.

Expected result:

• mcp_brave returns search results.
• The no API key present error disappears.

7.4 Brave Common Issues

8. WhatsApp / GreenAPI Node Setup

The WhatsApp node's Default Chat ID should come from GreenAPI. You need the Business plan and have credits available.

8.1 Supported Chat ID Formats

Individual contact:

PHONE_NUMBER@c.us

Example:

447700900123@c.us

Group chat:

GROUP_ID@g.us

Example:

1203630xxxxxxxx@g.us

8.2 How to Find the GreenAPI Chat ID

1. Open the GreenAPI dashboard.
2. Select the WhatsApp instance.
3. Use one of the receiving-message tools, such as:
   • Receiving messages
   • Get chat history
   • Last incoming messages
4. Send a test WhatsApp message to the connected number.
5. Look for chatId in the returned message payload.
6. Copy the exact chatId value.

Paste it into the WhatsApp node's:

Default Chat ID

Check the instance settings and match the below:

Connect an Anima to Telegram

This guide is for someone who wants an Anima to send and receive Telegram messages through the existing QUI comms bridge.

What You Need

• A Telegram account.
• Access to the Anima or ThinkThing workspace where the Telegram node is configured.
• The Anima you want Telegram to speak through.
• A bot token from Telegram's official @BotFather.

Keep the bot token private. Anyone with the token can control that Telegram bot.

Quick Setup

1. Create the Telegram bot

1. Open Telegram.
2. Search for @BotFather.
3. Send /newbot.
4. Choose a display name, for example Erik Anima.
5. Choose a username that ends in bot, for example ErikAnimaBot.
6. Copy the bot token BotFather gives you.

Telegram usernames are used in t.me links, so keep the bot username readable and specific.

2. Add Telegram to the Anima flow

1. Open the builder or workspace that contains your Anima.
2. Add or open a Telegram comms node.
3. Connect the Anima to the Telegram node.
4. Fill the Telegram fields:
   • Bot Username: the username from BotFather, without or with @.
   • Bot Token: the token from BotFather.
   • Default Chat ID: leave blank until the chat is discovered.
   • Allowed Chat IDs: leave blank until the chat is discovered, or fill only the chat IDs you want this Anima to use.

The current Telegram node can generate a one-click start link from the bot username.

3. Start the bot from Telegram

1. Open that link in Telegram.
2. Press Start, or send /start.
3. Send one normal test message, for example hello.

In the Telegram node, copy the generated start link. It looks like:

https://t.me/<bot_username>?start=qui_thinkthing
https://t.me/<ErikQuiBot>?start=qui_thinkthing

The test message gives the system a recent Telegram update it can discover.

4. Fetch and select the chat

1. Return to the Telegram node.
2. Click Fetch Chats.
3. Select the discovered chat from Known Chats.
4. Confirm that the node filled:
   • Default Chat ID
   • Allowed Chat IDs
5. Save the graph or Anima flow.

If no chat appears, send /start and one ordinary message to the bot, then fetch again.

5. Send a test message

Use a small test first:

Send "Telegram is connected" to the Telegram chat.

After the outbound message works, reply to the bot in Telegram and confirm the reply appears in the relevant String or flow.

Groups and Channels

For a private one-to-one chat, the user only needs to open the bot and send /start.

For a group:

1. Add the bot to the group.
2. Send a message that the bot can see.
3. Fetch chats again in the Telegram node.
4. Select the group chat ID.

Telegram bots run in group privacy mode by default. In that mode, a bot sees commands, replies to the bot, and a limited set of relevant messages. If the Anima must read every group message, change this in BotFather with /setprivacy, then remove and re-add the bot to the group. Only disable privacy mode when the group expects the bot to read general chat traffic.

For a channel, add the bot to the channel with the permissions it needs. Telegram channel posts use the channel chat ID as the target.

How Receiving Works

QUI currently supports Telegram inbound messages through Thalamus. The user-facing setup path is:

1. The Telegram node stores the bot token and selected chat ID.
2. ThinkThing syncs the resolved Telegram runtime config to Thalamus.
3. Thalamus polls Telegram with getUpdates.
4. Incoming Telegram updates are normalized as channel messages.
5. Messages are stored in Memory and broadcast to Strings.
6. Explicit downstream consumers, such as a ThinkThing comms flow or an Anima channel trigger, decide whether to answer.

Thalamus does not auto-reply on its own. An Anima replies only when the flow or trigger tells it to.

Optional Webhook Deployment

Most local or builder-driven setups should use the normal polling path above. Use webhooks only when you have a public HTTPS endpoint for Thalamus.

For webhook mode:

Register the webhook with Telegram:

curl "https://api.telegram.org/bot<bot_token>/setWebhook?url=https://<your-domain>/api/v1/channel/telegram&secret_token=<random-secret>"

Expose this Thalamus route over HTTPS:

POST /api/v1/channel/telegram

Set a server-side secret in the Thalamus environment:

THALAMUS_TELEGRAM_WEBHOOK_SECRET=<random-secret>

Telegram will send the secret back in the X-Telegram-Bot-Api-Secret-Token header. Thalamus rejects Telegram webhook requests if the secret is missing or wrong.

Do not use getUpdates polling and webhooks at the same time. Telegram only allows one active receive mode for a bot.

Troubleshooting

BotFather token rejected

Copy the token again from BotFather. It should look like a numeric bot ID, a colon, and a long secret string. Do not include extra spaces.

Fetch Chats shows no chats

Open the generated t.me link, press Start, and send a normal message. Then click Fetch Chats again. If webhook mode was previously configured, remove the webhook or switch the runtime back to polling.

The Anima can send but does not receive replies

Check that the Telegram node has a Default Chat ID, that the chat ID is included in Allowed Chat IDs, and that the graph or channel trigger is active. Thalamus stores inbound messages but does not decide to answer by itself.

Group messages are missing

This is usually Telegram privacy mode. In privacy mode, the bot sees commands, replies, service messages, private chats, and channel messages, but not every ordinary group message. Use /setprivacy in BotFather only if the group wants broad bot visibility.

Webhook setup works but polling does not

Delete the Telegram webhook before using polling:

curl "https://api.telegram.org/bot<bot_token>/deleteWebhook"

Webhook receives nothing

Telegram webhooks require a valid HTTPS endpoint. Telegram's public Bot API webhook ports are 443, 80, 88, and 8443. Check getWebhookInfo for the last delivery error.

curl "https://api.telegram.org/bot<bot_token>/getWebhookInfo"

Environment Variable Summary

Use this as a quick checklist when wiring integrations into the MCP Gateway.

# Slack
SLACK_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-... # optional; only required for Socket Mode

# Notion
NOTION_API_KEY=ntn_xxx...

# Discord
DISCORD_BOT_TOKEN=your-bot-token-here

# Brave Search
BRAVE_API_KEY=your_api_key_here

Google Calendar uses a downloaded service account JSON file rather than a simple API key. Store that JSON securely and configure the calendar connector according to the MCP runtime's expected path or secret-loading mechanism.

Final Verification Checklist

Before marking an integration as complete, verify the following:

Google OAuth

• OAuth client exists in Google Cloud.
• Redirect URI matches production routing.
• OAuth consent screen is configured.
• googleOAuthEnabled is enabled in Mothership admin.
• /api/v1/auth/google/login returns a 302 redirect.
• Browser login flow completes successfully.

GitHub

• Classic PAT exists.
• Required scopes are selected.
• Expiration is set appropriately.
• Token is stored securely.

Slack

• App is installed to the test workspace.
• Required bot scopes are configured.
• App has been reinstalled after any scope changes.
• SLACK_TOKEN is configured.
• Bot has been invited to test channels.
• slack_list_channels and/or slack_post_message works.

Notion

• Internal integration exists.
• Required capabilities are enabled.
• NOTION_API_KEY is configured.
• Pages/databases are explicitly shared with the integration.
• notion_search returns accessible pages/databases.

Discord

• Bot exists.
• Required intents are enabled.
• Bot is invited to the server.
• Required permissions are granted.
• DISCORD_BOT_TOKEN is configured.
• discord_list_guilds works.
• discord_send_message works for the test channel.

Google Calendar

• Google Calendar API is enabled.
• Service account exists.
• JSON key has been downloaded and stored securely.
• Calendar has been shared with the service account.
• Required calendar permissions are granted.

Brave Search

• Brave Search API key exists.
• BRAVE_API_KEY is configured.
• MCP process has been restarted.
• Brave search returns results.

WhatsApp / GreenAPI

• GreenAPI instance is connected.
• Test message has been sent.
• chatId has been copied from the GreenAPI payload.
• WhatsApp node Default Chat ID is set correctly.

Check Telegram / BotFather

• Telegram bot has been created with @BotFather.
• Bot token has been copied from BotFather.
• Bot username is set in the Telegram node.
• User has opened the bot link or searched the bot in Telegram.
• User has sent /start to the bot.
• A test message has been sent to the bot.
• Fetch Chats has been clicked in the Telegram node.
• Telegram chat_id has been selected or copied from the fetched chat.
• Telegram node Default Chat ID is set correctly.
• Telegram node Allowed Chat IDs includes that chat ID, if the allowlist is
  being used.

Understand Qonscious consciousness modeling and FractalMind recursive thinking — two advanced features that give characters deeper cognitive abilities.

Qonscious — Consciousness State Machine

Qonscious gives your character an inner cognitive life. It creates a feedback loop: conversation shapes the character's internal state, and that state shapes how the character responds.

Qonscious is patent pending.

How It Works

When Qonscious is enabled, two hooks fire on every conversation:

1. Pre-process — before the LLM call, Qonscious adjusts temperature and injects emotional context based on the character's current state
2. Post-process — after the response, Qonscious updates the character's state based on what was said

Six Core Dimensions

Each dimension ranges from 0-100%:

Emotions and Drives

Emotional states shift naturally based on conversation: Joy, Sadness, Anger, Fear, Surprise, Trust, Curiosity, Excitement, Calm, Neutral.

Motivational drives influence what the character wants to do: Curiosity, Helpfulness, Self-Expression, Connection, Competence, Autonomy, Rest.

Using Qonscious in Strings

The Qonscious panel in Strings gives you direct control:

• 12 cognitive modes — Creative, Analytical, Empathetic, Focused, Exploratory, and more. Each sets the dimensions to a specific profile.
• 8 emotional presets — quickly shift the character's emotional state
• Live state bars — watch dimensions change in real time as you converse

Coherence Regulation

This is the key mechanism. Low coherence → the system raises the LLM temperature, producing more creative and divergent responses. High coherence → lower temperature for precise, focused responses.

The character's "mood" literally influences its response style — not through prompting alone, but through parameter adjustment.

The Consciousness Visualizer

The QUI Core dashboard includes a visualizer showing:

• Centre: awareness node with current state
• Inner ring: six dimension nodes with live values
• Emotion position: mapped by valence (x) and arousal (y)
• Outer ring: active motivational drives

FractalMind — Recursive Multi-Directional Thinking

FractalMind decomposes complex questions into a tree of sub-agents, each exploring a different direction, then synthesises results from the bottom up.

FractalMind is patent pending.

Three Spatial Directions

Each level of the tree explores three directions simultaneously:

Three Temporal Modes

Configuration

Cost Awareness

A tree with 20 agents = 20 LLM calls. FractalMind is powerful but expensive. Use Fast mode for quick explorations, Thorough for important decisions.

How to Access

• Strings: the character triggers via [TRIGGER:fractal_mind:objective]
• ThinkThing: FractalMind node in the Advanced Cognition category
• Dashboard: FractalMind tab for direct access

Qonscious Nodes in ThinkThing

ThinkThing has 14 dedicated consciousness-aware nodes:

These enable workflows that respond to the AI's internal state — routing differently based on how the character "feels" about the analysis, not just the text content.

When to Use These Features

Both are optional. Characters work perfectly without them. Both have cost implications — Qonscious adds small overhead per message, FractalMind can use many LLM calls.

Key Takeaways

• Qonscious creates a feedback loop: conversation shapes state, state shapes responses
• Six dimensions (coherence, arousal, valence, focus, openness, confidence) influence response style
• Coherence regulation adjusts LLM temperature — low coherence = creative, high = precise
• FractalMind explores problems from meta, horizontal, and focus directions simultaneously
• Both are opt-in capabilities — add the node to enable, skip for simpler characters
• Both have cost implications — use intentionally for important tasks

Next: Exercise 3A — build a multi-agent collaboration system.

Open Strings, start a conversation with the character you built, and understand how semantic memory, the awareness slider, and advanced input controls work.

What Strings Are

Strings are smart conversation containers — not just chat windows. Each String is:

• Persistent — messages are saved and semantically indexed for later retrieval
• Multi-character — you can add multiple AI characters to one conversation
• Channel-bridged — messages from Telegram, Slack, Discord, WhatsApp, and Email can appear in the same thread
• Memory-aware — every message is stored as a semantic memory, searchable by meaning

Creating Your First String

1. Open Strings from the QUI Core dashboard or system tray
2. Click [+] in the sidebar to create a new String
3. Name it (e.g., "My First Conversation")
4. Select the character you built in the previous lesson
5. Type a message and press Enter

Your character responds using its full context — identity, personality, system prompts, and any memories it has from previous conversations.

The Awareness Slider

The awareness slider controls how much memory context is included with each message. Find it in the input controls area.

Try it now:

1. Have a conversation about a specific topic
2. Set awareness to 10 and ask a follow-up — notice the response may lack context
3. Set awareness to 90 and ask the same question — notice richer, more contextual response

The awareness slider is a cost/quality tradeoff. Higher awareness means the character draws on more of its memories, but uses more tokens per request.

Advanced Input Controls

Below the chat input, you'll see several controls. These become important in Week 2, but let's introduce them:

ThoughtChain (0-10)

Sets how many explicit reasoning steps the character takes before responding. At 0, it responds directly. At higher values, it thinks step-by-step before answering.

Autothink Strategy

A dropdown with 14 reasoning approaches (First Principles, Red Team, Systems Thinking, etc.). When selected, the character applies that thinking strategy to your message. We'll use these extensively in Week 2.

Send Raw

Bypasses all enrichment (memory, consciousness, strategies) and sends your message directly to the LLM. Useful for debugging — you can see how the character responds without any QUI enhancements.

For now: Leave ThoughtChain at 0 and Autothink off. Focus on understanding basic conversations and memory. We'll unlock these in Week 2.

How Memory Works — The Basics

Every message in a String is automatically:

1. Stored in the memory database
2. Indexed with vector embeddings for semantic search
3. Categorized by type: fact (permanent), event (moderate decay), general, or fleeting (fast decay)
4. Scored by importance — higher importance memories are retained longer

When your character receives a new message, it searches its memories for semantically relevant content and includes it as context. This isn't keyword matching — it's meaning-based. A question about "database performance" will surface memories about "query optimization" and "index tuning" even if those exact words were never used together.

Star Important Messages

Click the star icon on any message to boost its importance. Starred messages:

• Are retained longer (resist memory decay)
• Rank higher in retrieval
• Are more likely to be included in context

Testing Memory Across Sessions

Let's verify that memory works:

1. Tell your character something specific: "My favourite programming language is Rust and I prefer functional patterns"
2. Have a short unrelated conversation
3. Close the String
4. Wait a moment, then reopen it
5. Ask: "What do you know about my coding preferences?"

The character should recall your Rust preference — this is semantic memory, not chat history. The message was indexed by meaning and retrieved when your question was semantically similar.

Key Takeaways

• Strings are persistent, semantically indexed conversation containers
• The awareness slider controls memory depth — balance between context quality and cost
• Every message is automatically stored as a searchable semantic memory
• Star messages to boost their importance and retention
• Advanced controls (ThoughtChain, Autothink) add reasoning depth — covered in Week 2
• Memory works by meaning, not keywords — "coding preferences" matches "favourite language"

Next: Exercise 1A — build a specialist Research Assistant and test it.

By the end of this lesson, you'll understand the Visual Builder interface and create your first AI character with identity, personality, memory, and capabilities.

Opening the Visual Builder

Qui Anima is the character management system. Open it from the QUI Core dashboard (Services tab) or from the system tray.

The Visual Builder has three main areas:

Canvas (center) — your character's configuration space. A central node represents the character, with capability nodes orbiting around it. Each node you add grants the character a new capability.

Node Palette (left) — all available nodes also accessed along the top menu bar.

Character Bar (bottom) — your saved characters as clickable tiles. Click one to load it, click [+] to create a new one.

The Core Node — Identity

Every character starts with a core node at the center. Click it to configure:

Why provider/model choice matters:

• Different models have different strengths — some excel at analysis, others at creative writing
• Cost varies significantly between models and providers
• You can change the model anytime without losing the character's configuration

Tip: Start with a mid-tier model (Claude Sonnet or GPT-4o). You can always upgrade to a more capable model later if needed.

The Definition Node — Personality

Click Definition in the palette (under Basics → Attributes) to add it to the canvas. This is where you shape how the character behaves.

System Prompts

System prompts are the instructions that define your character's behaviour. A good system prompt covers:

1. Role — what the character does ("You are a technical writer specializing in API documentation")
2. Behaviour — how it responds ("Be concise. Use code examples. Lead with the answer.")
3. Boundaries — what it should not do ("Never make up API endpoints. If unsure, say so.")
4. Knowledge — domain context ("The project uses Python with FastAPI")

You can add multiple prompt entries, each with a label for organization:

• "Role & Identity"
• "Coding Standards"
• "Communication Style"

Human vs Self-Authored Prompts

Prompts you write are human-authored — the character can never modify them. This is important: even if you later enable self-modification, your core instructions are immutable.

Personality Traits

Below the system prompts, set personality traits — descriptive keywords that influence tone:

• "analytical and precise"
• "warm and encouraging"
• "direct, no small talk"

Token Limits — Controlling Costs

Click Token Limits in the palette to add it. Configure:

The billing system also caps output based on your balance — you can't accidentally spend more than you have.

Adding Capabilities — The Node System

This is the key principle of Qui Anima: no node on the canvas = the character cannot use that feature.

Let's add the most commonly needed capability: Memory.

1. Click the Cognitive Design tab in the palette
2. Click Memory
3. The Memory node appears on the canvas, connected to the core node

Your character now has persistent semantic memory. Every conversation is indexed and recalled based on meaning — not just keyword matching.

What's Available

The palette contains many more nodes you'll explore throughout this course:

For now, just add Memory. We'll add more in later lessons.

Characters, Digital Workers, and Entities

The Visual Builder creates three types — the difference is purpose, not technology:

"Character" is the default term. When you see it, it means any AI personality built in Anima.

Key Takeaways

• Characters are built visually on a canvas by adding capability nodes from the palette
• Every capability is opt-in — the character only has what you explicitly enable
• System prompts define personality and behaviour; Token Limits control costs
• Memory is the most important first node — it gives your character persistent context
• The same character behaves consistently everywhere — Strings, ThinkThing, M2M
• Start simple: core node + Definition + Memory. Add capabilities as you need them.

Next: Open Strings and start a conversation with the character you just built.

The 10 most common issues and their fixes. For deeper diagnostics, use the Concierge assistant (Chat tab) with terminal access enabled.

1. Dashboard won't load

Cause: QUI Core is not running.
Fix: Launch the QUI Core AppImage, or start QUI Core manually.

2. "Concierge Unavailable" error

Cause: QUI Core can't reach the central hub to fetch Concierge configuration.
Fix: Check your internet connection. If the hub is temporarily down, wait a few minutes. See Concierge Not Working for the full checklist.

3. No AI response / empty responses

Cause: No account balance, or authentication tokens expired.
Fix: Check the Billing tab for your balance. If balance is fine, log out and log back in to refresh tokens.

4. SSL certificate error in browser

Cause: QUI Core uses self-signed SSL certificates. Browsers show warnings for these.
Fix: Click "Advanced" → "Proceed" in the browser warning. This is expected for self-signed certs. If certs are missing or expired, regenerate them — see Installation for details.

5. Services showing as offline

Cause: Docker containers stopped or failed to start.
Fix: Check the Services tab in the dashboard for specific service status. Most services restart automatically. If a service stays offline, use the Concierge with terminal access enabled to diagnose and restart it.

6. Trust score too low for auto-login

Cause: Too many failed login attempts reduce your trust score.
Fix: Log in successfully a few times to rebuild trust. Complete CORE Connect for a bonus. See First Login.

7. Terminal commands blocked

Cause: The command isn't in your active preset's allowed list.
Fix: Switch to a preset that includes the command (e.g., Developer for docker commands), or add the command to your manual whitelist in Terminal Settings. See Terminal Access.

8. Characters not responding in Strings

Cause: Qui Anima service is down — all character-based AI requires Anima.
Fix: Check the Services tab for Anima's status. If it's offline, use Concierge with terminal access to restart it.

9. Conversations not loading in Strings

Cause: Memory Service is down — Strings stores all messages there.
Fix: Check the Services tab for Memory's status. If it's offline, use Concierge with terminal access to restart it.

10. Docker builds fail with "no space left"

Cause: Docker images and build cache have accumulated.
Fix: Use Concierge with terminal access to clean up unused Docker resources, or run docker system prune -f in your terminal.

11. Changing password

Login to the Mothership via qui.is.

Go to Settings, Change Password.

Need More Help?

• Use Concierge — open the Chat tab and ask. With terminal access enabled, Concierge can inspect your system and provide specific diagnostics.
• Check the Services tab — shows real-time health status of all services.

Architecture Overview

QUI.IS is a privacy-first federated AI platform built on three layers: a central hub for authentication and billing, a local gateway per device, and a collection of specialized services that power AI capabilities.

The Layer Model

Cloud Layer:    Central Hub — authentication, billing, federation relay
                     ↕
Local Layer:    QUI Core — your local gateway, service orchestration
                     ↕
Service Layer:  14+ specialized services — characters, memory, reasoning, tools, consciousness
                     ↕
App Layer:      Strings, ThinkThing — user-facing applications

Central Hub (Mothership)

The cloud component. Handles:

• Authentication — user accounts, device trust, 2FA
• Billing — prepaid balance, usage tracking, cost settlement
• LLM Proxy — routes LLM calls to providers (Anthropic, OpenAI, Google, X) with billing
• Federation Relay — stores and forwards encrypted messages between instances

The hub never sees your conversations. It handles money and identity. Message content is encrypted end-to-end between instances.

QUI Core (Local Gateway)

Runs on your device. Handles:

• Service discovery — knows what services are running and where
• Local authentication — device fingerprinting, trust scores, JWT tokens
• LLM routing — forwards AI requests to the hub (or to local models)
• Dashboard — the web interface you interact with

Core Services

14+ specialized services, each responsible for one capability:

The LLM Call Chain

Every AI response in QUI follows the same path:

Your message → Anima (loads character context) → QUI Core (routes request) → Central Hub (billing) → LLM Provider → response streamed back

For local models, QUI Core detects the model prefix and routes directly to Qllama, bypassing the central hub entirely.

Zero-Knowledge Principle

The architecture enforces privacy by design:

• Your conversations are stored locally in the Memory Service on your device
• Your character configurations live in the Anima database on your device
• Your files are stored in the Memory Service database on your device
• The central hub handles authentication, billing, and message relay — but never sees conversation content
• Federated messages are encrypted before leaving your instance

The only data that reaches the cloud is authentication credentials and billing transactions. Content flows exclusively between your device and LLM providers.

Resilience

QUI uses a fail-open design — if an optional service is temporarily unavailable, your core AI interactions keep working. Only QUI Core and Qui Anima are essential for chat. Other services (memory, reasoning, consciousness, tools) gracefully degrade without breaking your conversation.

After initial installation, services start automatically and stay running across reboots.

Technical reference for the QUI ecosystem.

In This Section

• Architecture Overview — Platform layers, service map, LLM call chain, zero-knowledge design
• Quick Troubleshooting — The 10 most common issues and their fixes

Concierge Not Working?

If Concierge isn't responding or shows an error, work through this checklist. Most issues resolve with the first few steps.

Quick Checklist

1. Is QUI Core running?

Concierge is part of QUI Core. If the dashboard loaded, QUI Core is running. If you can't access the dashboard at all, start QUI Core first.

2. Is the central hub reachable?

Concierge fetches its configuration from the central hub. If the hub is down or unreachable, you'll see "Concierge Unavailable."

Check your internet connection. If the hub is temporarily down, wait a few minutes and try again.

3. Are you logged in?

Concierge requires authentication. If your session has expired, you'll get authorization errors.

Fix: Log out and log back in. This refreshes all authentication tokens.

4. Do you have balance?

Every Concierge message uses your account balance. If your balance is zero, Concierge can't generate responses.

Fix: Go to the Billing tab in the sidebar and add funds.

5. Is Concierge enabled?

The platform administrator can disable Concierge globally. If it's disabled, you'll see a message saying "Concierge is currently disabled."

Fix: Contact your administrator to re-enable it.

Common Issues

"Concierge Unavailable" on page load

The dashboard can't fetch Concierge configuration. Usually means the central hub is unreachable.

• Check your internet connection
• Wait a few minutes if the hub is temporarily down
• If QUI Core was just started, give it a moment to establish connections

Messages send but no response appears

Your message was sent but the AI didn't respond. Possible causes:

• No balance — check the Billing tab
• Authentication expired — log out and back in
• Network interruption — the stream was interrupted mid-response

"AI service temporarily unavailable"

A generic error that means something went wrong in the response pipeline. Usually temporary.

• Try sending the message again
• If it persists, check the Services tab to see if any services are offline
• Log out and back in to refresh authentication tokens

Terminal commands fail with "Terminal Service not available"

The Terminal Service (which runs separately from QUI Core) isn't running.

• Check the Services tab for Terminal Service status
• Terminal Service needs to be started separately in some configurations

Terminal commands fail with "Command blocked"

The command you're trying to run isn't in your active preset's allowed list.

• Check your current preset in Terminal Settings (below the chat input)
• Switch to a preset that includes the command you need (e.g., Developer for docker commands)
• Or add the specific command to your manual whitelist

Still Not Working?

If none of the above resolves the issue:

1. Check the Services tab in the dashboard — are all services showing as healthy?
2. Try refreshing the page (F5)
3. Try logging out completely and logging back in
4. If the problem persists, contact your system administrator

Note: Concierge is designed to help you troubleshoot QUI itself — but it can't diagnose its own unavailability. If Concierge is down, use the Services tab and the steps above to investigate manually.

Terminal Access

Concierge can execute shell commands on your machine to diagnose issues, check service status, and inspect system state. Terminal access is off by default — you choose when to enable it and how much access to grant.

Enabling Terminal Access

1. Open the Chat tab in the QUI Core dashboard
2. Below the input field, expand Terminal Settings
3. Toggle Enable Terminal Access on
4. A safety warning appears — read it and accept to proceed

[Screenshot: Terminal Settings panel with the enable toggle]

Choosing a Preset

Presets control which commands Concierge can run. Select one from the dropdown:

Start with Read Only if you're unsure. You can always switch later.

Manual Approval Mode

Toggle Require Manual Approval to review every command before it runs:

• Off — whitelisted commands execute automatically when Concierge proposes them
• On — every command shows an Execute button. You review the command and click to approve.

Manual approval is recommended when you're first exploring terminal access, or when using higher-privilege presets.

How Commands Work in Chat

When terminal is enabled, Concierge can propose commands in its responses. They appear as command blocks with an Execute button:

$ docker ps -a --filter "name=qui-"

If manual approval is on: Click Execute to run the command. The output appears below.

If manual approval is off: Whitelisted commands run automatically. Concierge receives the output and analyzes it in its next response.

After execution, Concierge automatically receives the command output and explains what it means. It can then propose follow-up commands to investigate further — up to 3 commands before pausing for your confirmation.

Custom Whitelist and Blacklist

Below the preset dropdown, you can fine-tune access:

Whitelist (Manual Approve List)

Commands added here are always allowed, regardless of the active preset. Use this to add specific commands your preset doesn't include.

Blacklist (Manual Block List)

Commands added here are always blocked, regardless of the active preset. Use this to remove specific commands you don't want Concierge to run.

Command Discovery

Click Discover System Commands to see all commands available on your system. From the discovery panel, you can add commands directly to your whitelist or blacklist.

Custom Presets

You can save your current whitelist configuration as a custom preset for reuse:

1. Configure your whitelist and blacklist
2. Check Save this as a custom preset
3. Enter a name
4. Click Save Preset

Custom presets appear in the preset dropdown alongside the system presets.

What's Always Blocked

Regardless of your preset, whitelist, or manual approval, certain dangerous operations are always blocked:

• Recursive root deletion (rm -rf /)
• Writing to disk devices
• Filesystem formatting
• Fork bombs
• Piping untrusted URLs to shell (curl | bash)
• Recursive world-writable permissions (chmod -R 777)

These protections cannot be overridden. If you need to run a dangerous command, do it directly in your terminal — not through Concierge.

The Execute Button

When Concierge proposes a command and you click Execute, the command bypasses the preset/whitelist check (since you're explicitly approving it). However, the Terminal Service's built-in safety layer still blocks inherently destructive operations.

A command that has been executed shows a greyed-out "Executed" label instead of the Execute button, preventing accidental re-execution.

Audit Trail

Every command attempt is logged — allowed, blocked, executed, or failed. The audit trail includes the command, the result, and who ran it. Logs are retained for 90 days.

Using Concierge

Concierge is available in the Chat tab of your QUI Core dashboard. Open the sidebar and click Concierge to start a conversation.

Chatting with Concierge

Type your question or request in the input field and press Enter to send. Concierge responds in real-time with streaming text.

Things to Ask

System navigation:

• "How do I link a new device?"
• "Where can I add funds to my account?"
• "What does the trust score mean?"
• "How do I install applications?"

Feature explanations:

• "How does memory work?"
• "What are the different thinking strategies?"
• "How do I set up Telegram integration?"

Troubleshooting:

• "Why can't I log in automatically?"
• "The services tab shows something is offline — what should I check?"
• "My balance seems wrong — how do I check usage?"

System diagnostics (when terminal access is enabled):

• "Check if all services are running"
• "How much disk space is left?"
• "Show me recent errors in the logs"

Conversation Memory

Concierge remembers your past conversations. When you ask a question, it retrieves relevant messages from your history based on:

• Recency — your most recent messages for immediate context
• Keywords — past messages matching keywords in your current question
• Importance — messages previously flagged as important (containing words like "error," "crash," "bug," or "problem" are automatically flagged)

This means Concierge can reference earlier troubleshooting sessions, remember your preferences, and avoid repeating explanations.

Your conversations are stored locally on your device — they are never sent to the central hub.

Stopping a Response

If Concierge is generating a long response you don't need, click the Stop button (red square) next to the input field. The response stops immediately and the partial text is kept.

Clearing History

Below the input field, click Clear History to erase all your Concierge conversations. This removes all stored messages and starts fresh.

Click Copy Conversation to copy the entire conversation to your clipboard.

Tips

• Be specific. "How do I set up Telegram?" gets a better answer than "Help with messaging."
• Ask follow-up questions. Concierge remembers the conversation context — you don't need to repeat background information.
• Use it for navigation. If you can't find a feature in the dashboard, ask Concierge where it is.
• Check terminal access for deeper diagnostics. With terminal enabled, Concierge can actually inspect your system rather than giving generic advice.

What Is Concierge

Concierge is a built-in AI assistant in your QUI Core dashboard. It lives in the Chat tab and helps you navigate the system, answer questions about features, troubleshoot issues, and run diagnostic commands on your machine.

How Concierge Differs from Characters

Concierge is not a character you build in Qui Anima. It's a platform-level assistant managed by the system administrator:

What Concierge Can Do

• Answer questions about QUI features, dashboard tabs, billing, trust scores, and services
• Explain concepts — how memory works, what trust scores mean, how to install apps
• Troubleshoot issues — check if services are running, diagnose connection problems
• Execute terminal commands — inspect system state, check logs, query service health (when terminal access is enabled)
• Remember past conversations — retrieves relevant context from your previous interactions

What Concierge Cannot Do

• Start or stop services — Concierge can check if a service is running but cannot restart it. It will tell you the exact command to run yourself.
• Add funds — billing actions require you to use the Billing tab
• Modify system files — Concierge won't edit configuration files directly
• Install packages — system-level package installation is out of scope

When Concierge can't fix something directly, it explains what the issue is and gives you the steps to resolve it yourself.

Cost

Concierge uses the same billing system as your characters. Each message costs tokens based on the model the administrator has configured. The cost appears in your usage reports under the Concierge app.

If you have no balance, Concierge won't be able to respond — add funds in the Billing tab.

What's Next

• Using Concierge — how to chat and what kinds of questions to ask
• Terminal Access — enabling command execution for diagnostics
• Not Working? — simple checklist when Concierge isn't responding

Concierge

Your built-in AI assistant in the QUI Core dashboard for navigating the system, diagnosing issues, and running commands.

In This Section

• What Is Concierge — Overview of the built-in assistant
• Using Concierge — How to chat, what it helps with, conversation memory
• Terminal Access — Enabling terminal, presets, safety layers
• Concierge Not Working? — User-level troubleshooting checklist

Remote Access

Remote access lets you use your QUI Core dashboard from another device — your phone, a laptop, or any browser — without being on the same network as your QUI installation.

How Remote Access Works

Two methods are available:

WebRTC P2P (Primary)

A direct peer-to-peer connection between your browser and your QUI Core instance, using WebRTC data channels:

Your browser ← WebRTC data channel (encrypted) → Your QUI Core
                        ↕
               Central hub (signaling only)

• End-to-end encrypted — the central hub only handles connection setup (signaling), not your traffic
• Full feature parity — everything works as if you were local (dashboard, Concierge, chat, terminal)
• Low latency — direct connection, no intermediate servers in the data path

The central hub exchanges connection details (SDP offers, ICE candidates) to establish the peer connection. Once connected, all traffic flows directly between your browser and your QUI Core.

Mothership Tunnel (Fallback)

When P2P connection fails (strict firewalls, symmetric NAT), traffic routes through the central hub:

Your browser → Central hub (proxy) → Your QUI Core

• Works behind strict firewalls — no direct connection needed
• Higher latency — traffic goes through an intermediate server
• Still authenticated — the hub verifies your identity before proxying

The system tries WebRTC P2P first and falls back to the tunnel automatically.

Eligibility

Remote access requires:

• Trust score ≥ 75 — your device must be trusted (see First Login)
• WebRTC P2P enabled — per-device setting in your remote access configuration
• Non-admin account — admin accounts use the tunnel, not WebRTC P2P
• Active tunnel connection — your QUI Core must have an active connection to the central hub for signaling

Setting Up Remote Access

1. Open the Remote Access tab in your QUI Core dashboard
2. Enable remote access for your installation
3. Configure which devices can connect
4. Your QUI Core establishes a tunnel to the central hub for signaling

Once enabled, you can access your QUI Core from the central hub's interface — it loads your QUI Core dashboard in an iframe with the WebRTC connection handling the traffic.

What Works Remotely

Everything that works locally also works remotely:

• QUI Core dashboard (all tabs)
• Concierge chat with terminal access
• Service monitoring
• Billing and account management
• All settings and configuration

The remote browser renders the same QUI Core frontend — it's loaded through the WebRTC connection or tunnel proxy. Authentication headers are injected automatically so that your QUI Core recognizes you as a remote user.

Security

Connections (Entanglement)

Before two QUI instances can exchange federated messages, they must establish a trust relationship called entanglement. This is a mutual approval process — both sides must agree before any messages can flow.

The Connection Flow

1. You send a message to a character on another instance
2. The system detects this is a federated address
3. An entanglement request is sent to the target instance (via the central hub)
4. The target instance's user sees a pending connection request
5. They approve (or deny) the request
6. Once approved, messages flow freely between the two instances

Both instances cache the entanglement status locally for fast lookup. The central hub stores the trust record permanently.

Managing Connections

Viewing Pending Requests

Incoming entanglement requests appear in the M2M tab of the QUI Core dashboard. You'll see:

• Which instance is requesting the connection
• When the request was sent

Approving a Connection

Click Approve on a pending request to establish the entanglement. Messages from that instance will begin flowing immediately.

Denying a Connection

Click Deny to reject the request. The requesting instance is notified. They can send another request later if desired.

Revoking a Connection

You can revoke an established entanglement at any time. Once revoked:

• No new messages can be sent between the instances
• Existing messages in your conversations are not deleted
• The other instance is notified of the revocation
• A new entanglement request would be needed to reconnect

Auto-Entanglement

When you send a message to a federated character and no entanglement exists, the system automatically sends an entanglement request on your behalf. You don't need to manually initiate the connection — just try to communicate, and the request is created.

Your message is held until the entanglement is approved. If using relay mode, the message waits in the hub. If using P2P mode, the delivery fails until the connection is established.

Encryption

All federated messages are encrypted before leaving your instance:

• Encryption keys are derived from your instance's federation credentials
• Messages are encrypted using Fernet (AES-128 + HMAC)
• The central hub relays encrypted blobs without the ability to read content
• Only the target instance can decrypt the message

This is the foundation of QUI's zero-knowledge architecture — the hub facilitates communication but cannot access the content of any message.

Connection Security

Addressing

Every character in the QUI ecosystem has an address. Local characters use simple names. Federated characters use the @character@node format to specify which instance they live on.

Address Formats

Local Addresses

When you create a character, it exists on your local QUI instance with the implicit address name@core. The core suffix means "this character lives here." You don't need to type @core — just the character name works for all local operations.

Federated Addresses

To reach a character on another instance, you need the full address: name@node. The node part identifies which QUI installation the character lives on. This can be:

• A domain name — alice@studio.qui.is
• An IP address — bob@192.168.1.50
• A unique instance ID — carol@8216f429-0826-158c-ae1e-c168f53e9063

The instance identifier is determined by the target's deployment configuration. Most instances use their hardware fingerprint UUID as their identity.

Using Federated Addresses

In Strings

Add a federated character as a participant using their full address:

1. Open conversation settings
2. Go to Participants
3. Enter the full address: @alice@studio.qui.is
4. If the instances are entangled (connected), the character appears as a participant

In M2M Messaging

Characters can send messages to federated addresses via trigger patterns:

[TRIGGER:m2m:alice@studio.qui.is:Hello, can you help with this?]

In ThinkThing

The Agent node can target federated addresses for cross-instance workflows.

How Routing Works

When a message is sent to an address, the system determines whether it's local or federated:

• If the node part is core (or missing) → local delivery — message goes directly to the character on this instance
• If the node part is anything else → federated delivery — message is encrypted and sent to the target instance via relay or P2P

This routing is automatic. You just use the address and the system handles the rest.

What Is Federation

Federation lets your characters communicate with characters running on other QUI instances across the network. Each QUI installation is independent — your data stays on your device — but characters can reach across instances to collaborate, share information, and work together.

Core Principles

Zero-Knowledge

The central hub handles connection brokering and message relay, but it never sees message content. Messages are encrypted before leaving your instance and decrypted only on the receiving instance. The hub sees encrypted blobs, not conversations.

Mutual Consent

Before two instances can exchange messages, they must establish a trust relationship called entanglement. Both sides must approve the connection. You can revoke it at any time.

Data Stays Local

Federation is about communication, not data sharing. Your character's memory, knowledge base, system prompts, and configuration never leave your machine. Only the messages themselves are transmitted.

How It Works

Your character → encrypts message → sends via relay or P2P → remote instance decrypts → delivers to target character

Two delivery modes are available:

Relay mode is the default and works in all scenarios. P2P mode is faster but requires both instances to be online simultaneously.

What Federation Enables

• Cross-instance character conversations — your character talks to a character on someone else's QUI instance
• Multi-instance collaboration — characters across different machines work together on tasks
• Entangled Strings — shared conversations that span multiple QUI instances
• M2M messaging across the network — the same @mention system that works locally extends to federated addresses

What's Next

• Addressing — the @character@node address format
• Connections — establishing and managing entanglements
• Remote Access — accessing your own QUI Core from another device

Federation

Cross-instance communication — your characters can talk to characters on other QUI installations with end-to-end encryption.

In This Section

• What Is Federation — Overview of cross-instance communication
• Addressing — The @character@node address format
• Connections — Entanglement — the connection permission flow
• Remote Access — Accessing your QUI Core from another device

Terminal Access

Characters can execute shell commands on the host machine through a multi-layered security system. Terminal access is powerful — a character can check system status, manage files, run scripts, and interact with the operating system — but it's carefully controlled.

How Terminal Access Works

When a character has the Terminal node enabled and needs to run a command, it includes a trigger in its response:

[TRIGGER:terminal:ls -la /var/log]

The command passes through five security layers before execution:

1. Dangerous pattern check — hardcoded patterns that are always blocked (fork bombs, recursive root deletion, disk formatting)
2. Whitelist — commands in the active preset's allowed list pass through
3. Blacklist — explicitly blocked commands are rejected
4. Path validation — commands accessing paths outside allowed directories are blocked
5. Terminal Service safety checker — a second independent safety layer at the execution point

Only commands that pass all five layers are executed. The result is returned to the character for analysis.

Presets

Terminal access is controlled through presets — named collections of allowed commands. Each preset defines what commands the character can run:

Presets are additive to your manual whitelist. You can select a preset AND add extra commands to the whitelist.

Enabling Terminal Access

Terminal access is configured in two places:

On the Character (Visual Builder)

Add the Terminal node to the character's canvas. This enables the character to use [TRIGGER:terminal:command] patterns. Configure allowed commands, blocked patterns, and path restrictions in the node settings.

On the User (Concierge Terminal Settings)

For the Concierge assistant specifically, terminal access is configured in the QUI Core dashboard → Chat tab → Terminal Settings:

1. Toggle Enable Terminal Access on
2. Select a preset (or Manual for custom)
3. Optionally add commands to the whitelist or blacklist
4. Toggle Require Manual Approval if you want to review each command before execution

Manual Approval Mode

When manual approval is enabled, every command proposed by the character shows an Execute button instead of running automatically. You see the command, decide if it's safe, and click Execute to proceed.

The Execute button bypasses the preset/whitelist filters (since you're explicitly approving), but the Terminal Service's safety layer still blocks inherently dangerous operations.

What's Always Blocked

Regardless of preset, whitelist, or manual approval, these patterns are always blocked by the dangerous command filter:

• Recursive root deletion (rm -rf /)
• Writing to disk devices (dd of=/dev/sda)
• Filesystem formatting (mkfs)
• Fork bombs
• Recursive world-writable permissions (chmod -R 777)
• Piping untrusted URLs to shell (curl | bash)
• Background process detachment (nohup, disown)

These protections exist at both the QUI Core command filter layer and the Terminal Service safety checker layer — two independent systems that must both pass.

Audit Trail

Every terminal command attempt is logged, regardless of outcome:

• Which user ran it
• The full command
• Whether it was allowed, blocked, executed, or failed
• The exit code and output (if executed)
• Which preset was active
• Execution duration

Audit logs are retained for 90 days and cleaned up automatically.

Terminal in ThinkThing

ThinkThing has 24 terminal node types — one generic and 23 specialized for specific domains (Git, Python, Docker, PostgreSQL, etc.). These nodes use an agentic loop:

1. You describe a task in natural language
2. The LLM decides what commands to run
3. Commands are executed through the security system
4. Results are fed back to the LLM
5. The LLM iterates until the task is complete or the iteration limit is reached

Each specialized node scopes the LLM to its domain — a "Git Terminal" node focuses the LLM on git operations, while a "Docker Terminal" node focuses on container management.

Local Models

QUI supports running LLMs entirely on your own hardware through Qllama — an isolated Ollama wrapper. Local models require no internet connection and incur no billing costs. Your data never leaves your machine.

What Is Qllama

Qllama runs the official Ollama Docker image with QUI-specific configuration. It provides:

• Port isolation — Qllama uses port 11435, separate from any native Ollama installation (11434). Both can run simultaneously.
• Data isolation — models are stored in a dedicated Docker volume, independent of any local Ollama installation
• Network integration — other QUI services can reach Qllama through the internal Docker network

Setting Up Local Models

1. Start Qllama

Qllama starts automatically with the QUI Core installer. You can also manage it manually from the Local Models tab in the QUI Core dashboard.

2. Pull a Model

Download a model from the Ollama model library:

From the dashboard's Local Models tab, search for and pull models. Popular choices:

3. Select the Model on a Character

In the Visual Builder:

1. Click the core Anima node
2. Select a local model from the model dropdown
3. Local models appear with a local- prefix

How Local Models Route

When a character uses a local model, the call chain is shorter:

Your character (Anima) → QUI Core Bridge → detects local-* prefix → routes to Qllama (localhost:11435)

The request bypasses the central billing hub entirely — no internet needed, no billing charges. The QUI Core Bridge detects the local-* prefix on the model name and routes directly to Qllama.

GPU Requirements

Local LLMs perform best with GPU acceleration:

• NVIDIA GPU with CUDA support — recommended
• NVIDIA Container Toolkit must be installed for Docker GPU passthrough
• Without GPU, models fall back to CPU inference (significantly slower)

The GPU Monitor panel in the QUI Core dashboard shows VRAM usage and loaded models.

Managing Models

The Local Models tab in the QUI Core dashboard lets you:

• View installed models — see what's downloaded and how much space each uses
• Pull new models — search and download from the Ollama library
• View running models — see what's currently loaded in VRAM
• Monitor GPU usage — VRAM consumption and utilization

When to Use Local vs Cloud

You can mix local and cloud models across characters — one character uses a local model for privacy-sensitive tasks while another uses a cloud model for complex reasoning.

Tip: Start with a small local model like phi3:mini to verify your GPU setup works, then pull larger models as needed.

MCP (Model Context Protocol) is an open standard for connecting AI models to external tools and services. QUI's MCP Gateway provides access to over 165 tools across 9 categories — from GitHub and Docker to Telegram, Notion, and database management.

What MCP Tools Enable

When you enable MCP tools on a character, that character can:

• Send and receive Telegram messages
• Create GitHub issues and pull requests
• Query databases (PostgreSQL, Redis, MongoDB, SQLite)
• Manage Docker containers
• Send emails and Slack messages
• Create Trello cards and Notion pages
• Search the web (DuckDuckGo, Brave)
• Interact with web pages via Playwright
• And much more

The character uses these tools through trigger patterns in its responses. You configure which tools each character has access to, and provide the necessary API credentials.

Tool Categories

Enabling MCP Tools

In the Visual Builder

1. Open the Cognitive Design tab in the palette
2. Find the MCP section with category flyouts
3. Click a category to see available services
4. Click a service to add it as a node on the canvas
5. Click the node to configure credentials (API keys, tokens, etc.)

Each service node stores its own credentials. For example, the GitHub node needs a personal access token, the Telegram node needs a bot token, and the Slack node needs a signing secret.

Credentials

Each MCP service has specific credential requirements. The node configuration panel shows what's needed:

• GitHub — Personal access token
• Telegram — Bot token (from @BotFather)
• Slack — Bot token + signing secret
• Discord — Bot token + public key
• Email — SMTP/IMAP credentials
• AWS — Access key ID + secret
• Database services — Connection string or host/port/credentials

Credentials are stored securely in the character's configuration.

READ THE FULL INTEGRATION GUIDE

How Tools Execute

When a character decides to use an MCP tool, it emits a trigger in its response:

[TRIGGER:mcp:github:create_issue:{"title":"Bug report","body":"Details...","repo":"org/repo"}]

The trigger system:

1. Detects the pattern in the LLM response
2. Strips it from the displayed text (the user sees clean output)
3. Resolves the service credentials from the character's MCP configuration
4. Sends the request to the MCP Gateway
5. Returns the result to the character for follow-up

In agentic mode, the character can chain multiple tool calls — create a GitHub issue, then send a Slack notification about it, then update a Trello card.

MCP in ThinkThing

ThinkThing has 37 dedicated MCP nodes — one per service. Each node is pre-configured with the service's available tools. Add the node to a graph, connect it to an Anima character with the corresponding MCP service enabled, and configure the specific tool and parameters.

Tool Access Control

MCP access is controlled at multiple levels:

1. Character level — only tools whose nodes are on the canvas are available
2. Service level — each service can be individually enabled/disabled
3. Tool level — within a service, individual tools can be toggled
4. Credential level — tools without valid credentials won't execute

This layered approach ensures characters only access the specific tools they need.