User Manual

SovereignAI for iOS

Getting Started

When you first open SovereignAI, you will be guided through a short onboarding flow:

• Server URL — Enter the base URL of your AI chat server (for example, http://192.168.1.10:11434 for a local Ollama instance).
• Authentication — Choose how the app should authenticate with your server (see Authentication Methods below).
• Test Connection — Tap the test button to verify the app can reach your server and retrieve the list of available models.
• Select a Model — Pick the model you want to use from the list returned by your server.

Once setup is complete, you are taken to the chat screen and can start a conversation immediately.

Authentication Methods

SovereignAI supports four authentication options. Choose the one that matches your server configuration:

• None — No credentials are sent. Use this for local servers that do not require authentication.
• API Key Header — Sends an API key in a custom request header. You can configure the header name (defaults to X-Api-Key). The key is stored securely in the iOS Keychain.
• Bearer Token — Sends a bearer token in the Authorization header. Enter your token during setup; it is stored in the iOS Keychain.
• OpenID Connect (OIDC) — Uses the device authorization flow. The app displays a code and a URL; open the URL in a browser, enter the code, and sign in with your identity provider. Tokens are stored in the iOS Keychain and refreshed automatically.

Chatting

Type your message in the input field at the bottom of the screen and tap send. The assistant's response streams in token by token as it is generated.

• Thinking indicator — While the model is generating a response, a shimmer animation is displayed. If the model outputs reasoning tokens (e.g. <think> blocks), the reasoning is shown in a collapsible "Reasoning" section you can expand to read.
• Markdown rendering — Assistant responses are rendered with full Markdown support, including headings, bold, italic, strikethrough, lists, links, blockquotes, tables, and task lists.
• Code blocks — Fenced code blocks are syntax-highlighted and include a copy button so you can quickly copy code to the clipboard.
• LaTeX & math — Mathematical expressions are rendered using Unicode symbols. Display math is supported with \[...\] and $$...$$ delimiters; inline math uses \(...\). Math blocks appear in a styled container with a copy button.
• Tables — Markdown tables (pipe-delimited) are rendered as a horizontally scrollable grid with column headers and row dividers. A header bar displays a table icon and a copy button that exports the table data as tab-separated values (TSV) to the clipboard.
• Blockquotes — Nested blockquotes are shown with left border indicators and progressively reduced opacity for each nesting level.
• Task lists — Lines beginning with - [ ] or - [x] are displayed as checkbox items.

Message Actions

Long-press any message to open its context menu. The following actions are available:

• Copy — Copy the message text to the clipboard.
• Edit — Available on your own messages only. Edit the text and resend it; the conversation continues from the edited message. Edited messages are marked with an "(edited)" indicator.
• Regenerate Response — Available on your own messages only. Ask the model to generate a new response.
• Delete — Remove a single message from the conversation.
• Delete & Following — Remove the selected message and every message after it.

Tools

SovereignAI includes three built-in tools that the model can use during a conversation:

• Web Search — Searches the web using DuckDuckGo. When the model decides a web search would help answer your question, it performs a search automatically and uses the results to inform its response.
• URL Reading — Fetches and reads the content of a web page or PDF document. The model can use this to pull in information from a specific URL. When a PDF link is provided, the app downloads the document and extracts text page by page using iOS's built-in PDFKit framework. If the PDF contains only scanned images with no extractable text, the tool reports that. For unsupported content types (such as images or video), the tool returns a clear message instead of garbled data.
• Image Search — Searches DuckDuckGo for images, diagrams, and charts. When the model needs visual content, it performs an image search automatically and displays the results as a scrollable thumbnail gallery below its response. Tap any thumbnail to open a detail view showing the full-size image, its title, pixel dimensions, and a link to the source page.

All three tools are enabled by default. You can enable or disable them in Settings > Tools. When a search tool is used, the sources appear as an expandable section below the assistant's message. Image search results appear as a scrollable row of thumbnails that can be tapped for a full-size view with a link to the source page.

Managing Chats

The session list shows all your conversations. Each session row displays color-coded label dots (up to five, with an overflow count if there are more) so you can see at a glance which labels are applied.

• Create a new chat — Tap the new-chat button to start a fresh conversation.
• Delete a chat — Swipe left on a session to reveal the delete action.
• Session menu — Tap the ellipsis (…) button on a session row to open a menu where you can add a new label or remove existing labels directly from the session list.
• Clear a chat — Open a conversation and tap the settings icon in the toolbar to access per-chat options, including clearing all messages from the current chat.
• Search — Use the search bar to find chats by title, label, or message content. Results match across all conversations.

Exporting Chats

Swipe right on a session in the session list to reveal the export action. Choose a format:

• Markdown — Exports the conversation as a .md file with proper formatting.
• JSON — Exports the raw conversation data as a .json file.
• Plain Text — Exports a simple text transcript.

After choosing a format, the iOS share sheet opens so you can save the file, send it via AirDrop, or share it with any other app.

Labels

Labels let you organize your conversations with color-coded tags. Each label is automatically assigned a consistent color derived from its name, so the same label always appears in the same color.

Adding and removing labels. Open a conversation and tap the settings icon to access label management. From there you can type a new label name and add it, or remove any existing label. Labels from your other conversations are shown as suggestions so you can reuse them with a single tap. You can also add or remove labels directly from the session list using the ellipsis (…) menu on each session row.

Label bar. When a conversation has labels, they appear as a row of colored capsules at the top of the chat view. Tap a label capsule to open chat settings; long-press it to insert the label (prefixed with #) into the input field.

Cross-chat context with #. When you include a #label reference in a message (for example, #work), SovereignAI loads the conversations from all other chats that have that label and includes them as context in the request sent to the model. This lets the model draw on information from related conversations when answering. You can reference multiple labels in a single message. The referenced content is subject to the context window limit, so if the combined conversations are too large, only the most recent messages are included.

Autocomplete with #. While typing a message, type # followed by characters to see matching label suggestions above the input field. Tap a suggestion to insert it. This provides a quick way to add label references without having to remember exact label names.

Filtering by label. At the top of the session list, a horizontal bar shows all labels used across your conversations. Tap one or more labels to filter the list and show only conversations that have at least one of the selected labels.

Label dots. Each session in the list shows up to five small colored dots representing its labels. If a session has more than five labels, a count (e.g., “+2”) is displayed next to the dots.

Settings

Open Settings from the session list. Settings are organized into the following groups:

• Server — Change your server URL, authentication method, or credentials. Test the connection at any time.
• Model — Select a different model, set a custom system prompt, and adjust sampling parameters under Advanced Settings:
  • Temperature — Controls randomness. Lower values produce more focused responses; higher values produce more creative ones.
  • Context Window — How much conversation history to include in each request.
  • Top-p — Limits word choices to the most likely options.
  • Frequency Penalty — Reduces repetition by discouraging the model from repeating the same phrases.
  • Presence Penalty — Encourages the model to bring up new topics.
  • Max Tokens — Limits the maximum length of the model's response.
  • Seed — Set a fixed number for reproducible responses, or leave at zero for random.
• Tools — Enable or disable web search, URL reading, and image search. When web search is enabled, you can also adjust the maximum number of search results (1–10, defaults to 5).
• System — View storage information, delete all chats, or reset the app to its default state (clears all settings, credentials, and conversations).

Appearance

SovereignAI supports both light and dark mode. The app automatically follows your device's system appearance setting.