# Assistant Memory: Persistent Facts Across Chats
Source: https://docs.rikka-ai.com/assistants/memory

Enable AI memory so Rikka remembers key facts about you across conversations, and learn how to view, edit, and scope those memories.

Memory lets an assistant remember important facts about you — your preferences, past decisions, or background context — and automatically inject them into future conversations. Instead of re-explaining yourself every time you start a new chat, the assistant already knows what matters.

## How memory works

When memory is enabled, Rikka's configured **fast model** monitors the conversation and extracts facts worth remembering — things like your name, your preferred coding language, or dietary restrictions. Those facts are stored as discrete memory entries. Before each new conversation, the relevant entries are injected into the context, giving the assistant a head start.

<Note>
  Memory extraction runs through the **fast model** you have configured in **Settings → Models**. Choose a quick, low-cost model for this role to keep extraction fast and inexpensive.
</Note>

## Enabling memory

<Steps>
  <Step title="Open the assistant">
    Go to **Settings → Assistants** and tap the assistant you want to configure.
  </Step>

  <Step title="Open the Memory tab">
    Inside the assistant detail screen, tap the **Memory** tab.
  </Step>

  <Step title="Toggle Memory on">
    Enable the **Memory** switch. The assistant will begin extracting and storing facts from new conversations.
  </Step>
</Steps>

## Memory settings

<ParamField type="boolean">
  Master switch for memory. When off, no facts are extracted and no memories are injected into conversations.
</ParamField>

<ParamField type="boolean">
  When enabled, this assistant reads from and writes to the shared global memory pool rather than its own private store. Only available when **Memory** is turned on.
</ParamField>

<ParamField type="boolean">
  When enabled, the assistant can reference a summary of your recent past conversations, giving it broader continuity beyond individual memory entries.
</ParamField>

<ParamField type="boolean">
  Injects a time-interval reminder into the context so the assistant is aware of how much time has passed since your last interaction.
</ParamField>

## Global vs. assistant-isolated memory

By default each assistant maintains its own private memory store, so facts learned by one persona do not leak into another.

<Tip>
  Enable **Use Global Memory** if you want facts to be shared across all your assistants. This is useful when you have several assistants that all need to know the same things about you — your name, time zone, or ongoing projects — without duplicating entries.
</Tip>

| Setting                   | Behaviour                                                                                        |
| ------------------------- | ------------------------------------------------------------------------------------------------ |
| **Use Global Memory** off | Facts are stored privately and are only visible to this assistant                                |
| **Use Global Memory** on  | Facts are stored in a shared pool visible to all assistants that also have global memory enabled |

## Viewing and editing memories

You can inspect, add, edit, or delete individual memory entries at any time.

<Steps>
  <Step title="Open the Memory tab">
    Navigate to **Settings → Assistants**, tap the assistant, and select the **Memory** tab.
  </Step>

  <Step title="Browse entries">
    Scroll through the list of stored memory entries. Each entry shows its content.
  </Step>

  <Step title="Edit an entry">
    Tap the pencil icon on any entry to open an edit dialog. Modify the text and tap **Save**.
  </Step>

  <Step title="Delete an entry">
    Tap the trash icon on any entry. Confirm the deletion in the dialog that appears.
  </Step>

  <Step title="Add an entry manually">
    Tap the **+** button at the top-right of the memory list to write a new fact directly, without waiting for the model to extract it.
  </Step>
</Steps>

<Warning>
  Deleting a memory entry is permanent. The assistant will have no recollection of that fact in future conversations unless you re-add it manually or the model extracts it again.
</Warning>

## Recent chats reference

When **Enable Recent Chats Reference** is turned on, the assistant gains access to a summarised view of your recent conversation history. This is distinct from individual memory entries — it provides a broader narrative of what you have been discussing lately rather than a list of discrete facts.

Use this feature when you want the assistant to pick up naturally from previous sessions even if no specific facts were extracted into memory.


# Assistants: Personas, Models, and Settings
Source: https://docs.rikka-ai.com/assistants/overview

Create and manage reusable AI personas that bundle a system prompt, model choice, and generation settings into a single switchable profile.

Assistants are saved configurations that give the AI a distinct identity and behaviour. Each assistant stores a system prompt, an optional model override, generation parameters, and a host of advanced options — so you can switch between a coding helper, a creative writing partner, and a language tutor with a single tap, without reconfiguring anything.

## Creating an assistant

<Steps>
  <Step title="Open Settings">
    Tap the settings icon from the main screen to open the Settings menu.
  </Step>

  <Step title="Navigate to Assistants">
    Select **Assistants** from the list.
  </Step>

  <Step title="Add a new assistant">
    Tap the **+** button in the top-right corner. Enter a name for your assistant, then tap **Save**.
  </Step>

  <Step title="Configure the assistant">
    Tap the newly created assistant card to open its detail pages and fill in the fields described below.
  </Step>
</Steps>

## Importing a SillyTavern character card

Rikka can import character cards in the standard SillyTavern format, giving you instant access to community-created personas without any manual setup.

<Steps>
  <Step title="Open the creation sheet">
    Tap the **+** button on the Assistants screen.
  </Step>

  <Step title="Choose your file format">
    Tap **Import Tavern PNG** to pick a character card image, or **Import Tavern JSON** to pick a JSON file.
  </Step>

  <Step title="Confirm the import">
    Rikka reads the embedded metadata, builds the system prompt automatically, and saves the assistant — including the card artwork as the chat background.
  </Step>
</Steps>

<Note>
  Rikka supports character card spec versions **v2** and **v3**. Importing a card automatically populates the name, system prompt, description, personality, scenario, and first message.
</Note>

## Basic configuration

<CardGroup>
  <Card title="Identity" icon="user">
    Set the assistant's **name** and **avatar** to make it easy to recognise at a glance. Enable **Use Assistant Avatar** to display the assistant's avatar in place of the model icon inside the chat.
  </Card>

  <Card title="Model override" icon="cpu">
    Set a **Chat Model** to pin this assistant to a specific provider and model. Leave it blank to use whatever model is currently selected as the global default.
  </Card>

  <Card title="System prompt" icon="message-square">
    Write the core instructions that define how the assistant thinks and responds. The system prompt is sent at the beginning of every conversation. You can use [placeholder variables](/assistants/prompt-injection#placeholder-variables) inside the system prompt.
  </Card>

  <Card title="Tags" icon="tag">
    Assign tags to organise your assistants. Use the tag filter bar on the Assistants screen to quickly find the one you need.
  </Card>
</CardGroup>

## Key settings reference

### Generation settings

<ParamField type="float | null">
  Controls response randomness. Values range from `0` (deterministic) to `2` (very creative). Leave unset to use the model's default.
</ParamField>

<ParamField type="float | null">
  Nucleus sampling threshold. A lower value restricts the model to higher-probability tokens. Leave unset to use the model's default. Avoid setting both `temperature` and `topP` at the same time.
</ParamField>

<ParamField type="int | null">
  Maximum number of tokens the model may generate in a single response. Leave unset for no explicit cap.
</ParamField>

<ParamField type="enum">
  Controls how much chain-of-thought reasoning the model performs before answering. `AUTO` lets the model decide.
</ParamField>

<ParamField type="boolean">
  When enabled, the assistant's response streams token-by-token as it is generated. Disable this if you prefer to receive the complete response at once.
</ParamField>

### Context and history

<ParamField type="int">
  The maximum number of recent messages included as conversation history in each request. Set to `0` to include all messages. Reducing this value lowers token usage for long conversations.
</ParamField>

### Preset messages

<ParamField type="list">
  A list of messages that are always prepended to the conversation before any user input. Use preset messages to inject fixed examples, persona warm-up exchanges, or boilerplate context that every conversation with this assistant should start with.
</ParamField>

### HTTP overrides

<ParamField type="list">
  Additional HTTP headers to send with every request made by this assistant. Useful for routing through proxies or satisfying custom authentication requirements.
</ParamField>

<ParamField type="list">
  Extra fields to merge into every request body. Use this to pass provider-specific parameters that Rikka does not expose directly.
</ParamField>

### Tools and integrations

<ParamField type="list">
  The MCP (Model Context Protocol) servers this assistant is allowed to call. Tools from servers not in this list are hidden from the model.
</ParamField>

<ParamField type="list">
  Built-in device tools available to this assistant. **TimeInfo** is included by default, letting the model query the current date and time.
</ParamField>

<ParamField type="set">
  The set of skill names that are active for this assistant. Skills extend what the assistant can do beyond standard chat, such as web search or image generation, depending on what your setup supports.
</ParamField>

### Appearance

<ParamField type="string | null">
  URI of a custom background image shown in the chat view for this assistant. Import a SillyTavern character card to set this automatically.
</ParamField>

<ParamField type="float">
  Opacity of the background image, from `0.0` (invisible) to `1.0` (fully opaque).
</ParamField>

## Switching assistants in chat

Tap the assistant name or avatar shown in the chat toolbar to open a picker. Select any assistant to apply its persona and settings to the current or next conversation. The change takes effect immediately for new messages.

## Quick Messages

Quick Messages are pre-written message templates you can attach to an assistant and fire off with a single tap during a conversation — ideal for recurring prompts like "summarise the above" or "translate to English".

<Steps>
  <Step title="Create quick messages">
    Go to **Settings → Quick Messages** and tap **+** to create a template with a title and content.
  </Step>

  <Step title="Attach to an assistant">
    Open the assistant's **Extensions** tab, select the **Quick Messages** sub-tab, and toggle on the messages you want available.
  </Step>

  <Step title="Use in chat">
    Tap the quick-message icon in the chat toolbar to see your attached templates and send one instantly.
  </Step>
</Steps>

## Regex transformers

Regex transformers let you define find-and-replace rules that run on messages before they are displayed or sent. This is useful for sanitising output, reformatting citations, or applying cosmetic changes.

Each rule has the following fields:

| Field            | Description                                                                                       |
| ---------------- | ------------------------------------------------------------------------------------------------- |
| **Name**         | A human-readable label for the rule                                                               |
| **Find pattern** | A standard regular expression to match against                                                    |
| **Replace with** | The replacement string (supports capture group references)                                        |
| **Scope**        | Whether the rule applies to **User** messages, **Assistant** messages, or both                    |
| **Visual only**  | When enabled, the replacement is shown in the UI but the original text is still sent to the model |

<Tip>
  Enable **Visual only** when you want to clean up the display without changing what the model actually sees — for example, stripping markdown syntax that your renderer already handles.
</Tip>

To manage regex rules, open the assistant's **Prompt** tab and scroll to the **Regex** section.


# Prompt Injections and Lorebooks Explained
Source: https://docs.rikka-ai.com/assistants/prompt-injection

Automatically insert context snippets into conversations using mode injections and lorebooks, with full control over position, priority, and triggers.

Prompt injections are snippets of text that Rikka automatically inserts into a conversation's context at a position you choose. They let you augment any assistant with additional instructions, reference material, or world-building lore — without cluttering the main system prompt. Lorebooks extend this idea by grouping multiple injection entries and activating each one only when specific keywords appear in the conversation.

## Core concepts

<CardGroup>
  <Card title="Mode Injection" icon="toggle-right">
    A manually toggled snippet. Enable it on an assistant and it is always injected whenever that assistant is active. Ideal for "modes" like a formal writing style or a step-by-step reasoning format.
  </Card>

  <Card title="Lorebook" icon="book-open">
    A named collection of entries. Each entry carries keywords; when those keywords appear in recent messages, the entry's content is automatically injected. Perfect for world-building reference material or project glossaries.
  </Card>
</CardGroup>

## Injection positions

Every injection targets a specific location in the message list. Choose the position that best matches the intent of your content.

<Accordion title="Before System Prompt">
  Inserts the content immediately before the existing system message. Use this for high-priority framing that should precede all other instructions.
</Accordion>

<Accordion title="After System Prompt">
  Appends the content to the end of the system message. This is the most common position — it extends the system prompt without replacing it.
</Accordion>

<Accordion title="Top of Chat">
  Places the content just before the first user message in the conversation history. Useful for setting scene context that appears once at the start.
</Accordion>

<Accordion title="Bottom of Chat">
  Inserts the content immediately before the most recent user message. Good for reminders or dynamic context that should be fresh in the model's attention.
</Accordion>

<Accordion title="At Depth">
  Inserts at a specific depth from the end of the message list (e.g., depth 4 = four messages from the bottom). Use this for precise placement relative to recent conversation turns.
</Accordion>

## Creating a mode injection

<Steps>
  <Step title="Open Settings">
    Tap the settings icon from the main screen.
  </Step>

  <Step title="Navigate to Prompts">
    Select **Prompts** (also accessible from the **Extensions** tab of an assistant via the **Go to Prompts** button).
  </Step>

  <Step title="Add a mode injection">
    Tap **+** in the Mode Injections section. Give it a name, write the content, choose an injection position, set a role (User or Assistant), and assign a priority.
  </Step>

  <Step title="Save">
    Tap **Save**. The injection is now available to attach to any assistant.
  </Step>
</Steps>

## Creating a lorebook

<Steps>
  <Step title="Open Settings → Prompts">
    Navigate to the Lorebooks section and tap **+** to create a new lorebook.
  </Step>

  <Step title="Name the lorebook">
    Give it a descriptive name such as "Fantasy World Lore" or "Project Glossary".
  </Step>

  <Step title="Add entries">
    Inside the lorebook, tap **+** to create an entry. For each entry, configure:

    * **Keywords** — the words or patterns that trigger this entry.
    * **Content** — the text to inject when triggered.
    * **Injection position** and **role**.
    * **Scan depth** — how many recent messages to check for keyword matches.
    * **Use regex** — treat keywords as regular expressions instead of plain text.
    * **Case sensitive** — whether matching respects letter case.
    * **Constant active** — inject this entry unconditionally, regardless of keywords.
  </Step>

  <Step title="Save the lorebook">
    Tap **Save**. The lorebook and all its entries are now ready to attach to assistants.
  </Step>
</Steps>

<Tip>
  Set **Constant active** on an entry if you want it to always inject, making it behave like a persistent mode injection that lives inside a lorebook for organisational purposes.
</Tip>

## Attaching injections to an assistant

<Steps>
  <Step title="Open the assistant's Extensions tab">
    Go to **Settings → Assistants**, tap an assistant, and select the **Extensions** tab.
  </Step>

  <Step title="Enable mode injections">
    Switch to the **Mode Injections** sub-tab and toggle on any injections you want active for this assistant.
  </Step>

  <Step title="Enable lorebooks">
    Switch to the **Lorebooks** sub-tab and toggle on any lorebooks whose entries should be available in this assistant's conversations.
  </Step>
</Steps>

## Key assistant fields

<ParamField type="set">
  The set of mode injections that are active for this assistant. Any injection in this set is included in every conversation, regardless of message content.
</ParamField>

<ParamField type="set">
  The set of lorebooks attached to this assistant. Entries within those lorebooks fire automatically when their keywords are detected in recent messages.
</ParamField>

<ParamField type="boolean">
  When enabled, each individual conversation can override this assistant's system prompt. Turn this on if you want to customise the system prompt on a per-chat basis without changing the assistant's default.
</ParamField>

<ParamField type="boolean">
  When enabled, each conversation can bind its own set of mode injections and lorebooks, overriding the assistant-level selection. Enable this when you want to mix and match injections dynamically per conversation.
</ParamField>

## Message template

The **message template** wraps every user message before it is sent to the model. The default value is `{{message}}`, which sends the message as-is. You can add surrounding context, formatting, or persona hints around it.

<ParamField type="string">
  A template string applied to each outgoing user message. Must include `{{message}}` somewhere so the user's actual text is passed through. Rikka will flag an error if this placeholder is missing.
</ParamField>

<Warning>
  If `{{message}}` is missing from the message template, the user's actual message will not be included in the request. Rikka highlights this as an error in the editor — always verify the template before saving.
</Warning>

## Placeholder variables

Placeholder variables can be used inside the **message template**, the **system prompt**, or any injection content. Rikka replaces them with live values at the time each message is sent. Both `{{variable}}` and `{variable}` syntax are accepted.

| Variable             | Description                                                   |
| -------------------- | ------------------------------------------------------------- |
| `{{cur_date}}`       | Current date, formatted for your locale                       |
| `{{cur_time}}`       | Current time, formatted for your locale                       |
| `{{cur_datetime}}`   | Current date and time, formatted for your locale              |
| `{{model_id}}`       | The model ID string of the active model                       |
| `{{model_name}}`     | The display name of the active model                          |
| `{{locale}}`         | Your device's current locale (e.g. `English (United States)`) |
| `{{timezone}}`       | Your device's current time zone name                          |
| `{{system_version}}` | Android version running on the device                         |
| `{{device_info}}`    | Device brand and model name                                   |
| `{{battery_level}}`  | Current battery charge level as a percentage                  |
| `{{nickname}}`       | Your display nickname from **Settings → Display**             |
| `{{user}}`           | Same as `{{nickname}}` — your display name                    |
| `{{char}}`           | The name of the current assistant                             |

Tap any variable chip shown beneath the system prompt or template editor to insert it at the cursor position.

## How injection priority works

When multiple injections target the same position, Rikka sorts them by their priority value in descending order — higher number means injected first. Injections with the same role at the same position are merged into a single message to keep the conversation structure clean.

<Note>
  Rikka is careful not to insert injected messages between a user message and an immediately following assistant message that contains tool calls, because some providers (such as DeepSeek) require those two messages to be adjacent for correct reasoning.
</Note>


# Conversation Branching: Explore Alternate Chat Paths
Source: https://docs.rikka-ai.com/chat/branching

Fork any conversation at a specific message to explore different answers, compare models, or A/B test prompts — all without losing prior context.

Branching lets you diverge a conversation from any point and explore a different direction without overwriting what came before. Every branch shares the full message history up to the split point, so the AI always has the context it needs.

## What Branching Is

Every message in Rikka is stored inside a **message node**. A node can hold multiple versions of the same message — for example, the original assistant reply and one or more regenerated alternatives. When you regenerate a response, a new version is added to the same node, and you can swipe left and right through the versions at that position without affecting any other part of the conversation.

A **fork** (also called a branch) is something bigger: it creates a brand-new conversation that starts with a copy of every message up to and including the message you forked from. Both the original conversation and the fork are independent — editing one does not affect the other.

## Creating a Branch

<Steps>
  <Step title="Find the message you want to fork from">
    Scroll to any message in the conversation — it can be a user message or an assistant reply.
  </Step>

  <Step title="Open the message action menu">
    Long-press the message, or tap the overflow (three-dot) menu that appears below it.
  </Step>

  <Step title="Tap Fork">
    Select **Fork** from the action menu. Rikka copies all messages up to and including the selected one into a new conversation and navigates you there immediately.
  </Step>

  <Step title="Continue from the fork point">
    You are now in a fresh conversation that picks up exactly where the fork was made. Send a different prompt, change the model, or adjust the assistant settings — none of these changes affect the original conversation.
  </Step>
</Steps>

## Navigating Between Versions on the Same Node

When a message node has more than one version (created by **Regenerate** or **Edit**), a small branch navigator appears inline with that message. It shows the current version number and the total, for example **2 / 3**.

* Tap the **left arrow** (←) to go to the previous version.
* Tap the **right arrow** (→) to go to the next version.

The arrows dim when you are already at the first or last version. All subsequent messages in the conversation update automatically to reflect the selected branch of history — Rikka always shows the path formed by the currently selected version at each node.

<Tip>
  Use branching to A/B test prompts or compare how different models answer the same question. Fork the conversation at your user message, switch models, and send the same question — then compare both forks side by side.
</Tip>

## How Branched Conversations Are Stored

<CardGroup>
  <Card title="Shared history up to the branch point" icon="code-branch">
    The forked conversation contains full copies of every message up to the split. Editing a message in the fork does not modify the original conversation.
  </Card>

  <Card title="Independent from that point on" icon="arrows-split-up-and-left">
    Any new messages sent after the fork exist only in that conversation. The original continues on its own timeline.
  </Card>

  <Card title="Files are duplicated" icon="copy">
    Any image or document attachments in the copied messages are duplicated into the fork's storage so that deleting the original conversation does not break the fork.
  </Card>

  <Card title="Same assistant and settings" icon="robot">
    The fork inherits the original conversation's assistant, system prompt overrides, injected modes, and lorebook bindings, giving you a consistent starting point.
  </Card>
</CardGroup>

## Why Branching Is Useful

* **Exploring different answers** — Not happy with a response? Fork from your last user message, resend it, and compare both answers without losing either.
* **Comparing models** — Fork the conversation twice from the same point and set each fork to a different model. Run the same follow-up question in each to directly compare quality or style.
* **Safe experimentation** — Try a risky or speculative prompt in a fork. If the conversation goes off track you can simply abandon the fork and return to the original.
* **Sharing a subset** — Fork at an early message to create a clean, shorter version of a conversation you want to share, without exposing the full history.

<Note>
  Branches are stored locally like any other conversation. They appear in your conversation history alongside originals, sorted by last updated time. You can rename, pin, or delete a branch the same way you manage any other conversation.
</Note>


# Managing Conversations in the Rikka Chat Interface
Source: https://docs.rikka-ai.com/chat/conversations

Start chats, switch models, edit and regenerate messages, render rich Markdown, favorite content, share, and track token usage in Rikka.

The chat screen is where you spend most of your time in Rikka. Every conversation is stored locally on your device, and you can create as many as you need across multiple AI providers without any limit imposed by the app.

## Starting a New Conversation

Tap the **compose** icon (pencil-and-paper) in the top-right corner of the chat toolbar to open a fresh conversation. Rikka automatically generates a title for the conversation once you send your first message. You can rename it at any time by tapping the title in the top bar — an inline edit dialog will appear.

<Steps>
  <Step title="Open the chat screen">
    Launch Rikka. The last conversation you used opens automatically.
  </Step>

  <Step title="Tap the new-chat icon">
    Tap the **MessageAdd** icon in the top-right corner. A blank conversation opens immediately.
  </Step>

  <Step title="Type your message and send">
    Enter your text in the input bar at the bottom and tap the **send** button (arrow-up). Rikka streams the reply in real time.
  </Step>
</Steps>

## Switching Between Conversations

All your past conversations live in the **history drawer**. On phones, swipe from the left edge or tap the hamburger menu icon to open the drawer. On large-screen devices (tablets and foldables in landscape), the drawer is always visible on the left side.

Inside the drawer you will find:

* A **search bar** that jumps to the conversation search page where you can search message content across all chats using full-text search.
* A **History** shortcut that takes you to the full conversation list.
* The conversation list itself, sorted by most recently updated, with pinned items at the top.

Tap any conversation to switch to it. Long-press a conversation item to reveal context menu options such as rename, pin, move to a different assistant, or delete.

<Tip>
  Pin frequently used conversations by long-pressing them in the drawer and selecting **Pin**. Pinned conversations always appear at the top of the list.
</Tip>

## Switching Models Mid-Conversation

You can change the active AI model at any point without starting a new chat.

Tap the **model selector** shown below the conversation title in the top bar (or inside the input bar on some screen sizes). A picker lists all models from every provider you have configured. Select a new model — subsequent messages will use it while earlier messages remain unchanged.

<Note>
  Switching models does not re-generate any previous messages. Only new messages sent after the switch use the newly selected model.
</Note>

## Regenerating and Editing Messages

Rikka lets you refine any exchange without losing context.

<CardGroup>
  <Card title="Regenerate a Response" icon="rotate-right">
    Long-press an assistant message or tap the action menu that appears beneath it, then choose **Regenerate**. Rikka re-runs the same prompt and appends a new response as an additional branch on that node.
  </Card>

  <Card title="Edit a User Message" icon="pencil">
    Long-press your own message and tap **Edit**. The text loads back into the input bar. Modify it and send — Rikka re-generates the assistant reply from that point forward.
  </Card>
</CardGroup>

You can also **delete** any individual message by long-pressing it and selecting **Delete** from the action menu. Deletion is blocked while a response is actively streaming; stop generation first.

## Markdown Rendering

Rikka renders rich content inside assistant (and user) messages:

<Accordion title="Code blocks with syntax highlighting">
  Fenced code blocks (` ```language `) are highlighted using a built-in syntax highlighter. Tap the copy icon in the top-right corner of any code block to copy its contents to the clipboard.
</Accordion>

<Accordion title="LaTeX formulas">
  Inline math enclosed in `$...$` and display math in `$$...$$` are rendered natively. Both inline and block equations are supported.
</Accordion>

<Accordion title="Tables">
  Standard Markdown tables render with proper column alignment. Scroll horizontally on narrow screens to see wide tables.
</Accordion>

<Accordion title="Mermaid diagrams">
  Mermaid diagram code blocks (` ```mermaid `) render as interactive diagrams. Tap the **Export** button on any diagram to save it as an image.
</Accordion>

## Favoriting Messages

Mark an important assistant response so you can find it later from any conversation.

Tap the **heart** (favorite) icon below a message. A filled heart indicates the message is saved. Access all favorited messages from the drawer by tapping the **Favorites** icon. Tapping a favorite jumps you straight to that message inside its original conversation.

## Sharing a Conversation

Rikka can export any selection of messages in two formats.

<Steps>
  <Step title="Enter selection mode">
    Long-press any message and tap **Share**. Rikka pre-selects all messages up to and including that one and enters multi-select mode.
  </Step>

  <Step title="Adjust the selection">
    Tap individual messages to add or remove them from the selection. Use the **Select All** button in the floating toolbar to toggle all messages.
  </Step>

  <Step title="Choose an export format">
    Tap the **Confirm** (checkmark) button. The export sheet appears with two options:

    * **Markdown** — exports a `.md` file you can share via any app.
    * **Image** — renders the selection as a PNG with optional expanded reasoning sections and a Rikka watermark.
  </Step>
</Steps>

## Deleting Conversations

Open the history drawer, long-press the conversation you want to remove, and tap **Delete**. The conversation and all its messages are removed permanently from local storage. There is no trash or undo.

<Warning>
  Deleted conversations cannot be recovered unless you have a backup. Export important conversations before deleting them.
</Warning>

## Stats Page (Token Usage)

Rikka tracks how many input and output tokens each conversation consumes and displays aggregated charts in the Stats page.

Open the history drawer and tap the **Chart** icon in the bottom action row to navigate to **Stats**. The page shows:

* A **weekly activity heatmap** with daily message counts.
* Total and per-day breakdowns of **input tokens**, **output tokens**, and **total tokens**.
* Per-model usage so you can see which models you use most.

<Note>
  Token counts are recorded at generation time. Messages sent before you updated to a version that supports stats tracking will not appear in the charts.
</Note>


# Multimodal Input: Attach Images and Documents to Chats
Source: https://docs.rikka-ai.com/chat/multimodal

Attach images, PDFs, DOCX files, and more to your Rikka messages. Learn how OCR and document extraction work for non-vision models.

Rikka supports more than plain text. You can attach images, documents, and other files directly to any message, and the app handles the conversion steps needed to deliver that content to the underlying AI model — whether the model natively understands images or not.

## Attaching Files

Tap the **+** (Add) button on the left side of the chat input bar to open the attachment picker. From there you can choose how to add content:

<CardGroup>
  <Card title="Camera" icon="camera">
    Take a photo on the spot. The image is saved to app storage and attached immediately.
  </Card>

  <Card title="Gallery / Files" icon="image">
    Pick one or more images or documents from your device. Supported document types include PDF, DOCX, PPTX, and EPUB.
  </Card>

  <Card title="Paste from clipboard" icon="clipboard">
    Copy an image from another app, tap the input field, and paste. Rikka detects the image and attaches it automatically.
  </Card>

  <Card title="Share from another app" icon="share">
    Use Android's share sheet to send a file or image to Rikka. The shared content pre-populates the input bar ready to send.
  </Card>
</CardGroup>

Attached files appear as chips above the text input. Tap the **×** on any chip to remove that attachment before sending.

## Images

When you attach an image and the selected model supports vision input, Rikka encodes the image as base64 and passes it directly to the model. The model sees the image as part of the conversation.

Attachment chips for images display a small thumbnail so you can confirm the right file is attached before sending.

<Note>
  Not all models support image input. If you select a model that does not accept image modalities, Rikka automatically falls back to OCR — see the **OCR** section below.
</Note>

## Documents: PDF, DOCX, PPTX, and EPUB

Rikka supports the following document types natively:

| Format     | Extension | MIME type                                                                   |
| ---------- | --------- | --------------------------------------------------------------------------- |
| PDF        | `.pdf`    | `application/pdf`                                                           |
| Word       | `.docx`   | `application/vnd.openxmlformats-officedocument.wordprocessingml.document`   |
| PowerPoint | `.pptx`   | `application/vnd.openxmlformats-officedocument.presentationml.presentation` |
| E-book     | `.epub`   | `application/epub+zip`                                                      |

When you attach a supported document, Rikka extracts its text content before the message is sent. The extracted text is injected as a text block at the beginning of your message, formatted like this:

```text theme={null}
## user sent a file: report.pdf
[content]
[extracted text goes here]
[/content]
```

The model then reads the document text as part of your prompt, letting you ask questions about the content, summarise it, or request translations — even if the model has no native file-upload capability.

<Warning>
  Very large documents may exceed a model's context window. If you receive an error about context length, try sending a shorter excerpt or splitting the document into smaller sections before attaching.
</Warning>

## OCR — Extracting Text from Images

If the active model does **not** support image input (i.e., it lacks vision modality), Rikka automatically runs OCR on any attached images using a separate vision-capable model you designate as the OCR model.

<Steps>
  <Step title="Configure an OCR model">
    Go to **Settings → Models** and set an **OCR Model**. Choose any vision-capable model from your configured providers — a fast, low-cost vision model works well here.
  </Step>

  <Step title="Attach an image">
    Attach an image as usual. When you send the message, Rikka checks whether the active chat model supports image input.
  </Step>

  <Step title="Automatic OCR">
    If the chat model does not support vision, Rikka sends the image to your configured OCR model with the extraction prompt. The transcribed text is then injected into your message in place of the raw image, so the main model receives a text description instead.
  </Step>

  <Step title="Results are cached">
    OCR results are cached for up to three days. If you send the same image again in a new message, Rikka reuses the cached text rather than calling the OCR model again.
  </Step>
</Steps>

<Tip>
  You can customise the OCR prompt in **Settings → Models → OCR Prompt** to control how the OCR model describes or transcribes images — for example, asking it to preserve table structure or transcribe handwriting carefully.
</Tip>

## File Size and Model Support

Keep these practical limits in mind when attaching files:

* **Image size** — Large images are passed as base64, which increases the token count significantly. Resize very large images before attaching them to avoid hitting context limits.
* **Document length** — The full extracted text of a document is injected into the prompt. PDFs with hundreds of pages can easily overflow a standard 8k-token context window. Use a model with a long context window (e.g. 128k tokens) for lengthy documents.
* **Model capability** — Not every provider or model tier exposes vision or document APIs. Consult your provider's documentation to confirm which input modalities a specific model supports.

<Note>
  Always check your provider's documentation to confirm which input types a model supports. Rikka detects image modality automatically, but document handling is always done via text extraction regardless of model capabilities.
</Note>


# Web Search: Ground AI Answers in Live Search Results
Source: https://docs.rikka-ai.com/chat/search

Enable Rikka's built-in web search to inject real-time results into any conversation, configure your preferred search service, and use the Search page.

Rikka includes a built-in web search capability that lets any AI model access live information from the web. When you enable web search before sending a message, Rikka automatically calls your configured search service, retrieves relevant results, and injects them into the conversation context before the model generates its reply.

## Enabling Web Search for a Message

The web search toggle lives in the **input toolbar** — the row of icons just above the text field.

<Steps>
  <Step title="Tap the search toggle">
    Tap the globe or search icon in the toolbar to enable web search. The icon highlights to indicate it is active.
  </Step>

  <Step title="Type your message">
    Write your question or prompt as normal. You do not need to phrase it differently — Rikka extracts the search query automatically.
  </Step>

  <Step title="Send the message">
    Tap send. Rikka calls the search service, retrieves results, and injects them as context before asking the model to respond. You will see a brief processing indicator while the search is in progress.
  </Step>

  <Step title="Review the cited sources">
    The assistant's reply includes references to the search results. Tap any linked URL to open it in your browser.
  </Step>
</Steps>

<Note>
  Web search is powered by a **tool call** injected into the conversation. The model decides when to invoke the `search_web` tool based on your prompt. If the model determines that search is unnecessary for a given question, it may skip the web call and answer from its training data.
</Note>

## Supported Search Services

Rikka supports a wide range of search providers. Configure one or more and select which one to use as the active service.

<Tabs>
  <Tab title="General purpose">
    | Service         | Notes                                                                                                                |
    | --------------- | -------------------------------------------------------------------------------------------------------------------- |
    | **Bing**        | Uses the Microsoft Bing Search API. No additional configuration required beyond an API key.                          |
    | **Brave**       | Privacy-focused search via the Brave Search API.                                                                     |
    | **RikkaHub**    | Rikka's own search API. Requires a RikkaHub API key and supports configurable search depth and AI-generated answers. |
    | **SearXNG**     | Self-hosted meta-search engine. Provide your instance URL, optional credentials, and preferred search engines.       |
    | **Bocha (博查)**  | Chinese-language search service with optional AI-generated summaries.                                                |
    | **Metaso (秘塔)** | Chinese AI-powered search service.                                                                                   |
  </Tab>

  <Tab title="AI-powered">
    | Service        | Notes                                                                                                                     |
    | -------------- | ------------------------------------------------------------------------------------------------------------------------- |
    | **Tavily**     | AI search API optimised for LLM use. Supports `general`, `news`, and `finance` topic modes, plus standard/advanced depth. |
    | **Exa**        | Semantic search API built for AI applications.                                                                            |
    | **Perplexity** | Uses Perplexity's search-augmented models. Optional max-tokens settings for replies and per-page content.                 |
    | **LinkUp**     | Configurable search depth (standard / deep).                                                                              |
    | **Grok**       | xAI's Grok model with live web search. Supports custom API URL, model choice, and a configurable system prompt.           |
    | **Tinyfish**   | Lightweight AI search service.                                                                                            |
  </Tab>

  <Tab title="Scraping & crawling">
    | Service       | Notes                                                                                                        |
    | ------------- | ------------------------------------------------------------------------------------------------------------ |
    | **Firecrawl** | Web crawling API that returns structured Markdown from any URL.                                              |
    | **Jina**      | Reader API (`r.jina.ai`) for scraping and search API (`s.jina.ai`) for querying. Both URLs are configurable. |
    | **Ollama**    | Run a local search-capable Ollama model as a search backend.                                                 |
  </Tab>

  <Tab title="Specialised">
    | Service        | Notes                                                                                                                           |
    | -------------- | ------------------------------------------------------------------------------------------------------------------------------- |
    | **Zhipu (智谱)** | Zhipu AI's search tool.                                                                                                         |
    | **Custom JS**  | Write your own search (and optionally scrape) logic in JavaScript. Rikka executes the script with a sandboxed `fetch()` helper. |
  </Tab>
</Tabs>

## Configuring a Search Service

<Steps>
  <Step title="Open Settings">
    Tap the **Settings** gear icon in the history drawer (bottom-right of the drawer action row).
  </Step>

  <Step title="Navigate to Search">
    Select **Search** from the settings list.
  </Step>

  <Step title="Add a service">
    Tap **Add** and choose a service from the list. Each service shows a description and a link to obtain an API key where required.
  </Step>

  <Step title="Enter credentials">
    Fill in the API key and any service-specific options (depth, language, model, custom URL, etc.).
  </Step>

  <Step title="Set as active">
    If you have multiple services configured, tap the one you want to use to select it as the active search service. The active service is shown in the search toggle tooltip in the chat input toolbar.
  </Step>
</Steps>

### Common Configuration Options

Different services expose different settings, but you will commonly see:

| Option                        | Description                                                                                                                         |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **API Key**                   | Your authentication key from the provider. Some services (e.g., Bing, SearXNG) may work without one or use a different auth method. |
| **Result count**              | How many search results to fetch and inject into context. More results give the model more information but consume more tokens.     |
| **Depth**                     | For services like Tavily and LinkUp, controls whether to perform a shallow or deep crawl of results.                                |
| **Language**                  | Restricts results to a specific language. Useful for SearXNG and some other services.                                               |
| **Include / exclude domains** | Available on select services to whitelist or blacklist specific websites.                                                           |
| **Safe search**               | Enables content filtering where supported.                                                                                          |

## How Search Results Are Injected

When you send a message with web search enabled, Rikka follows this flow:

1. The `search_web` tool is registered with the model alongside your message.
2. If the model decides to search, it emits a tool call with a `query` parameter.
3. Rikka calls the active search service with that query and the configured result count.
4. The results — including titles, URLs, and text snippets — are returned to the model as tool output.
5. Some services also support a `scrape_web` tool call that lets the model fetch the full content of individual pages.
6. The model integrates the results into its final response.

<Note>
  The search step happens silently in the background. A processing status message appears briefly in the chat list while Rikka is fetching results. The tool call and its output are visible in the chain-of-thought section if your model exposes reasoning steps.
</Note>

## The Dedicated Search Page

In addition to per-message web search, Rikka has a full-screen **Search** page for research-oriented sessions.

Open the history drawer and tap the **Search** icon (magnifying glass) in the drawer actions row. The Search page provides:

* A persistent search bar that lets you type a query and retrieve web results directly.
* Result cards showing the title, a text snippet, and the source URL.
* Tap any result card to open that URL or use it as context in a new chat.

<Tip>
  Use the Search page when you want to browse and compare multiple results before handing them off to the AI. It gives you more control than the automatic in-conversation search mode.
</Tip>

## Custom JS Search Service

If none of the built-in services fit your needs, use the **Custom JS** option to write your own search logic.

```javascript theme={null}
// Implement search(query, resultSize) function
// Use fetch(url, options?) for HTTP requests
// fetch() returns { status, ok, text(), json() }
// Return { items: [{ title, url, text }], answer?: string }

function search(query, resultSize) {
  const encoded = encodeURIComponent(query);
  const res = fetch("https://example.com/search?q=" + encoded + "&limit=" + resultSize);
  const data = res.json();
  return {
    items: data.results.map(function(r) {
      return { title: r.title, url: r.url, text: r.snippet };
    })
  };
}
```

You can also provide an optional `scrape(urls)` function to implement custom page extraction. Rikka's sandboxed environment provides a synchronous `fetch()` helper — no `async`/`await` is needed.

<Warning>
  Custom JS scripts run inside a restricted sandbox. Network access via `fetch()` is available, but the script cannot access device storage, Android APIs, or any Rikka internals.
</Warning>


# Install Rikka on Android: Download from Play or Web
Source: https://docs.rikka-ai.com/download

Download Rikka from Google Play or the official website, install it on your Android device, and complete the first-launch setup in minutes.

Rikka is a native Android application distributed through two official channels: the Rikka website and the Google Play Store. Both channels deliver the same app — choose whichever is most convenient for you. This page walks you through downloading, installing, and completing your first launch.

## System Requirements

Before you install, confirm your device meets the minimum requirements.

<Card title="Android Device Required" icon="robot" href="https://play.google.com/store/apps/details?id=me.rerere.rikkahub">
  Rikka runs on Android smartphones and tablets. Check the Google Play listing for the exact minimum Android version supported on your device.
</Card>

<Note>
  Rikka does not have an iOS version at this time. Make sure you are installing on an Android device.
</Note>

## Download Options

<Tabs>
  <Tab title="Google Play Store">
    The Google Play Store is the easiest way to install Rikka. Play handles automatic updates, so you always have the latest version without lifting a finger.

    1. Open the **Google Play Store** on your Android device.
    2. Search for **Rikka** or tap the link below to go directly to the listing.
    3. Tap **Install** and wait for the download to complete.

    <Card title="Rikka on Google Play" icon="rocket" href="https://play.google.com/store/apps/details?id=me.rerere.rikkahub">
      Open the official Rikka listing in the Google Play Store.
    </Card>
  </Tab>

  <Tab title="Official Website">
    You can also download the APK directly from the Rikka website. This is useful if the Play Store is unavailable in your region or if you prefer to sideload apps.

    1. Visit **[rikka-ai.com/download](https://rikka-ai.com/download)** in your browser.
    2. Tap the download button to save the APK file to your device.
    3. Open your file manager, locate the downloaded APK, and tap it to begin installation.
    4. If prompted, grant permission to **Install unknown apps** for your browser or file manager.
    5. Follow the on-screen prompts to complete the installation.

    <Warning>
      Only download Rikka from **rikka-ai.com** or the official Google Play listing. APKs from third-party sources may be outdated or tampered with.
    </Warning>
  </Tab>
</Tabs>

## First Launch Experience

Once Rikka is installed, open it from your home screen or app drawer. The first time you launch the app, Rikka walks you through the essential setup:

<Steps>
  <Step title="Welcome Screen">
    Rikka greets you with a brief welcome screen. Tap **Get Started** to move to the setup flow.
  </Step>

  <Step title="Add a Provider">
    Rikka prompts you to add at least one AI provider. Select your preferred provider — OpenAI, Google Gemini, Anthropic Claude, or a custom OpenAI-compatible endpoint — and enter your API key. You can add more providers later from **Settings → Providers**.
  </Step>

  <Step title="Choose a Default Model">
    Pick a default model for new conversations. You can always change the model on a per-conversation basis.
  </Step>

  <Step title="Start Chatting">
    Tap **Start Chatting** to open the main conversation view. Rikka is ready to use.
  </Step>
</Steps>

## Import Provider Settings via QR Code

If you have already configured Rikka on another device, you can skip manual API key entry by importing your provider settings with a QR code.

<Accordion title="How to import via QR code">
  On your existing device:

  1. Open **Settings → Providers**.
  2. Tap the **Export** or **Share** option and choose **QR Code**.
  3. A QR code containing your provider configuration is displayed on screen.

  On your new device:

  1. Complete installation and open Rikka.
  2. On the provider setup screen, tap **Import via QR Code**.
  3. Point your camera at the QR code on your existing device.
  4. Rikka imports your provider settings automatically.

  <Note>
    The QR code includes your API keys. Keep it private and do not share it publicly or screenshot it to an unsecured location.
  </Note>
</Accordion>

## Next Steps

<CardGroup>
  <Card title="Quickstart Guide" icon="rocket" href="/quickstart">
    Add a provider and send your first message in under five minutes.
  </Card>

  <Card title="Providers Overview" icon="plug" href="/providers/overview">
    Learn how to configure OpenAI, Gemini, Claude, and custom endpoints.
  </Card>
</CardGroup>


# Generate Images from Text Prompts in Rikka for Android
Source: https://docs.rikka-ai.com/extensions/image-generation

Open Rikka's image generation workspace to create images from text prompts using any image-capable model from your configured providers.

Rikka includes a dedicated image generation workspace that lets you turn text prompts into images — or supply a reference image and ask the model to edit it. Generated images are stored in an in-app gallery and can be saved to your device's photo library at any time.

<Note>
  Image generation requires a provider that supports image synthesis. Supported options include **DALL-E 3** (OpenAI), **Imagen 3** (Google), and any other provider you have configured in Rikka that exposes an image generation model. Make sure you have added and authenticated at least one such provider in **Settings → Providers** before continuing.
</Note>

## Selecting an Image Generation Model

Before you generate your first image, tell Rikka which model to use.

<Steps>
  <Step title="Open Model Settings">
    Go to **Settings → Models** and look for the **Image Generation Model** selector.
  </Step>

  <Step title="Pick a model">
    The selector lists every image-capable model across all your configured providers. Choose the one you want — for example, `dall-e-3` from your OpenAI provider, or `imagen-3.0-generate-002` from Google.
  </Step>

  <Step title="Save">
    Your choice is saved automatically. You can also change the model directly from the image generation screen at any time using the model selector in the input bar.
  </Step>
</Steps>

## Opening the Image Generation Screen

Tap the **Image Generation** entry in the app drawer (the grid icon on the home screen) to open the dedicated workspace. The screen has two tabs at the bottom:

<CardGroup>
  <Card title="Generate" icon="wand-magic-sparkles">
    Write a prompt, adjust settings, and create new images. Your most recently generated images appear at the top of this tab.
  </Card>

  <Card title="Gallery" icon="images">
    Browse every image you have generated across all sessions, with the prompt and model name displayed on each card.
  </Card>
</CardGroup>

## Generating an Image from a Text Prompt

<Steps>
  <Step title="Write your prompt">
    Type a descriptive text prompt in the input field at the bottom of the **Generate** tab. The more detail you include — subject, style, lighting, composition — the more closely the output matches your vision.
  </Step>

  <Step title="Adjust generation settings (optional)">
    Tap the **settings (wrench) icon** to open the settings sheet. You can configure:

    * **Model** — switch to a different image model without leaving the screen.
    * **Number of images** — generate between 1 and 4 images in a single request.
    * **Aspect ratio** — choose Square, Landscape, or Portrait.
  </Step>

  <Step title="Tap the send button">
    Tap the circular **arrow** button. Rikka sends your prompt to the selected model and shows a loading indicator while it waits for the result.
  </Step>

  <Step title="Review the output">
    Generated images appear above the input bar. Tap any image to open a full-screen preview.
  </Step>
</Steps>

<Tip>
  Start a **New Session** (the **+** icon in the top-right corner) to clear the current prompt and generated images and begin fresh. Each session keeps its own context separate from the gallery history.
</Tip>

## Editing an Existing Image

Some models — such as `dall-e-2` and certain Imagen variants — support image editing, where you provide a reference image and a prompt describing the changes you want.

<Steps>
  <Step title="Add a reference image">
    Tap the **image add (+) icon** in the input bar to pick one or more images from your device's photo library. Thumbnails appear above the text field; tap the **×** on any thumbnail to remove it.
  </Step>

  <Step title="Describe the edit">
    Write a prompt explaining what changes to apply, for example: *"Change the background to a sunset over the ocean"*.
  </Step>

  <Step title="Tap the send button">
    Rikka calls the provider's image-edit endpoint instead of the standard generation endpoint when reference images are present.
  </Step>
</Steps>

<Warning>
  Not all image models support editing. If your selected model only supports generation, Rikka will return an error when you try to submit with reference images attached. Switch to a model that supports editing (check your provider's documentation) or remove the reference images to do a standard generation instead.
</Warning>

## Working with the Gallery

Every image you generate is automatically saved to Rikka's in-app gallery. Open the **Gallery** tab to browse your history.

Each gallery card shows:

* A thumbnail of the image
* The model used
* A truncated version of the prompt

From the card's action row you can:

| Action                      | Effect                                                                         |
| --------------------------- | ------------------------------------------------------------------------------ |
| **Copy** (clipboard icon)   | Copies the full prompt text to your clipboard so you can reuse or refine it.   |
| **Save** (floppy disk icon) | Saves the image to your device's photo library / media store.                  |
| **Delete** (trash icon)     | Removes the image from the gallery and deletes the file from internal storage. |

Tap a thumbnail to open a full-screen preview with pinch-to-zoom support.

<Note>
  Images are stored in Rikka's private internal storage until you explicitly tap **Save** to export them to your device's media library. Uninstalling Rikka will permanently delete any images you have not saved externally.
</Note>

## Tips for Better Results

<Accordion title="Writing effective prompts">
  * Be specific about the subject: *"a red fox sitting in a snowy forest at dusk"* beats *"a fox"*.
  * Name an art style or medium: *"oil painting"*, *"photorealistic"*, *"watercolour sketch"*.
  * Describe the mood or atmosphere: *"dramatic lighting"*, *"soft pastel tones"*, *"cinematic composition"*.
  * If the model supports negative prompts, use the settings sheet to exclude unwanted elements.
</Accordion>

<Accordion title="Choosing the right aspect ratio">
  * **Square** — social media posts, avatars, product shots.
  * **Landscape (16:9)** — desktop wallpapers, scene illustrations, banners.
  * **Portrait (9:16)** — mobile wallpapers, posters, character art.
</Accordion>

<Accordion title="Managing API costs">
  Image generation APIs typically charge per image generated. Keep the **Number of images** setting at `1` while iterating on your prompt, and increase it only once you are happy with the style and composition.
</Accordion>


# Set Up MCP Servers in Rikka for External Tool Access
Source: https://docs.rikka-ai.com/extensions/mcp

Add and configure MCP servers in Rikka to give your AI assistants access to external tools, APIs, and real-world data sources on Android.

Model Context Protocol (MCP) is an open standard that lets AI models securely access external tools, APIs, and data sources. Rikka implements MCP as a first-class feature, so you can wire up any compliant MCP server and immediately expose its tools to your assistants — from web search and code execution to database queries and custom business logic.

## Adding an MCP Server

<Steps>
  <Step title="Open MCP Settings">
    Navigate to **Settings → MCP**. You'll see a list of all configured servers along with their current connection status (Idle, Connecting, Connected, Reconnecting, or Error).
  </Step>

  <Step title="Tap Add Server">
    Tap the **+** button in the top-right corner. Choose the transport type that matches your server.
  </Step>

  <Step title="Configure the server">
    Fill in the server details (see [Transport Types](#transport-types) and [Server Options](#server-options) below), then save.
  </Step>

  <Step title="Wait for connection">
    Rikka connects automatically and syncs the list of tools the server exposes. A green **Connected** indicator confirms the handshake succeeded. If the connection drops, Rikka retries automatically with exponential back-off before marking the server as errored.
  </Step>
</Steps>

<Note>
  MCP servers must be publicly reachable on the internet or on the same local network as your Android device. Servers behind a firewall or corporate VPN require a VPN connection on the device before Rikka can reach them.
</Note>

## Transport Types

Rikka supports two MCP transport mechanisms. Both require only a URL endpoint — choose whichever your server advertises.

<CardGroup>
  <Card title="SSE (Server-Sent Events)" icon="signal-stream">
    The original MCP transport. The client opens a persistent HTTP connection and the server pushes events over it. Provide the full SSE endpoint URL, for example `https://mcp.example.com/sse`.
  </Card>

  <Card title="Streamable HTTP" icon="arrows-up-down">
    The newer, recommended transport defined in the MCP spec. Uses standard HTTP requests with chunked streaming. Provide the base URL of the server, for example `https://mcp.example.com/mcp`.
  </Card>
</CardGroup>

## Server Options

Each server has a set of common options you configure when adding or editing it.

<ParamField type="string">
  A human-readable display name for this server. Appears in the MCP server list and in the assistant settings picker.
</ParamField>

<ParamField type="boolean">
  Toggle this server on or off without deleting it. When disabled, Rikka closes the connection and does not expose the server's tools to any assistant.
</ParamField>

<ParamField type="string">
  The full URL of the MCP endpoint. For SSE servers this is typically a path ending in `/sse`; for Streamable HTTP servers it is the base MCP path.
</ParamField>

<ParamField type="list of key-value pairs">
  Custom HTTP headers sent with every request to this server. Use this to pass authentication tokens, API keys, or any other request metadata your server requires. Add each header as a name-value pair, for example `Authorization: Bearer <token>`.
</ParamField>

## Per-Tool Options

After Rikka connects and syncs, it lists every tool the server exposes. You can control each tool individually.

<ParamField type="boolean">
  Enable or disable a specific tool from this server. Disabled tools are hidden from the assistant's tool list and are never called, even if the server is connected.
</ParamField>

<ParamField type="boolean">
  When turned on, Rikka shows a confirmation dialog before executing this tool. Use this for any tool that performs irreversible actions — file writes, emails, purchases — so you stay in control of what the AI actually does.
</ParamField>

<Tip>
  Enable **Needs Approval** on any tool that modifies data or triggers external side-effects. You can always approve quickly, and it prevents the model from acting autonomously in ways you didn't intend.
</Tip>

## Attaching MCP Servers to an Assistant

Adding a server to Rikka's global list does not automatically expose it to your assistants. You must opt each assistant in explicitly.

<Steps>
  <Step title="Open assistant settings">
    Long-press an assistant on the home screen, or tap the assistant name and then the **Edit** (pencil) icon to open its settings.
  </Step>

  <Step title="Find the MCP Servers section">
    Scroll down to **MCP Servers**. You'll see all servers that are currently enabled in your global MCP list.
  </Step>

  <Step title="Toggle the servers you want">
    Enable the servers whose tools this assistant should have access to. Only tools from servers ticked here will appear in the assistant's tool calls.
  </Step>
</Steps>

## Importing Server Configs via JSON

If a service publishes a ready-made MCP config file, you can import it directly instead of typing in all the details manually.

<Steps>
  <Step title="Copy or download the JSON config">
    The config should be a JSON object describing one or more MCP servers in Rikka's config schema.
  </Step>

  <Step title="Open MCP Settings and tap Import">
    In **Settings → MCP**, tap the import icon and paste or load the JSON. Rikka validates and merges the servers into your existing list.
  </Step>
</Steps>

A minimal single-server SSE config looks like this:

```json theme={null}
{
  "type": "sse",
  "commonOptions": {
    "name": "My MCP Server",
    "enable": true,
    "headers": [
      ["Authorization", "Bearer my-secret-token"]
    ]
  },
  "url": "https://mcp.example.com/sse"
}
```

## Connection Status Reference

| Status           | Meaning                                                                     |
| ---------------- | --------------------------------------------------------------------------- |
| **Idle**         | Server is disabled or has not yet been started.                             |
| **Connecting**   | Rikka is establishing the initial connection.                               |
| **Connected**    | Handshake complete; tools are available.                                    |
| **Reconnecting** | Connection was lost; Rikka is retrying with exponential back-off.           |
| **Error**        | All retry attempts failed. Check the URL, headers, and server availability. |


# Skills: Reusable Capability Bundles for Assistants
Source: https://docs.rikka-ai.com/extensions/skills

Bundle prompt instructions into reusable skills you can install once and enable on any Rikka assistant, then share or import via GitHub.

Skills are self-contained bundles of instructions and configuration that extend what an assistant can do. Think of a skill as a plug-in you install once and then enable on any assistant you like. A skill might teach an assistant how to write in a specific style, follow a domain-specific reasoning process, or call a particular set of tools — all defined in a single portable package that you can share, import from GitHub, or author yourself.

## Browsing and Managing Skills

Open **Settings → Extensions → Skills** to see all the skills installed on your device. Each card shows the skill's name, a short description, and — if the author included one — a compatibility note indicating which models or providers it works best with.

<CardGroup>
  <Card title="Import from GitHub" icon="github">
    Tap **+** and choose **Import from GitHub**. Paste a repository URL such as `https://github.com/owner/repo`. Rikka downloads the skill files directly from the repository's default branch.
  </Card>

  <Card title="Import from File" icon="file-import">
    Tap **+** and choose **Import from File**. Select a `.zip` archive or a plain text file from your device. Rikka extracts the skill and adds it to the list.
  </Card>

  <Card title="Create Manually" icon="pen">
    Tap **+** and choose **Add Manually**. Paste in the skill content directly — Rikka reads the YAML frontmatter to extract the skill's name and description automatically.
  </Card>

  <Card title="Delete a Skill" icon="trash">
    Tap the **⋮** menu on any skill card and choose **Delete**. Rikka removes the skill from every assistant that had it enabled.
  </Card>
</CardGroup>

## Skill File Format

Every skill is built around a `SKILL.md` file that Rikka reads when loading the skill. The file starts with a YAML frontmatter block followed by the instruction body.

```markdown theme={null}
---
name: code-reviewer
description: "Performs thorough code review with style and security feedback"
compatibility: "Works best with GPT-4o, Claude 3.5+"
allowed-tools: read_file, search
---

You are an expert code reviewer. When given a code snippet or file, you:
1. Check for logic errors and edge cases
2. Identify security vulnerabilities
3. Suggest style improvements aligned with the project's conventions
...
```

<Accordion title="Frontmatter fields">
  | Field           | Required | Description                                                       |
  | --------------- | -------- | ----------------------------------------------------------------- |
  | `name`          | ✅        | Unique identifier for the skill. Must be non-empty and URL-safe.  |
  | `description`   | ✅        | One-line summary shown on the skill card.                         |
  | `compatibility` | ✗        | Free-text hint about which models or providers work best.         |
  | `allowed-tools` | ✗        | Space-separated list of tool names this skill is designed to use. |
</Accordion>

## Viewing and Editing a Skill's Files

Tap any skill card to open the **Skill Detail** page. You'll see a collapsible file tree showing every file inside the skill directory.

* Tap the **pencil** icon next to a file to edit its contents in a built-in text editor.
* Tap the **trash** icon to delete a file (you cannot delete `SKILL.md`).
* Tap the **+** FAB to add a new file, optionally nested in a subfolder using a path like `examples/basic.md`.

<Warning>
  Editing `SKILL.md` directly changes the skill's instructions. If you imported the skill from GitHub, your edits will not sync back to the upstream repository — keep a backup if you plan to make significant changes.
</Warning>

## Enabling a Skill on an Assistant

Installing a skill globally does not activate it for any assistant automatically. You choose which assistants benefit from each skill.

<Steps>
  <Step title="Open assistant settings">
    Long-press an assistant on the home screen, or tap the assistant name and then the **Edit** icon to open its settings page.
  </Step>

  <Step title="Find the Enabled Skills section">
    Scroll down to **Enabled Skills**. All currently installed skills appear here as toggles.
  </Step>

  <Step title="Toggle on the skills you want">
    Enable any skills that should be active for this assistant. The assistant's system prompt will be augmented with the skill's instruction body at inference time.
  </Step>

  <Step title="Test the assistant">
    Start a new chat with the assistant and verify it behaves according to the skill's instructions.
  </Step>
</Steps>

<Tip>
  You can enable multiple skills on a single assistant. Keep in mind that each active skill's instructions are injected into the system prompt, so very large or numerous skills may consume a meaningful portion of the model's context window.
</Tip>

## Sharing Skills

Because each skill is just a directory of plain text files, sharing is straightforward:

* **ZIP and send**: Compress the skill folder and share the `.zip` file via any messaging app or file transfer method. The recipient imports it with **Import from File**.
* **GitHub repository**: Publish the skill directory as a public GitHub repo. Anyone with the URL can import it directly into Rikka.


# Set Up TTS and ASR Speech Providers in Rikka for Android
Source: https://docs.rikka-ai.com/extensions/speech

Configure TTS and ASR providers in Rikka to have AI responses read aloud and dictate your messages with a microphone instead of typing.

Rikka ships with built-in support for both Text-to-Speech (TTS) — hearing AI responses read aloud — and Automatic Speech Recognition (ASR) — dictating your messages with a microphone instead of typing. You configure each capability independently, choosing from several cloud and on-device providers. Once set up, TTS and ASR work directly from the chat screen without leaving the conversation.

Navigate to **Settings → Speech** to access both tabs.

<Tabs>
  <Tab title="Text-to-Speech (TTS)">
    ## Setting Up TTS

    Open the **TTS** tab inside **Settings → Speech**. Tap **Add Provider** and select the provider you want to use. Fill in the required fields, then tap Save. You can add multiple providers and switch between them at any time.

    To hear a message read aloud, tap the **speaker icon** that appears on any assistant message bubble.

    ***

    ### Available TTS Providers

    <Accordion title="OpenAI TTS">
      Uses OpenAI's neural TTS API. Produces natural-sounding speech with a choice of six preset voices.

      <ParamField type="string">
        Your OpenAI API key. Find this in your [OpenAI dashboard](https://platform.openai.com/api-keys).
      </ParamField>

      <ParamField type="string">
        Base URL for the OpenAI-compatible API. Change this if you are routing through a proxy or using a third-party OpenAI-compatible endpoint.
      </ParamField>

      <ParamField type="string">
        The TTS model to use. `gpt-4o-mini-tts` is fast and cost-effective; swap in `tts-1-hd` for higher fidelity output.
      </ParamField>

      <ParamField type="string">
        Voice preset. OpenAI offers `alloy`, `echo`, `fable`, `onyx`, `nova`, and `shimmer`.
      </ParamField>
    </Accordion>

    <Accordion title="Gemini TTS">
      Uses Google's Gemini multimodal TTS. Supports a wide range of voices including the expressive Gemini 2.5 family.

      <ParamField type="string">
        Your Google AI Studio API key.
      </ParamField>

      <ParamField type="string">
        Base URL for the Gemini API.
      </ParamField>

      <ParamField type="string">
        Gemini model to use for speech synthesis.
      </ParamField>

      <ParamField type="string">
        Voice name. Refer to the [Google AI voice list](https://ai.google.dev/gemini-api/docs/speech-generation) for all available options.
      </ParamField>
    </Accordion>

    <Accordion title="MiniMax TTS">
      High-quality Chinese and multilingual TTS from MiniMax.

      <ParamField type="string">
        Your MiniMax API key.
      </ParamField>

      <ParamField type="string">
        MiniMax API base URL.
      </ParamField>

      <ParamField type="string">
        TTS model identifier.
      </ParamField>

      <ParamField type="string">
        Voice ID. Browse available voices in the MiniMax console.
      </ParamField>

      <ParamField type="string">
        Emotional tone of the synthesized voice, e.g. `calm`, `happy`, `sad`.
      </ParamField>

      <ParamField type="float">
        Playback speed multiplier. Values below `1.0` slow speech down; values above `1.0` speed it up.
      </ParamField>
    </Accordion>

    <Accordion title="Qwen TTS">
      Alibaba DashScope's Qwen TTS, optimised for Chinese and multilingual speech.

      <ParamField type="string">
        Your DashScope API key.
      </ParamField>

      <ParamField type="string">
        DashScope API base URL.
      </ParamField>

      <ParamField type="string">
        TTS model. `qwen3-tts-flash` is the low-latency variant.
      </ParamField>

      <ParamField type="string">
        Voice name. Check the DashScope documentation for the full list.
      </ParamField>

      <ParamField type="string">
        Language hint. `Auto` lets the model detect the language automatically.
      </ParamField>
    </Accordion>

    <Accordion title="Groq TTS">
      Fast TTS via Groq's inference infrastructure, powered by Orpheus models.

      <ParamField type="string">
        Your Groq API key.
      </ParamField>

      <ParamField type="string">
        Groq API base URL.
      </ParamField>

      <ParamField type="string">
        Orpheus TTS model to use.
      </ParamField>

      <ParamField type="string">
        Voice preset name.
      </ParamField>
    </Accordion>

    <Accordion title="xAI TTS">
      Text-to-speech via xAI's Grok API.

      <ParamField type="string">
        Your xAI API key.
      </ParamField>

      <ParamField type="string">
        xAI API base URL.
      </ParamField>

      <ParamField type="string">
        Voice identifier.
      </ParamField>

      <ParamField type="string">
        BCP-47 language tag or `auto` for automatic detection.
      </ParamField>
    </Accordion>

    <Accordion title="MiMo TTS">
      TTS provided by Xiaomi's MiMo service.

      <ParamField type="string">
        Your MiMo API key.
      </ParamField>

      <ParamField type="string">
        MiMo API base URL.
      </ParamField>

      <ParamField type="string">
        TTS model identifier.
      </ParamField>

      <ParamField type="string">
        Voice preset.
      </ParamField>
    </Accordion>

    <Accordion title="System TTS">
      Uses Android's built-in text-to-speech engine. No API key required — works fully on-device using whatever voice packs you have installed in Android settings.

      <ParamField type="float">
        Speed of synthesized speech. `1.0` is normal speed; increase for faster delivery, decrease for slower.
      </ParamField>

      <ParamField type="float">
        Pitch of the synthesized voice. `1.0` is the default pitch for the selected Android voice.
      </ParamField>

      <Note>
        The quality and language support of System TTS depend on the voice packs installed on your device. You can install additional voices in **Android Settings → Accessibility → Text-to-speech output**.
      </Note>
    </Accordion>
  </Tab>

  <Tab title="Automatic Speech Recognition (ASR)">
    ## Setting Up ASR

    Open the **ASR** tab inside **Settings → Speech**. Tap **Add Provider** and select your preferred provider. After saving, a **microphone icon** appears in the chat input bar. Tap and hold it to record your voice; Rikka transcribes the audio and inserts the text into the message field automatically.

    ***

    ### Available ASR Providers

    <Accordion title="OpenAI Realtime ASR">
      Streams audio to OpenAI's Realtime transcription API over a WebSocket connection, giving you low-latency, real-time transcription with voice activity detection (VAD).

      <ParamField type="string">
        Your OpenAI API key.
      </ParamField>

      <ParamField type="string">
        WebSocket endpoint for the Realtime transcription API.
      </ParamField>

      <ParamField type="string">
        Transcription model. `gpt-4o-transcribe` offers the best accuracy.
      </ParamField>

      <ParamField type="string">
        BCP-47 language code (e.g. `en`, `zh`, `ja`). Leave empty to enable automatic language detection.
      </ParamField>

      <ParamField type="float">
        Voice activity detection sensitivity, from `0.0` (very sensitive) to `1.0` (least sensitive). Increase this in noisy environments to reduce false triggers.
      </ParamField>

      <ParamField type="integer">
        How many milliseconds of silence Rikka waits before treating the utterance as complete and finalising the transcript.
      </ParamField>
    </Accordion>

    <Accordion title="DashScope ASR (Qwen)">
      Real-time streaming ASR from Alibaba Cloud's DashScope, backed by Qwen's speech models and optimised for Chinese and multilingual audio.

      <ParamField type="string">
        Your DashScope API key.
      </ParamField>

      <ParamField type="string">
        DashScope WebSocket inference endpoint.
      </ParamField>

      <ParamField type="string">
        ASR model identifier. The `flash-realtime` variant prioritises low latency.
      </ParamField>

      <ParamField type="string">
        Language code hint. Leave empty for automatic detection.
      </ParamField>

      <ParamField type="float">
        VAD sensitivity. Lower values make the detector more aggressive about cutting off silence.
      </ParamField>
    </Accordion>

    <Accordion title="Volcengine ASR">
      Streaming ASR from ByteDance's Volcengine platform (via the SeedASR model), well-suited for Mandarin Chinese and multi-accent speech.

      <ParamField type="string">
        Your Volcengine API key.
      </ParamField>

      <ParamField type="string">
        Volcengine ASR WebSocket endpoint.
      </ParamField>

      <ParamField type="string">
        Volcengine resource identifier for the ASR service.
      </ParamField>

      <ParamField type="string">
        Language code. Leave empty to rely on the model's built-in language detection.
      </ParamField>
    </Accordion>
  </Tab>
</Tabs>

## Using Speech in the Chat Screen

Once you have at least one provider configured in each category, the controls appear directly in the chat interface:

<CardGroup>
  <Card title="Microphone (ASR)" icon="microphone">
    Tap the **microphone icon** in the chat input bar to start recording. Speak your message naturally — Rikka streams the audio to your ASR provider and populates the text field as words are transcribed. Release or tap again to stop.
  </Card>

  <Card title="Speaker (TTS)" icon="volume-high">
    Tap the **speaker icon** on any assistant message to have it read aloud by your configured TTS provider. Tap again to stop playback mid-sentence.
  </Card>
</CardGroup>

<Tip>
  If you primarily use voice input, combine ASR with a low-latency TTS provider so the full conversation flows naturally without switching away from the keyboard.
</Tip>


# Workspace
Source: https://docs.rikka-ai.com/extensions/workspace

A lightweight Linux environment for AI to handle agent tasks like file editing and creating presentations.

Workspace provides a lightweight Linux environment for AI, enabling it to manipulate files and complete tasks such as editing files, creating presentations, and more.
An assistant can be bound to one workspace.

## Quick Start

<Steps>
  <Step title="Create a Workspace">
    1. Go to **Settings** → **Extension Management** → **Workspace** to open the workspace management page.
    2. Tap the plus button in the bottom-right corner to create a new workspace and enter a name.
    3. Tap the newly created workspace card to enter its management page, then tap **Install Rootfs** to install the system files.

    <Note>
      Workspace names must be in English.
    </Note>
  </Step>

  <Step title="Manage and Configure">
    On the workspace management page, you can:

    * Configure whether tools provided by the workspace require user approval before execution
    * Tap the **Files** tab to manage workspace files, including importing and exporting
    * Tap the icon in the top-right corner to open the terminal
  </Step>

  <Step title="Use in Chat">
    Go back to the chat page and tap the plus button in the chat bar. You will see a card for binding a workspace — tap it to bind to your target workspace.

    Once bound, the AI can operate within the workspace to complete various tasks when you give it instructions.
  </Step>
</Steps>

## Glossary

| Term          | Description                                                                                                                                                    |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Workspace** | An isolated Linux environment provided by Rikka for AI. Each workspace runs independently with its own filesystem and packages.                                |
| **Terminal**  | A built-in command-line interface within the workspace where you can run Linux commands to manage files, install software, or debug issues.                    |
| **Rootfs**    | Short for Root Filesystem — the base system files required for a workspace to run. Installing Rootfs is like installing an operating system for the workspace. |

## Installing Common Packages

Workspaces use the `apt` package manager by default. You can install packages manually via the terminal, or let the AI install what it needs during a task.

<Tabs>
  <Tab title="Essential Tools">
    | Package         | Purpose                                |
    | --------------- | -------------------------------------- |
    | `curl`          | Send HTTP requests and download files  |
    | `unzip` / `zip` | Extract and create ZIP archives        |
    | `git`           | Version control and repository cloning |
    | `jq`            | Parse and process JSON data            |

    ```bash theme={null}
    apt update && apt install -y curl unzip zip git jq
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    apt update && apt install -y python3 python3-pip
    ```
  </Tab>

  <Tab title="Node.js (nvm)">
    Install Node.js via nvm for easy version management:

    ```bash theme={null}
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
    ```

    After installation, reload the environment and install Node.js:

    ```bash theme={null}
    source ~/.bashrc && nvm install --lts
    ```
  </Tab>
</Tabs>

<Tip>
  In most cases you don't need to install packages manually — when you give the AI a task, it will automatically install any dependencies it needs.
</Tip>

## File Import & Export

You can manage workspace files in two ways:

<Tabs>
  <Tab title="In-App Management">
    Open the workspace management page and tap the **Files** menu button at the bottom to switch to the file management view. From here you can:

    * Import files into the workspace
    * Export files from the workspace
    * Share files directly to other apps
  </Tab>

  <Tab title="System File Manager">
    Open your system's file manager and look for a drive named **RikkaHub**. Inside, you'll find folders named after each workspace containing their files. You can copy, move, and delete files directly.
  </Tab>
</Tabs>

## Use Cases

Here are some example use cases for reference.

### Clone a Repository and Edit Files

With a workspace bound, you can ask the AI to clone a Git repository and edit its files. For example, send a message like:

> Clone [https://github.com/user/repo](https://github.com/user/repo) and translate the README.md into Chinese

The AI will perform the following steps in the workspace:

1. Install `git` (if not already installed)
2. Clone the target repository into the workspace
3. Read the contents of `README.md`
4. Translate the content into Chinese and write it back to the file

Once complete, you can export the modified files through file management, or push to the remote repository.

### Create a Presentation

1. Go to **Extension Management** → **Agent Skills** and install the [pptx skill](https://github.com/anthropics/skills/tree/main/skills/pptx).
2. In the chat page, tap the plus button, go to extension management, and enable the skill.
3. Send your request — for example, ask the AI to research a topic and create a presentation.
4. The AI will progressively gather information and use the Python / Node.js environment in the workspace to generate the PPT file.
5. Once complete, go to the workspace management page to export or share the generated PPT file.


# Welcome to Rikka — Your Android AI Chat Application
Source: https://docs.rikka-ai.com/introduction

Rikka is a native Android app that unifies OpenAI, Google Gemini, Anthropic Claude, and any OpenAI-compatible provider in one beautiful interface.

Rikka brings every major AI provider together in a single, polished Android app. Instead of juggling separate apps and browser tabs, you connect your own API keys once and chat with OpenAI, Google Gemini, Anthropic Claude, or any OpenAI-compatible endpoint — all from the same familiar interface. Rikka is built natively in Kotlin with Jetpack Compose, so it feels fast, responsive, and right at home on your Android device.

## Get Started

<CardGroup>
  <Card title="Download Rikka" icon="download" href="/download">
    Install Rikka from the website or Google Play and get set up in minutes.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Add your first provider, pick a model, and send your first message in under five minutes.
  </Card>

  <Card title="AI Providers" icon="plug" href="/providers/overview">
    Connect OpenAI, Google Gemini, Anthropic Claude, or any OpenAI-compatible API.
  </Card>

  <Card title="Assistants" icon="robot" href="/assistants/overview">
    Create custom assistants with tailored system prompts, models, and personas.
  </Card>

  <Card title="MCP Extensions" icon="puzzle" href="/extensions/mcp">
    Extend Rikka's capabilities with Model Context Protocol plugins and tools.
  </Card>

  <Card title="Web Access" icon="globe" href="/settings/web-access">
    Let Rikka search the web in real time to ground answers in current information.
  </Card>
</CardGroup>

## Why Rikka?

Rikka was designed around one idea: you should own your AI experience. You bring your own API keys, choose your own models, and keep your conversations private. There are no subscriptions, no middlemen, and no lock-in.

<CardGroup>
  <Card title="Multiple Providers, One App" icon="plug" href="/providers/overview">
    Switch between OpenAI, Gemini, Claude, and OpenAI-compatible APIs without leaving the app.
  </Card>

  <Card title="Custom Assistants" icon="wand-magic-sparkles" href="/assistants/overview">
    Build reusable assistants with custom system prompts, model selections, and personalities.
  </Card>

  <Card title="MCP Tool Support" icon="puzzle" href="/extensions/mcp">
    Connect external tools and data sources through the Model Context Protocol.
  </Card>

  <Card title="Live Web Search" icon="globe" href="/settings/web-access">
    Enable real-time web access so your AI answers stay accurate and up to date.
  </Card>
</CardGroup>


# Quickstart: Send Your First AI Message in 5 Minutes
Source: https://docs.rikka-ai.com/quickstart

Install Rikka on Android, connect your first AI provider with your API key, choose a model, and send your first message in under five minutes.

This guide gets you from zero to your first AI conversation as quickly as possible. You need an Android device, a copy of Rikka installed, and an API key from at least one AI provider. If you do not have an API key yet, sign up with your chosen provider first — links are included in the steps below.

<Steps>
  <Step title="Download and Install Rikka">
    Install Rikka on your Android device from either the Google Play Store or the official website.

    <CardGroup>
      <Card title="Official Website (Recommended)" icon="download" href="https://rikka-ai.com/download">
        Download the latest APK directly from rikka-ai.com — always up to date.
      </Card>

      <Card title="Google Play Store" icon="rocket" href="https://play.google.com/store/apps/details?id=me.rerere.rikkahub">
        Tap **Install** on the Play listing for automatic updates and easy installation.
      </Card>
    </CardGroup>

    Once installation is complete, open Rikka from your home screen or app drawer.
  </Step>

  <Step title="Open Settings and Add a Provider">
    Rikka needs at least one AI provider before you can chat. Navigate to the provider settings now.

    1. Tap the **Settings** icon (gear) at the bottom of the sidebar.
    2. Select **Provider Settings** from the settings menu.
    3. Many providers are pre-configured — if yours is listed, just tap it and enter your API key. If not, tap the button in the top-right corner to create a new provider.

    <Tabs>
      <Tab title="OpenAI">
        The most widely used API format. Enter the base URL and API key from your provider to complete the setup.

        OpenAI has two API versions. **Chat Completions** is the default in RikkaHub and is the most popular format supported by the vast majority of providers. The newer **Responses API** is what OpenAI itself now prioritizes — if you are using the official OpenAI API or a relay that mirrors GPT models, switching to the Responses API is recommended. Tap **Use Responses API** to enable it.
      </Tab>

      <Tab title="Google Gemini">
        Google's own API format, used exclusively for Google Gemini models.
      </Tab>

      <Tab title="Anthropic Claude">
        The second most widely adopted API format after OpenAI. Used by Claude and a number of other models as well.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Enter Your API Key">
    Paste your API key into the **API Key** field for the provider you selected.

    If you are using an unofficial relay that is not built into RikkaHub, you will also need to set the provider's **Base URL** when creating a new provider.

    <Warning>
      Treat your API key like a password. Do not share it, and do not paste it into untrusted apps. Rikka stores your key locally on your device and never sends it to Rikka's servers — it goes directly to your chosen provider.
    </Warning>

    After pasting your key, tap **Save** or **Confirm** to store the provider configuration.
  </Step>

  <Step title="Add Models">
    After configuring a provider, scroll to the **Models** section at the bottom of the provider screen and tap it.

    Most providers support fetching the model list automatically — tap the expand button to load the list, then select the models you want to use.

    To remove a model you no longer need, swipe it to delete.

    <Note>
      You can change the model at any time from within a conversation using the model picker in the chat toolbar.
    </Note>
  </Step>

  <Step title="Configure Default Models">
    Go back to the Settings page and select **Default Models & Prompts** to set the default model for each feature module.

    Beyond the chat model, other features (such as title generation and summarization) can each use a different model — a faster, cheaper model often works well for those tasks.
  </Step>

  <Step title="Start Your First Conversation">
    Everything is ready. Head back to the main screen and start a new conversation.

    1. Tap the model selector button at the bottom-left to choose the model you want to use.
    2. Type your first message in the text field and tap **Send**.

    Rikka streams the response back to you in real time. That's it — you're up and running!

    <Tip>
      Try a simple opener like *"Explain what you can help me with"* to get a feel for the model's capabilities before diving into more specific tasks.
    </Tip>

    <Warning>
      Avoid asking the model which model it is. Models do not have accurate self-awareness about their own identity — this is a fundamental property of how large language models work, not a bug in Rikka.

      Official apps can answer this correctly because they inject a system prompt that tells the model its identity. RikkaHub does not include such a prompt by default, though you can add one yourself through the system prompt settings.
    </Warning>
  </Step>
</Steps>

## What to Explore Next

<CardGroup>
  <Card title="Providers Overview" icon="plug" href="/providers/overview">
    Add more providers and learn how to configure advanced options like custom base URLs and headers.
  </Card>

  <Card title="Custom Assistants" icon="robot" href="/assistants/overview">
    Create reusable assistants with custom system prompts, model defaults, and personalities.
  </Card>

  <Card title="MCP Extensions" icon="puzzle" href="/extensions/mcp">
    Connect external tools and data sources to give your AI access to real-world actions.
  </Card>

  <Card title="Web Access" icon="globe" href="/settings/web-access">
    Enable live web search so your AI can answer questions about current events and recent information.
  </Card>
</CardGroup>


# Rikka Appearance: Themes, Dark Mode, and Display Settings
Source: https://docs.rikka-ai.com/settings/appearance

Control how Rikka looks: enable Material You dynamic color, switch dark or AMOLED mode, pick a preset theme, build a custom palette, and tune display.

Rikka gives you full control over how the app looks and feels. You can let Android automatically generate a color scheme from your wallpaper, choose from a curated set of built-in themes, or design a completely custom palette using an HSL color picker. Display options let you adjust font size, message density, code block behavior, and much more — all stored locally on your device.

## Color and Theme

### Dynamic Color

Dynamic Color automatically generates Rikka's entire color scheme from your current wallpaper using Android's Material You system. When you change your wallpaper, Rikka's accent colors update to match.

<Tip>
  Dynamic Color requires Android 12 or later. On older devices the toggle is hidden and Rikka falls back to the selected preset or custom theme.
</Tip>

To enable Dynamic Color:

<Steps>
  <Step title="Open Settings">
    Tap the **Settings** icon from the main screen.
  </Step>

  <Step title="Go to Preferences → Theme">
    Select **Preferences**, then tap **Theme**.
  </Step>

  <Step title="Toggle Dynamic Color on">
    Enable the **Dynamic Color** switch. Rikka's UI immediately adopts your wallpaper-derived palette.
  </Step>
</Steps>

When Dynamic Color is active, preset and custom theme selections are ignored. Disable Dynamic Color to use them.

***

### Dark Mode and AMOLED Dark Mode

Rikka follows your system dark/light mode preference by default. You can also enable **AMOLED Dark Mode** for a true-black background that saves battery on OLED screens.

To enable AMOLED Dark Mode:

<Steps>
  <Step title="Open Settings → Preferences → Theme">
    Navigate to **Settings → Preferences → Theme**.
  </Step>

  <Step title="Enable AMOLED Dark Mode">
    Toggle on **AMOLED Dark Mode**. The background switches to pure black in dark mode.
  </Step>
</Steps>

***

### Preset Themes

Rikka ships with five hand-crafted themes. Each theme has a dedicated light and dark color scheme that is fully accessible and meets Material You contrast guidelines.

<CardGroup>
  <Card title="Sakura" icon="circle">
    Soft pinks inspired by cherry blossoms. The default theme.
  </Card>

  <Card title="Ocean" icon="circle">
    Cool blues and teals drawn from deep water.
  </Card>

  <Card title="Spring" icon="circle">
    Fresh greens evoking new growth and clear skies.
  </Card>

  <Card title="Autumn" icon="circle">
    Warm ambers and earthy tones of the fall season.
  </Card>

  <Card title="Black" icon="circle">
    High-contrast dark-first palette optimized for AMOLED.
  </Card>
</CardGroup>

To apply a preset theme:

<Steps>
  <Step title="Disable Dynamic Color">
    Preset themes are only available when **Dynamic Color** is off.
  </Step>

  <Step title="Open Settings → Preferences → Theme → Theme Settings">
    Tap **Theme Settings** to open the theme picker.
  </Step>

  <Step title="Select a preset">
    Tap any preset theme tile. The app updates immediately — no restart required.
  </Step>
</Steps>

***

### Custom Themes

Create your own color palette by specifying primary, secondary, and tertiary colors using an HSL (Hue, Saturation, Lightness) color picker. You can also import and export themes as JSON to share them.

<Steps>
  <Step title="Open Theme Settings">
    Go to **Settings → Preferences → Theme → Theme Settings**.
  </Step>

  <Step title="Add a new custom theme">
    Tap the **Add** button. Enter a name for your theme.
  </Step>

  <Step title="Set your colors">
    Use the HSL sliders to choose your primary, secondary, and tertiary colors. You can also type an HSL value directly (for example, `hsl(267 36% 48%)`). A live preview of the palette updates as you adjust the sliders.
  </Step>

  <Step title="Save the theme">
    Tap **Save**. Your custom theme appears in the theme list alongside the presets; tap it to activate it.
  </Step>
</Steps>

<Tip>
  You can export a custom theme as JSON to share it, or import one from a friend. Use the copy icon next to any custom theme to copy its JSON to the clipboard. To import, tap **Import** and paste the JSON into the dialog that appears.
</Tip>

<Note>
  Editing or deleting a custom theme takes effect immediately. If you delete the currently active custom theme, Rikka reverts to the default Sakura preset.
</Note>

***

## Display Settings

Display settings let you control what information appears in the chat view and how content is rendered. Access them at **Settings → Preferences → Display**.

### Message Display

<Accordion title="User avatar and nickname">
  * **Show User Avatar** — display your avatar bubble next to your messages.
  * **User Nickname** — set the name shown in conversations.
</Accordion>

<Accordion title="Assistant bubble and opacity">
  * **Show Assistant Bubble** — wrap assistant messages in a colored bubble instead of plain text.
  * **Bubble Opacity** — drag the slider to control how transparent the bubble background is.
</Accordion>

<Accordion title="Model information">
  * **Show Model Icon** — display the provider icon next to each assistant message.
  * **Show Model Name** — show the model name beneath each assistant reply.
</Accordion>

<Accordion title="Timestamps and token usage">
  * **Show Date/Time in Message** — append a timestamp to every message.
  * **Show Token Usage** — display the prompt and completion token counts after each response.
</Accordion>

<Accordion title="Thinking content">
  * **Show Thinking Content** — reveal chain-of-thought reasoning blocks when a model produces them.
  * **Auto-Collapse Thinking** — automatically fold thinking blocks after the response finishes generating.
</Accordion>

### Font Settings

<ParamField type="select">
  Choose between **Default** (system sans-serif), **Serif**, **Monospace**, or **Custom**. Selecting **Custom** prompts you to import a font file from your device.
</ParamField>

<ParamField type="slider">
  Scale the chat font size. A live preview updates as you drag the slider.
</ParamField>

### Code Block Settings

<Accordion title="Code display options">
  * **Auto-Wrap** — wrap long lines inside code blocks instead of scrolling horizontally.
  * **Auto-Collapse** — collapse code blocks taller than the viewport by default.
  * **Show Line Numbers** — prepend a line number to each line of code.
</Accordion>

### Rendering

* **LaTeX Rendering** — enable or disable mathematical expression rendering using LaTeX syntax inside messages.
* **Blur Effect** — apply a subtle blur to certain UI surfaces for a frosted-glass look.


# Back Up and Restore Your Rikka Conversations and Settings
Source: https://docs.rikka-ai.com/settings/backup

Export conversations and settings to a local file, sync automatically to WebDAV or S3-compatible storage, and set reminders so you never lose your data.

Rikka stores all your conversations, settings, and provider configurations on-device. Use the Backup page to protect that data: export a portable ZIP file for manual safekeeping, push incremental backups to a WebDAV or S3 server, or schedule reminders that prompt you to back up regularly. Navigate to **Settings → Backup** to get started.

The Backup page is organized into four tabs: **WebDAV**, **S3**, **Import/Export**, and **Reminder**.

***

## Manual Import / Export

The **Import/Export** tab lets you create a complete snapshot of your data and restore it whenever you need — no cloud account required.

### Export your data

<Steps>
  <Step title="Open Settings → Backup → Import/Export">
    Tap the **Import/Export** tab.
  </Step>

  <Step title="Tap Export">
    Tap the **Export** item under *Local Backup / Export*. The system file picker opens.
  </Step>

  <Step title="Choose a save location">
    Navigate to a folder — local storage, an SD card, or a connected cloud drive — and confirm. Rikka saves a ZIP file containing your full database and associated files.
  </Step>
</Steps>

### Import from a backup file

<Steps>
  <Step title="Tap Import">
    Tap the **Import** item under *Local Backup / Export*. The system file picker opens filtered to `.zip` files.
  </Step>

  <Step title="Select your backup ZIP">
    Locate and tap the backup file you previously exported.
  </Step>

  <Step title="Restart Rikka">
    After a successful restore Rikka shows a restart prompt. Tap **Restart** to apply the restored data.
  </Step>
</Steps>

<Note>
  Manual export is the recommended method for migrating to a new Android device. Copy the ZIP file to the new device via cable, Bluetooth, or a file-sharing app, then import it.
</Note>

### Import from other apps

Rikka can also import conversation history exported from other AI chat apps.

<Tabs>
  <Tab title="Chatbox">
    Tap **Import from Chatbox**, then select the `.json` export file produced by Chatbox. Rikka parses the conversation format and merges the history into your local database.
  </Tab>

  <Tab title="Cherry Studio">
    Tap **Import from Cherry Studio**, then select the `.zip` export file. Rikka extracts and converts the Cherry Studio backup format automatically.
  </Tab>
</Tabs>

***

## WebDAV Sync

The **WebDAV** tab connects Rikka to any WebDAV-compatible server for automatic cloud backup and restore.

<Note>
  WebDAV sync is compatible with **Nextcloud**, **ownCloud**, and any server that implements the WebDAV protocol — including many NAS devices.
</Note>

### Configure the WebDAV connection

<Steps>
  <Step title="Open Settings → Backup → WebDAV">
    Tap the **WebDAV** tab on the Backup page.
  </Step>

  <Step title="Enter the server URL">
    Paste your WebDAV endpoint URL into the **Server Address** field. For Nextcloud, this is typically `https://your-server.com/remote.php/dav/files/username/`.
  </Step>

  <Step title="Enter credentials">
    Fill in your **Username** and **Password**. For Nextcloud, generate a dedicated app password under *Personal Settings → Security* rather than using your main account password.
  </Step>

  <Step title="Set the remote path">
    Enter the folder path on the server where backups should be stored in the **Path** field. The default is `rikkahub_backups`. Rikka creates the folder automatically if it does not exist.
  </Step>

  <Step title="Choose what to back up">
    Toggle the **Chat Records** and **Files** segments to include or exclude each item type.
  </Step>

  <Step title="Test the connection">
    Tap **Test Connection** to verify that Rikka can reach the server with the supplied credentials. A success toast confirms everything is working.
  </Step>
</Steps>

### Back up now

Tap the **Backup Now** button at the bottom of the WebDAV tab. Rikka uploads a timestamped ZIP to your configured remote path and updates the *Last Backup* timestamp shown at the top of the tab.

### Restore from WebDAV

<Steps>
  <Step title="Tap Restore">
    Tap the **Restore** button. Rikka fetches the list of available backup files from the remote path and displays them in a bottom sheet.
  </Step>

  <Step title="Select a backup file">
    Each file shows its name, last-modified date, and size. Tap **Restore Now** on the file you want to restore from.
  </Step>

  <Step title="Restart Rikka">
    After a successful restore, tap **Restart** when prompted.
  </Step>
</Steps>

You can also delete individual backup files from the restore sheet by tapping **Delete** next to the file.

***

## S3 Sync

The **S3** tab connects Rikka to any S3-compatible object storage service.

<Note>
  S3 sync works with **AWS S3**, **Cloudflare R2**, **MinIO**, **Backblaze B2**, and any other service that implements the S3 API.
</Note>

### Configure the S3 connection

<Steps>
  <Step title="Open Settings → Backup → S3">
    Tap the **S3** tab on the Backup page.
  </Step>

  <Step title="Enter the endpoint URL">
    Paste the S3-compatible endpoint into the **Endpoint** field. For AWS S3, use `https://s3.amazonaws.com`. For Cloudflare R2, use your account-specific R2 endpoint.
  </Step>

  <Step title="Enter your access key ID">
    Fill in the **Access Key ID** field. Create a dedicated IAM user or API token with the minimum required permissions (`s3:GetObject`, `s3:PutObject`, `s3:DeleteObject`, `s3:ListBucket`).
  </Step>

  <Step title="Enter your secret access key">
    Fill in the **Secret Access Key** field. This value is masked by default; tap the eye icon to reveal it.
  </Step>

  <Step title="Set the bucket and region">
    Enter the **Bucket** name (for example, `my-rikka-backups`). Enter the **Region** — use `auto` for Cloudflare R2 or a region code such as `us-east-1` for AWS. The default region is `auto`.
  </Step>

  <Step title="Choose what to back up">
    Toggle the **Chat Records** and **Files** segments to include or exclude each item type.
  </Step>

  <Step title="Test the connection">
    Tap **Test Connection** to verify connectivity and permissions.
  </Step>
</Steps>

### Back up now

Tap **Backup Now**. Rikka uploads a timestamped ZIP to the configured bucket and updates the *Last Backup* timestamp.

### Restore from S3

<Steps>
  <Step title="Tap Restore">
    Tap the **Restore** button. Rikka lists all backup objects in the bucket in a bottom sheet.
  </Step>

  <Step title="Select a backup">
    Each entry shows its name, modification date, and size. Tap **Restore Now** to restore from that file.
  </Step>

  <Step title="Restart Rikka">
    Tap **Restart** when prompted to apply the restored data.
  </Step>
</Steps>

You can also delete individual backup objects from the restore sheet by tapping **Delete** next to the entry.

***

## Backup Reminders

The **Reminder** tab helps you build a regular backup habit by having Rikka send a notification when your last backup is overdue.

<Steps>
  <Step title="Open Settings → Backup → Reminder">
    Tap the **Reminder** tab.
  </Step>

  <Step title="Enable reminders">
    Toggle on **Enable Reminders**.
  </Step>

  <Step title="Set the interval">
    Choose how often Rikka should remind you: **1**, **3**, **7**, **14**, or **30** days. The default is 7 days.
  </Step>
</Steps>

Once enabled, Rikka checks on launch whether the interval has elapsed since the last recorded backup. If it has, a notification appears prompting you to back up.

The last backup time is updated automatically whenever you run a WebDAV or S3 backup. For manual exports, the timestamp is updated after each successful export.

<Tip>
  Pair the 7-day reminder with WebDAV or S3 sync so that when the reminder fires you can back up in one tap without leaving the app.
</Tip>


# Access Rikka's Chat Interface from Any Browser on Your LAN
Source: https://docs.rikka-ai.com/settings/web-access

Run a local HTTP server inside Rikka so you can use the full chat interface from any desktop or mobile browser on the same Wi-Fi network.

Rikka can run a lightweight HTTP server directly on your Android device. Once the server is running, any browser on the same local network — your laptop, a tablet, or another phone — can open the Rikka chat interface without installing anything. The app stays on your phone; the web UI is just a window into it.

<Note>
  The web server only works while Rikka is running on your Android device. Closing or force-stopping the app shuts the server down. A persistent foreground notification keeps the server alive when the app is in the background.
</Note>

## Starting the Server

<Steps>
  <Step title="Open Web Access settings">
    In Rikka, go to **Settings → Web Access**.
  </Step>

  <Step title="Configure the port">
    Enter a port number in the **Port** field. The default is **8080**. Use any value between 1024 and 65535. You cannot change the port while the server is already running.
  </Step>

  <Step title="Choose network visibility">
    Toggle **Localhost Only** if you want the server accessible only from the device itself (useful for ADB port forwarding). Leave it off to allow access from other devices on your Wi-Fi network.
  </Step>

  <Step title="Set an access password (recommended)">
    Enter a password in the **Access Password** field. See [Securing the server](#securing-the-server) below.
  </Step>

  <Step title="Start the server">
    Tap the **Start** button. Rikka requests notification permission and, on Android 15 and later, local network permission, then starts the server.
  </Step>
</Steps>

## Finding the Server URL

Once the server is running, the Web Access page shows the available addresses:

| Address type      | When shown                            | Example                            |
| ----------------- | ------------------------------------- | ---------------------------------- |
| **LAN Address**   | Localhost Only is off                 | `http://192.168.1.42:8080`         |
| **mDNS Address**  | Localhost Only is off, mDNS available | `http://android-device.local:8080` |
| **Local Address** | Always                                | `http://localhost:8080`            |

Tap any address row to copy it to your clipboard. A toast confirms the copy. Open the URL in any browser on the same network.

<Tip>
  The mDNS address (`.local`) is easier to type and works reliably on most home networks without knowing the device's IP. If it doesn't resolve, fall back to the LAN Address.
</Tip>

## Securing the Server

<Warning>
  If you expose the server beyond localhost (i.e. **Localhost Only** is disabled), anyone on your local network can reach the chat interface. Set an access password to prevent unauthorized access to your conversations and AI provider keys.
</Warning>

Rikka uses JWT-based authentication to protect the server:

<Steps>
  <Step title="Enter an access password">
    Type a password in the **Access Password** field on the Web Access settings page.
  </Step>

  <Step title="Enable JWT authentication">
    Toggle on **Enable JWT Auth**. This toggle becomes available once you have entered a non-empty password. Clearing the password automatically disables JWT auth.
  </Step>

  <Step title="Authenticate in the browser">
    When you open the server URL for the first time, the web UI prompts for the password. On success, a JWT token is stored in the browser session so you don't have to enter it again until the token expires.
  </Step>
</Steps>

## Configuration Reference

<ParamField type="integer">
  The TCP port the HTTP server listens on. Must be between 1024 and 65535. Shown as an error state if the value is out of range. Cannot be changed while the server is running.
</ParamField>

<ParamField type="boolean">
  When enabled, the server binds to `127.0.0.1` and is only reachable from the device itself. When disabled, the server binds to all network interfaces and is reachable from other devices on the same network. Cannot be changed while the server is running.
</ParamField>

<ParamField type="boolean">
  Require a signed JWT token for every request. Tokens are issued at login using the **Access Password**. Only available when the access password field is non-empty.
</ParamField>

<ParamField type="string">
  The password users must enter in the browser to obtain a JWT token. Clearing this field automatically disables JWT auth. Treat this like any other sensitive credential.
</ParamField>

## Stopping the Server

Tap the **Stop** button on the Web Access settings page. The foreground service and notification are dismissed and all active browser sessions lose connectivity immediately.

You can also stop the server by dismissing the persistent notification from the Android notification shade.