::callout{variant="primary"}
**Looking for Msty App?**  
If you're looking for the **Msty App 1.x** documentation instead, you can find it here: [**Go to Msty App Docs →**](http://docs.msty.app){target="\_blank"}
::

[Msty Studio](https://msty.ai){target="\_blank"} is a [privacy-first](https://msty.ai/privacy-first){target="\_blank"} AI platform that empowers you to design and run advanced AI workflows using local and online models, directly from a web or desktop interface. Msty offers seamless integration with hundreds of top-tier models, powerful tools like Toolbox (MCP), Knowledge Stacks (RAG), Personas (Customized AI Assistants), and Turnstiles (Workflows), and fully local data storage, ensuring both sophistication and security in your AI processes.



## Getting Started

You can get started for free with [Msty Studio Desktop](/getting-started/desktop). 

Aurum subscribers get full access to both Msty Studio Web and Msty Studio Desktop.

See the [plan comparison](https://msty.ai/pricing#plan-comparison){target="_blank"} to view what features are available by plan type. 

::alert{type="info" icon="tabler:info-circle"}
Data does not sync between devices. Data is stored locally on your device. Studio web stores data directly to your browser.
::

### Msty Studio Desktop

Msty Studio Desktop is our Msty Desktop 2.0 app and is FREE to get started on. Check out our [Announcement](https://msty.ai/blog/announcing-studio-desktop){target="\_blank"} to learn more about our vision for Msty Studio Desktop.

To get started with Studio Desktop, please see the [Desktop](/getting-started/desktop) guide.

### Msty Studio Web :aurum-tag

Msty Studio Web is a web-based application that is capable of running the majority of features that Msty Studio Desktop offers. However, to unlock additional features, including Real-Time Data, Toolbox, and Local Models, Studio Web will need to connect to [Msty Studio Desktop](/features/remote-connections) or [Msty Sidecar](/how-tos/sidecar). Connecting Web to Desktop is the recommended approach for most users.

Even though Msty Studio Web is a web-based app, data is stored directly on your browser's local storage. This helps us maintain our Privacy-first policy and our commitment to keep your data in your control.

#### Existing Msty App v1.x user?

If you are an existing user of Msty App, please see the [Quick Start](/getting-started/quick-start) guide to get started.

#### New to Msty Studio?

If you are brand new to Msty Studio, please see the [Onboarding](/getting-started/onboarding) guide to get started.

## Popular Topics

- [Managing Models](/getting-started/managing-models) - Learn how to add and configure AI models
- [Toolbox](/features/toolbox/tools) - Leverage powerful tools using MCP
- [Knowledge Stacks](/features/knowledge-stacks/overview) - RAG the right way
- [Workspaces](/features/workspaces) - Organize your projects and conversations
- [Environment Variables](/features/environment) - Configure your development environment
- [Data Backups](/features/data-backups) - Keep your data safe and synchronized

## Need Help?

- **Getting Started**: Check out our [Quick Start](/getting-started/quick-start) or [Onboarding](/getting-started/onboarding) guides
- **How-Tos**: Find step-by-step guides in our [How-Tos](/how-tos/manage-license) section
- **Whats new**: See what's new in Msty Studio by visiting our [Changelog](https://msty.ai/changelog){target="\_blank"}
- **Support**: Visit our [Discord](https://msty.ai/discord){target="\_blank"} for issues and discussions


---

## Welcome to Msty Studio! 

Already have the **Aurum license** and **Msty App** installed? Awesome — you're all set to start using **Msty Studio**!

These instructions are for those who actively used Msty App 1.x and have an Aurum subscription and will get you started quickly with Msty Studio. 

Before continuing, grab your license key, which you can do by going to [Lemon Squeezy](https://app.lemonsqueezy.com/my-orders/login).

For Studio Desktop, you can migrate your data from Msty App v1.x to Studio Desktop. See the [Data Migration](#data-migration-for-msty-app-users) section for more details.

## Quick Start Instructions for Msty Studio Web :aurum-tag

::steps

1. Open the **Msty App**, go to **Settings → Local AI**.
2. Scroll to **Allowed Network Origins** and add:

   ```
   https://msty.studio
   ```

   This enables Msty Studio to connect with your Msty App and access your Local AI models. Keep Msty App open so that Studio can connect to it for a quick start to Studio.

3. Head over to [**Msty Studio**](https://msty.studio)

4. Paste in your license key and click **Next**.

5. On the following screen, Msty Studio will detect your Msty App and list available Local AI models.

6. Click **Let's Go!** — and you're in!

![Quick Start Msty Studio](/images/welcome-to-msty.png)
::

::alert{type="info" icon="tabler:info-circle"}
**Don’t have Msty App installed or running yet?**
No worries — just head to the next section, and we’ll guide you through the full setup step by step.
::

## Quick Start Instructions for Msty Studio Desktop :aurum-tag
::steps

1. [Download Msty Desktop](/getting-started/desktop) and install
2. Enter your license key in **Settings → License and Access**
3. Proceed to the following section if you'd like to migrate data from Msty App 1.x to Msty Studio Desktop

::

## Data Migration for Msty App Users

Msty App v1.x free and Aurum users can migrate much of their data to Msty Studio Desktop. Before proceeding, please **backup** your data for BOTH Msty App and Msty Studio Desktop prior to migration.

::alert{type="info" icon="tabler:info-circle"}
Data migration is only available for Msty Studio Desktop at this time. 
::

### Data Migration includes

You can migrate any of the following items from Msty App v1.x to Msty Studio Desktop:
- **Prompts**: All your workspace's Prompt Library prompts
- **Remote Model Providers**: All your workspace's remote providers and selected models from Msty App - **does NOT include API keys**, these will need to be re-entered for each provider
- **Conversations**: All your workspace's conversations 
- **Attachments**: All your workspace's attachments that you include in the zip file

Migrated conversations and prompts will be added to new project folders in Msty Studio. Your existing Msty Studio Desktop data will not be overwritten.

### Migration steps

You can migrate data one workspace at a time. If you have multiple workspaces, you will need to repeat the migration steps for each workspace you intend to migrate data to.

::steps

1. Locate the **msty.db** database and attachment files

To locate the **default workspace** database and attachments, follow these steps:
  - Open Msty App and go to **Settings > General > Data Paths** and open location for **App Data**
  - This will open the folder where the default workspace database file and attachments folder are stored

![Default Workspace Data Paths](/images/quick-start/default-data.png)

To locate a **custom workspace** database and attachments, follow these steps:
  - Right click on the workspace and then select option to **Reveal in Finder** (macOS) or **Open Folder** (Windows)

![Default Workspace Data Paths](/images/quick-start/workspace-data.png)

2. If you plan to migrate attachments, first zip the attachments folder 
3. Open Msty Studio Desktop
4. Ensure you are in the workspace you want to migrate data to
   - If you are not in the correct workspace, switch to the desired workspace by clicking on the workspace icon
5. Go to **Settings > Data > Data Migration** 
6. Select the database file you want to import the items from
7. Select the items you want to import from the database file
9. Optionally select a zipped attachments file to import; attachments can also be imported later, after the database has been imported
8. Click the **Migrate** button to migrate items from database file

:: 

You will see confirmation messages when data migration and attachment imports are complete. 

#### Migration Workspace Issues

Thank you to our Discord community members, if you are running into issues importing a Workspace, try the following steps: 


##### Linux / Mac

1. **Save the script**
   - Create a new file called `optimize_db.sh` in the same folder as `msty.db`
   - Paste the following script into it

  ```bash
      # Close the database properly first to merge WAL files
      sqlite3 msty.db "PRAGMA wal_checkpoint(FULL);"

      # Create a fresh export that includes all data
      sqlite3 msty.db ".output msty_temp.sql" ".dump" ".exit"

      # Create a completely new database from the dump
      rm -f msty_copy.db msty_copy.db-shm msty_copy.db-wal
      sqlite3 msty_copy.db ".read msty_temp.sql"
      rm msty_temp.sql

      # Optimize the new database
      sqlite3 msty_copy.db "PRAGMA integrity_check;"
      sqlite3 msty_copy.db "PRAGMA optimize;"
      sqlite3 msty_copy.db "VACUUM;"

      # Verify database access
      echo "Verification:"
      sqlite3 msty_copy.db "SELECT COUNT(*) FROM chat_session_folders;"

      # Compare file sizes
      echo "Original size:"
      du -h msty.db
      echo "Optimized copy size:"
      du -h msty_copy.db

      echo "Done! You can now import msty_copy.db"
  ```

2. **Open Terminal**
   - Press `Cmd + Space` and type "Terminal"

3. **Navigate to your folder**
   - Type: `cd /path/to/your/folder`
   - Replace `/path/to/your/folder` with the actual path

4. **Make script executable**
   - Type: `chmod +x optimize_db.sh`

5. **Run the script**
   - Type: `./optimize_db.sh`

##### Windows
1. **Install SQLite**
   - Open Command Prompt (CMD)
   - Run: `winget install SQLite.SQLite`

2. **Save the script**
   - Save the `fix-msty-db.ps1` script to: `C:\Users\YourUsername\AppData\Roaming\Msty`

  ```bash
      # Close the database properly first to merge WAL files
      sqlite3 msty.db "PRAGMA wal_checkpoint(FULL);"

      # Create a fresh export that includes all data
      sqlite3 msty.db ".output msty_temp.sql" ".dump" ".exit"

      # Create a completely new database from the dump
      Remove-Item -Path msty_copy.db, msty_copy.db-shm, msty_copy.db-wal -ErrorAction SilentlyContinue
      sqlite3 msty_copy.db ".read msty_temp.sql"
      Remove-Item msty_temp.sql

      # Optimize the new database
      sqlite3 msty_copy.db "PRAGMA integrity_check;"
      sqlite3 msty_copy.db "PRAGMA optimize;"
      sqlite3 msty_copy.db "VACUUM;"

      # Verify database access
      Write-Host "Verification:" -ForegroundColor Green
      sqlite3 msty_copy.db "SELECT COUNT(*) FROM chat_session_folders;"

      # Compare file sizes
      Write-Host "`nOriginal size:" -ForegroundColor Green
      Get-Item msty.db | Select-Object Name, @{Name="Size";Expression={"{0:N2} MB" -f ($_.Length / 1MB)}}

      Write-Host "`nOptimized copy size:" -ForegroundColor Green
      Get-Item msty_copy.db | Select-Object Name, @{Name="Size";Expression={"{0:N2} MB" -f ($_.Length / 1MB)}}

      Write-Host "`nDone! You can now import msty_copy.db" -ForegroundColor Green
  ```

  - Replace `YourUsername` with your actual Windows username

3. **Open PowerShell**
   - Press `Win + X` and select "Windows PowerShell"

4. **Navigate to the Msty folder**
   - Run: `cd ~\AppData\Roaming\Msty`

5. **Run the script**
   - Run: `.\fix-msty-db.ps1`

##### If you get a script execution error

Try one of these options:

**Option 1: Run this single script only**
- Run: `powershell -ExecutionPolicy Bypass -File .\fix-msty-db.ps1`

**Option 2: Enable PowerShell scripts permanently** (has security implications)
- Run: `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`

::Resources


---

These onboarding instructions are meant for new Msty Studio users. If you are an existing Msty App v1.x and Aurum subscriber, please check out the [Quick Start](/getting-started/quick-start) guide.

## Getting Started Video Guide
::YouTubePlayer{videoId="TdGjKf4vRPo"}
::

## Msty Studio Desktop Onboarding Instructions

You can get started with Msty Studio Desktop for FREE. 

::steps

1. [Download Msty Studio Desktop](/getting-started/desktop) 

2. On initial launch, you'll be asked how you'd like to proceed - either with using existing local models, setting up a new local model, or adding an API key for an online provider. The quickest way to get started is to proceed with a local model. You can add additional local and online models later. 

3. Once you have your Remote or Local Provider set up, click on **Let's Go!**

::

::alert{type="info" icon="tabler:info-circle"}
Msty Studio installs a separate instance of Ollama when setting up Local AI Services. This is to allow Msty Studio to have control over Ollama, allowing Msty to manage models, version updates, etc. If you have Ollama and do not want Msty Studio to manage Ollama, you can add Ollama as a Remote Provider (remote meaning separate from Msty, but may still be running on local machine) by selecting Ollama in the dropdown. This will allow you to use Ollama models you have setup without Msty having management access over Ollama. 
::

### Install Local AI From Archive file

During onboarding (and from Settings > Local AI > Services Version) you choose to setup an earlier version of Ollama if you do not want to use the latest version, which is what Msty Studio will install when setting up Local AI Services. 

![import ollama archive](/images/quick-start/import-ollama-archive.png)

To install from an archive file, select the option as seen in the image above. 

You'll want to have an archive file ready. You can download one from the [Ollama Version Archives](https://github.com/ollama/ollama/releases){target="_blank"} by downloading the appropriate file for your Operating System from the verion > assets section. 

Select the archived file from the file selection window and Msty Studio will install using the selected file. 

::alert{type="info" icon="tabler:info-circle"}
If you see an error during Local AI Services setup, try this option as an alternative method to install Local AI Services.
::

## Msty Studio Web Onboarding Instructions :aurum-tag

::steps

1. [Purchase an Aurum license](https://msty.ai/pricing) if you haven't already and keep your license key handy

2. Open a browser and navigate to Msty Studio at [https://msty.studio](https://msty.studio)

3. Enter your license key and click **Next**

4. You'll now have a few options on how you can proceed. In order to make use of Msty, you will need to add either a local or remote model provider.
   ![Msty Studio Initial Setup](/images/initial-setup.png)
   - To add a Remote Provider, click **Add Provider**. There are many available options, such as OpenAI, Claude, and Gemini. You will first need an API Key from the desired provider in order to add the remote provider to Msty.
5. Once you have your Remote or Local Provider set up, click on **Let's Go!**

## ![Quick Start Msty Studio](/images/welcome-to-msty.png)

::

::alert{type="info" icon="tabler:info-circle"}
**Safari user?** Safari is not directly supported by Msty Studio however there is a workaround using [Remote Connections](/features/remote-connections) by leveraging the tunneling feature.
::

::Resources


---

![msty studio](/images/image-comparison.png)

### Quick Facts
Are you a previous Msty App 1.x users? Here are some quick facts to know: 

1. Studio Desktop installs separately from Msty App (v1.x).
2. You do not need to remove Msty App (v1.x), you can continue using it while using Studio Desktop.
3. Studio Desktop Aurum activation will count against your Aurum activated devices limit, so you may need to deactivate a device if you have reached your limit.
4. Studio Desktop is available for Windows, Mac, and Linux.
5. A migration tool is available to help migrate some of your existing Msty App (v1.x) data to Studio Desktop.


## Msty Studio Desktop Download Options

Please select the download option for your operating system.

::tabs{variant="card" sync="user-os"}
::div{label="Windows" icon="iconoir:windows"}

### Windows

- [Download Msty Studio Desktop (x64)](https://next-assets.msty.studio/app/latest/win/MstyStudio_x64.exe)

When installing on Windows, please install as an Administrator for your user account only. Installing for all users is not supported due to a Windows limitation.

Corporate SSL issues? Try running the following command: 
```bash
   $env:NODE_TLS_REJECT_UNAUTHORIZED="0"; & <MSTY STUDIO.EXE PATH>
```
Replace `<MSTY STUDIO.EXE PATH>` with the actual path to the Msty Studio executable file.

::

::div{label="Mac" icon="hugeicons:apple"}

### Mac

- [Download Msty Studio Desktop (Apple Silicon - M1, M2, M3, M4)](https://next-assets.msty.studio/app/latest/mac/MstyStudio_arm64.dmg)
- [Download Msty Studio Desktop (Intel Macs)](https://next-assets.msty.studio/app/latest/mac/MstyStudio_x64.dmg)

::

::div{label="Linux" icon="ph:linux-logo"}

### Linux

Linux requires some additional manual steps after downloading. 

---

### AppImage Instructions

[Download Msty Studio Desktop (x64 AppImage)](https://next-assets.msty.studio/app/latest/linux/MstyStudio_x86_64.AppImage)

After download is complete, run the following command in your terminal to make the AppImage executable:

```bash
chmod a+x ./<DownloadedFileName>.AppImage
```

Then, you can run the AppImage file:

```bash
./<DownloadedFileName>.AppImage --no-sandbox

```
Note: You may need to install appropriate packages like libfuse2 (if your system does not have them already) in order to run the AppImage file.


**Using GTK 2/3 and GTK 4 in the same process is not supported** Error? 

Try running Msty from the terminal with: 
```bash
./MstyStudio_x86_64.AppImage --gtk-version=3
```

---

### Deb Instructions

[Download Msty Studio Desktop (x64 deb)](https://next-assets.msty.studio/app/latest/linux/MstyStudio_amd64.deb)

After download is complete, run the following command to install the deb package:
```
sudo apt install ./<DownloadedFileName>.deb
```

Once the installation is complete, run the following command to launch Msty Studio Desktop:

```bash
MstyStudio
```

Sometimes the installation may experience permission issues if the '_apt' user does not have enough privileges. In that case, run the following two commands to mitigate this issue and then run Msty again.

```bash
sudo chown root:root /opt/MstyStudio/chrome-sandbox
```
```bash
sudo chmod 4755 /opt/MstyStudio/chrome-sandbox
```

::
::


### Looking for Msty App 1.x?
::Collapsible{title="Expand this section to see download options"}
  Msty App 1.x is still available for download if you need it. See below for download links and installation instructions. See the [Msty App 1.x Docs](https://docs.msty.app){target="_blank"} for more info.

  ::tabs{variant="card" sync="download-os"}
  ::div{label="Windows" icon="iconoir:windows"}
  ### Windows
  Choose between two versions depending on your hardware.

  #### CPU-Only Version
  Ideal for systems without a dedicated GPU.

  :button-link[Download Msty (x64 CPU)]{left-icon="tabler:download" variant="outline" to="https://assets.msty.app/prod/latest/win/cpu/Msty_x64.exe" self}



  #### GPU Version
  Optimized for systems with a [compatible AMD or NVIDIA GPU](/getting-started/gpus-support), offering improved performance.

  :button-link[Download Msty (x64 GPU)]{left-icon="tabler:download" variant="outline" to="https://assets.msty.app/prod/latest/win/auto/Msty_x64.exe" self}
  ::
  ::div{label="Mac" icon="hugeicons:apple"}
  ### Mac
  We offer installers for both Apple Silicon and Intel-based Macs.

  #### Apple Silicon
  For M1, M2 and M3 chip-based Macs.

  :button-link[Download Msty (M1/M2/M3)]{left-icon="tabler:download" variant="outline" to="https://assets.msty.app/prod/latest/mac/Msty_arm64.dmg" self}



  #### Intel
  For Macs with Intel processors.
  :button-link[Download Msty (Intel)]{left-icon="tabler:download" variant="outline" to="https://assets.msty.app/prod/latest/mac/Msty_x64.dmg" self}
  ::
  ::div{label="Linux" icon="ph:linux-logo"}
  ### Linux
  Download the version that best fits your setup.

  #### AppImage (CPU Version)
  A universal package that runs on most Linux distributions, optimized for CPUs.
  :button-link[Download Msty (AppImage CPU)]{left-icon="tabler:download" variant="outline" to="https://assets.msty.app/prod/latest/linux/amd64/Msty_x86_64_amd64.AppImage" self}



  #### Deb Installer (CPU Version)
  Specifically for Debian-based distributions (like Ubuntu) with CPU optimization.
  :button-link[Download Msty (.deb CPU)]{left-icon="tabler:download" variant="outline" to="https://assets.msty.app/prod/latest/linux/amd64/Msty_amd64_amd64.deb" self}



  #### AppImage (AMD GPU - ROCm Version)
  For systems with AMD GPUs using ROCm, available as a universal AppImage.
  :button-link[Download Msty (AppImage AMD GPU)]{left-icon="tabler:download" variant="outline" to="https://assets.msty.app/prod/latest/linux/rocm/Msty_x86_64_rocm.AppImage" self}



  #### Deb Installer (AMD GPU - ROCm Version)
  A ROCm-optimized version for Debian-based distributions.
  :button-link[Download Msty (.deb AMD GPU)]{left-icon="tabler:download" variant="outline" to="https://assets.msty.app/prod/latest/linux/rocm/Msty_amd64_rocm.deb" self}
  ::
  ::

  ## Installation Instructions
  After downloading the appropriate installer for your system, follow the instructions below:

  ::tabs{variant="card" sync="download-os"}
  ::div{label="Windows" icon="iconoir:windows"}
  ### Windows
  Double-click the installer and follow the setup wizard.
  ::
  ::div{label="Mac" icon="hugeicons:apple"}
  ### Mac
  Open the downloaded `.dmg` file and drag Msty to your Applications folder.
  ::
  ::div{label="Linux" icon="ph:linux-logo"}
  ### Linux
  Read [how to install Msty on Linux.](/how-to-guides/install-msty-on-linux)
      ::
    ::
::

::Resources

---

You can manage AI providers and models from **Model Hub**.

![adding new models](/images/model-hub.png)

## Model Matchmaker

If you're unsure which model is the best for your needs, select **Match Maker** and adjust the scales according to what is most important.

![msty matchmaker](/images/matchmaker.png)

Matchmaker will consider what you are looking for against the strengths of available models, and provide recommendations for which models best match your criteria.

![msty matchmaker ranked models](/images/ranked-models.png)

Now, you have a starting point for which Model Providers and Models to consider using in Msty.

Then, the real fun! Testing the models in Msty to see which one best encapsulates your needs.

BTW - a big part of the charm of Msty is the ability to use multiple models. So, if one model doesn't quite cut it, then consider leveraging two (or more models) where each model provides complimentary skills. Check out [Split Chats](/features/conversations/split-chat) and [Turnstiles](/features/turnstiles) for more insights.

## Model Providers

You can edit and remove existing Cloud Providers from the **Model Providers** tab.

You can also add new Providers and Models by selecting **Add Provider**.

As these are mainly Cloud Providers, you will first need to set up and account with the desired provider, generate and copy their API Key, and then add the API Key to Msty when adding a New Provider.

## Local AI Models

You can add and remove Local Models from the **Local AI Models** tab.

The **Featured Models** tab displays popular Local Models that are available for installation.

The **Installed Models** tab displays the models currently installed on your device. You can remove models from this tab to uninstall.

The **Ollama Models** and **Hugging Face Models** tabs allow you to search Ollama and Hugging Face for models that you can install onto your device. As long as the model is public and has an available GGUF (GPT-Generated Unified Format) file for download, then it typically is available to install.

The **Import GGUF Model** tab allows you to Select a GGUF model file from your file system to import into Msty Local AI.

## Import a GGUF Model
To import a GGUF model that you have downloaded locally, navigate to the **Import GGUF** tab, select directory and then browse to the location of the GGUF file on your device.

You can either establish a symlink to point Msty Studio to the GGUF file location, or you can copy the GGUF file into Msty Studio's models directory.

## Import a Safetensors Model
To import a Safetensors Model that you have downloaded locally, navigate to the **Import Safetensors** tab, select directory and then browse to the location of the Safetensors file on your device.

## Model Squad

Model Squad is a collection of specialized AI models to assist with Msty functionality.

As opposed to generic or standard text summaries, you can have GenAI create conversation titles, context shield summaries, and and real-time prompt data synthesis.

This allows you to use an AI that may be better at generating descriptions than the current model that you have selected.

## Set A Default Model

To set a default model, expand the model selection box in the Conversations toolbar and then select the star icon to set the model as the default.

## Update Model Name

From Model Providers, Local AI Models > Installed Models, or the model selector in the the Conversations toolbar, select the edit icon to update the model name.

You can update the model name to be more descriptive of the model's purpose or the type of conversations that you are having with it.

## Set Model's Purpose (tags)

![model purpose](/images/model-purpose.png)

Also, from the window that opens when you select the edit icon, you can set the model's purpose. These are tags that are used to categorize the model according to the standard use-cases they provide.

### Model Purpose Types

- **Text**: General text generation and understanding. Typical applications include text classification, generation, translation, completion, and summarization.
- **Coding**: Assisting with code generation and debugging. Typical applications include code completion, generation, analysis, debugging, and summarization.
- **Tools**: Interfacing with external tools and APIs. These models can be used for Msty Tools feature (MCP).
- **Image**: Generate images. This will need to be set correctly according to model type, see [Image Generation](/features/image-gen).
- **Vision**: Analyzing and understanding visual content, such as if you were to add an image attachment to a chat. Typical applications include image classification, object detection, visual search, and image descriptions.
- **Embedding**: Creating and using embeddings for various tasks. The models are used for vectorization, similarity search, and clustering and are typically used for RAG - such as with Msty's Knowledge Stacks feature.
- **Streaming**: Handling real-time (or near real-time) data streams. Typical applications include real-time data processing, event detection, and anomaly detection.
- **Thinking**: Reasoning models will have additional configurations available in model parameters - such as for some models you can set thinking to a low, medium, high setting.

## Provider and Model Logos

You can customize the logo for a Provider or Model by selecting the edit icon in Model Hub and then selecting the image icon to upload a new logo.

![change model logo](/images/change-provider-model-logo.png)

## GPU support

If your system has a compatible GPU, you can enable GPU support for models that support it by selecting the corresponding option in **Settings > Local AI > Service ellipsis menu**.

::Resources


---

MLX (Apple Machine Learning eXchange) is Apple’s machine learning framework optimized for Apple Silicon. It enables fast, efficient training and inference using GPU and CPU acceleration on macOS and iOS devices. **Msty Studio Desktop** supports MLX for running local models natively, making it ideal for private, high-performance AI workflows on your Mac.

## Adding MLX Models
Adding and managing MLX models is fundamentally similar to adding and managing other local models in Msty Studio. 

In **Model Hub**, you can view featured MLX models and search for models on the MLX Hugging Face Community tab. 

![mlx models](/images/mlx/mlx-model-hub.png)

Please note that there are fewer models that currently support MLX.

## Managing MLX Service

You can manage and configure the MLX service in **Settings > MLX Service**. Here, you can start or stop the MLX service, which is required to run MLX models locally.

![mlx service](/images/mlx/mlx-service.png)

You can also view the service health, stop and start the service, view the endpoint, version, logs, and more.

::Resources

---

llama.cpp is an open source C/C++ library that performs efficient inference on large language models with minimal setup and optimized performance across various hardware.

This provides another option for a local inference engine in Msty Studio in addition to Ollama and MLX. 

::alert{type="info" icon="tabler:info-circle"}
Llama.cpp support is an experimental feature and you may encounter issues. Please report any problems you find on our Discord server to help us improve the experience. 
::

Llama.cpp can be installed during new user onboarding or from **Model Hub > Llama.cpp**. 

## Adding Llama.cpp Models

In **Model Hub**, you can view featured Llama.cpp models and search for models on the Llama.cpp Hugging Face Community tab. 

Click on the download icon to download and install a model locally. 

## Managing Llama.cpp Service

You can manage and configure the Llama.cpp service in **Settings > Llama.cpp Service**. Here, you can start or stop the Llama.cpp service, which is required to run Llama.cpp models locally.

You can also view the service health, stop and start the service, view the endpoint, version, logs, and more.

### GPU support

If your system has a compatible GPU, you can enable GPU support for Llama.cpp models by selecting the corresponding option under the Llama.cpp service ellipsis menu. 

## Llama.cpp Model Parameters

LLama.cpp provides a few features that can give them an edge when used during conversations. 

Next to the model selection, when you have a Llama.cpp model selected, click on the **Model Parameters** icon.

**Here, you will see options specific to Llama.cpp, including**:

### Num ctx default to model max
This is the context window where you can select the option to use the max amount of context for a mode. 

The specific max value may not be known to Llama.cpp or Msty Studio; however, this option will set it to the max value. 

Setting to the max will benefit conversations as more context will be held onto, which will result in fewer hallucinations and improved conversation continuity. 

This does come at a cost in the form of your device's system performances being expended, which may result in decreased system performance. 

### Truncation Strategy 

As conversation get longer, you can set a truncation strategy so that you can continue conversations without getting a context limit reached message. 

**Options**: 
- **Truncate Middle** this truncates the middle portions of the conversation. This setting is ideal when the first parts of the conversation are important to maintain the overall context. Use this if the first interaction set the stage for the overall conversation. 
- **Truncate Old** - this truncates the first messages of the conversation. This setting is idea for continued conversations where the first messages are not critical to the continuity of the conversation. Use this if the latest messages are the most critical for continuity. 
- **None** - this does not truncate any messages in an ongoing conversation. Use this setting if full historical context is needed. However, this does run the risk of context limits being exceeded. 


::Resources

---

Personas is a powerful tool that allows you to create custom AI agents tailored to specific conversational contexts.

![Msty Personas](/images/personas.png)

## Create new Personas

You can create new personas from the **Personas** section, accessible on the left sidebar menu. You don't need to start from scratch though.

Select the down arrow next to **New Persona** and then select **Import Default Personas** to import a collection of Personas. You can edit any of these personas to customize them to fit your needs.

### Add a new custom Persona

::steps

1. Select the **New Persona** button - this will display form fields for configuring your new persona
2. Enter a **Name** you'd like to refer to your Persona by and select a corresponding icon
3. Fill in the **System Prompt** for the Persona. Prompts are an important part of the equation for making the best use of AI chat conversations. Be clear and descriptive about what you are wanting for the desired output. Don't be afraid to provide examples of a quality output that you are looking for so that the AI can reference the example when crafting its response.
4. Select whether you want to add the prompt before the system prompt, to replace the system prompts, or add after the system prompts.
5. Enable any additional settings to:
  - **Hide and isolate system prompt** which automatically hides and isolates user messages when sending Persona prompt
  - **Isolate response** which automatically isolates the generated response, excluding it from being added as context in follow-up messages
  - **Auto Response** which will automatically enable the Persona as an auto-responding persona 
6. Enter a brief **Description** of the Persona
7. Include **Add Ons** such as any relevant [attachments](/features/attachments), [real-time data](/features/real-time-data), related [toolsets](/features/toolbox/toolsets), context shield, desired model and any pertinent model parameters. Add-Ons add a ton of power and flexibility to your Persona and can take them from a simple canned prompt to a full-blown Agent.
8. **Few-Shot Prompts** let you provide example prompts to guide the Persona's responses, helping it understand the desired style or context of replies based on previous examples.

::

## Using Personas in conversations

[See how Personas are used in conversations](/features/conversations/main-chat#personas)

::Resources


---

Shadow Personas are assistants that observe the main conversation you are having in a chat or in multiple split chats. 

How the Shadow Persona responds to the conversation, is up to how you have configured the prompt for the underlying persona. 

To enable a Shadow Persona for a conversation, select the Shadow Persona icon in the top right of the window, to the left of the ellipsis (...) menu. 

::alert{type="warning" icon="tabler:info-circle"}
Shadow Persona is not available when **Compact Mode** is enabled. Exit Compact Mode in order to enable a Shadow Persona. 
::

Shadow Personas can monitor multiple split chats. In the example below, the Shadow Persona is tasked with reviewing the responses from two split chats and then synthesize the responses into one single optimal response that takes the best parts of each split chat. 
![Shadow Personas Synthesize Split Chats Example](/images/shadow-personas/shadow-persona-synthesizer.png)

See the examples section below for additional useful usages for Shadow Personas. 

## Adding a new Shadow Persona :aurum-tag

### Step 1 - Create the underlying Persona
The underlying directives and capabilities of a Shadow Persona come from the underlying Persona. 

See the [Personas](/features/personas) learn how to create a new persona.

Shadow Personas adopt the following features of a Persona: 
- **System Prompt** - the prompt provides the main directives that a Shadow Persona is tasked with
- **Attachments** - add attachments that a Shadow Persona can reference to for additional context
- **Real-Time Data** - provide access to real-time data so that Shadow Personas can search the internet
- **Toolbox** - Shadow Personas can call tools and live context endpoints for additional context
- **Knowledge Stacks** - provide access to a Knowledge Stack so that a Shadow Persona can reference it for specific context
- **Model** - select a specific model for the Shadow Persona to use; the default model is the same model selected in the conversation
- **Model Parameters** - configure specific parameters; increase the context limit if using a local model for improved results


### Step 2 - Configure the new Shadow Persona

Click on the Shadow Persona icon in the top right of Msty Studio to expose Shadow Persona. 

![Configure New Persona Start](/images/shadow-personas/configure-new-shadow-persona.png)

Then, click on **Create New** to configure a new Shadow Persona. If you already have a Shadow Persona you'd like to attach to the conversation, then select the **Attach Existing** option and select the Shadow Persona to attach. 

After selecting **Create New**, you'll see a modal to configure the new Shadow Persona. 

![Configure Shadow Persona](/images/shadow-personas/configure-shadow-persona.png)

Fill out the Shadow Persona configuration accordingly. 

- **Shadow Persona Name** - provide a unique name for your Shadow Persona
- **Select Persona** - select the underlying Persona 
- **Update Trigger** - this is how often the Shadow Persona will respond; either after every new message, every three messages, or manually triggered
- **Messages Per Split** - the number of messages, per split, that will be sent to the Shadow Persona for context; if you only want a response given the most recent message(s) only, set to 1
- **Synthesis Mode** - most important for when there are multiple split chats, this will direct the Shadow Persona if it should respond to each split chat uniquely, if it should synthesize all of the split chats, or if it should compare/contrast the split chats
- **Max Versions** - this is the max number of Shadow Personas that will be kept during a conversation; after the number that is set, then the later messages will be dropped

Once you have your Shadow Persona configured how you want it, select **Create and Assign** to create the persona and assign it to the current conversation. 

## Using Shadow Persona in Conversations

When enabled in a conversation, the Shadow Persona will wait for the models in the conversation to complete their response before providing their own - with the exception of if you set the Shadow Persona to respond via manual trigger. 
![Shadow Persona working with](/images/shadow-personas/shadow-personas-options.png)

Referencing the above image, here are the key parts of the Shadow Persona: 
1. **Enable / Disable Shadow Persona** from auto-responding
2. **Ellipsis overflow menu** provides options to edit the Shadow Personas configuration, create a new Shadow Persona, and delete a Shadow Persona
3. **Manage Split Chats** section allows you to select which split chats are included for the Shadow Persona to monitor
4. **Output options** to toggle between outputs, copy an output, or remove an output
5. **Shadow Persona's response output** message according to their directive; this will also display tool usages, Knowledge Stacks referenced, and real-time data sources
6. **Manually trigger** Shadow Persona response 

## What you can do with Shadow Personas

There are countless ways you can use a Shadow Persona to provide value to your conversations. 

Here are just a few: 
- **A commentator** - provide color commentary on the main conversation. 
- **Response analysis** - provide an analysis of the quality of the response, this is especially useful when you have multiple split chats
- **Response synthesizer** - take the best parts of multiple responses in split chats and provides an improved response
- **Fact Checker** - enable add-ons for the underlying persona such as real-time data, knowledge stacks, or toolbox so that the Shadow Persona can check sources of record to see if the conversation models are providing accurate results
- **Monitor and act** - have a Shadow Persona watch a conversation and look for something specific, they can then either inform you that something you are looking for came up, or they can take further action by triggering a tool call to kick-off a workflows
- **Summarizer** - summarize your conversations as you are conversing in the main chat, so you have a clear, concise list of items discussed

Be sure to watch the videos in the Resources section below as well for ideas.  

::Resources

---

Environments are a powerful feature in Msty Studio that allow you to create and manage different settings for your different projects or use cases. By using environments, you can easily switch between different configurations without having to manually change settings each time.

## Add and Manage Environments :aurum-tag

On the left menu, select the ellipsis icon and then select **Environments** and then **Manage Environments**.

By default, there is a **Base Environment** that is created for you. This environment is used to store variables that are common across all environments.

Also, if the active environment doesn't have a variable set, it will fall back to the Base Environment and check to see if the variable is defined there.

### Add New Environment

To add a new environment, select the **Add Environment** button. Then, add an Environment **Name** and enter the **Variables** you want to set for this environment.

You can also click on the ellipsis icon next to an existing environment to **Clone Environment** and then use that as a starting point for a new environment.
![add new environment](/images/new-environment.png)

You can always come back and modify the environment variables later.

### Backup and Restore Environments

Select the down arrow icon next to the **Add Environment** button to backup or restore your environments.

### Remove Environment

To remove an environment, select the ellipsis icon next to the environment you want to remove and select **Delete Environment**.

## Set Active Environment

You can select an active Environment from the Manage Environments section by selecting the ellipsis icon and then select option to **Make Active Environment**.

You can also quickly select an Active Environment from the ellipsis icon on the main left menu and then select an icon under the **Environments** submenu.

If an Environment Variable is not in the selected Environment; however, is in the **Base Environment**, then the variable will fall back to the one listed in the Base Environment.

## Use Environment Variables

You can use Environment Variable in the following areas of Msty Studio:

1. Model provider API keys
2. System prompts
3. Conversations
4. Tools

You can copy and paste variables into these areas. Note that variable names will automatically begin with `MSTY_`, such as `MSTY_MY_VARIABLE`.

When a process runs, the variable placeholder will be replaced with the value of the variable in the active environment.

::alert{type="info" icon="tabler:info-circle"}
Use the same variable name across Environments for things like model provider API keys, this way, when you change the environment, you change the underlying API Key - making it easy to switch between model API environments.
::

### Dynamic Variables

There are a few dynamic variables that accessible from the Environment Variable picker (shift+shift+e). These variables are automatically populated with the current date and time, and can be used in your conversations to provide context or information. The following dynamic variables are available:

**These include:**

- {MSTY_LOCAL_DATE} - the current system date
- {MSTY_LOCAL_DATE_TIME} - the current system date and time
- {MSTY_LOCAL_TIMEZONE} - the current system timezone

![env dynamic variables](/images/env-dynamic-variables.png)
In the quick select modal, when you select a variable, it will be copied to your clipboard.
No newline at end of file

::Resources


---

Image generation can be accomplished with compatible models.

![image generation update car color](/images/img-gen/image-gen-cars.png)

## Set 'Image' Purpose

Most models capable of image generation will come with **image** already enabled as a model's purpose.

However, if you are using a model, or have added a custom model, where you know that the model supports image generation, then you'll need to enable **image** as a purpose for the model.

### Adding custom model

When adding a custom model, select **image** as a purpose.
![add custom model](/images/img-gen/add-custom-model.png)

### Updating existing model

To update purposes for an existing model, in the conversation area, click on the model selector, find the model you want to update, and then click on the edit icon.

This will open a modal where you can update the model's purpose.

Be sure to appropriately select purposes based on if the model is image-only or if it is multimodal.

::alert{type="info" icon="tabler:info-circle"}
Setting purpose appropriately based on if model is image-only or multimodal impacts how Msty handles the image generation request. If you encounter an error, double check the Model's purpose is configured correctly.
::

#### Image-only models

It is very important that if the model is an image-model only, meaning the model doesn't have multimodal functionality, then ensure that **only** image is selected.

![image generation only models](/images/img-gen/image-only-model.png)

#### Multimodal models

Likewise, if the model has multimodal functionality, then ensure that more than just image is selected as a purpose. Such as, most multimodal models that support images are also likely to support text.

![multimodals](/images/img-gen/add-purpose-to-existing-model.png)

## Advanced configurations

Not all models support advanced configurations - such as, these configurations may likely work for OpenAI models but may not work for Gemini.

Advanced configurations can be included as model parameters.

![model params](/images/img-gen/model-params.png)

### Aspect Ratio

`size : 1536x1024`

### Number of images generated

`n: 2`

::Resources


---

Workspaces in Msty Studio help keep your projects organized by allowing you to create multiple, separate work areas. Each workspace can have its own unique settings, including models, conversations, toolsets, and prompts.

## Add New Workspaces

When you start Msty Studio for the first time, a default Workspace is created for you.

You can create additional workspaces to organize your work. Each workspace can have its own set of conversations, toolsets, prompts, and other settings.

![Add new workspaces](/images/new-workspace.png)

::steps

1. Beneath the Msty logo and the default Workspace icon, select the **+** symbol to create a new **Workspace**
2. Enter a unique **Workspace Name**
3. Select any setting(s) you'd like to copy from the current Workspace you are in to the new Workspace
4. Select **Create and Switch** to create the new Workspace and automatically switch to it

::

## Export And Import Workspaces

You can export a Workspace by right clicking on the Workspace icon and select the **Export Workspace** option. This will create a Zip file that you can save to your local machine.

Likewise, you can import a Workspace by selecting the **+** symbol and then select the **Import Workspace** option. This will allow you to select a Zip file from your local machine to import into Msty Studio.

::Resources


---

Wondering what the advanced settings are and how to use them? We've outlined the most common advanced settings in our [The AI Settings Dictionary](https://msty.ai/blog/the-ai-settings-dictionary) blog post. Please check out this article for the most common settings - in which Msty offers quick configs for these common settings.

This document will cover the **even more advanced** settings that are not included in the dictionary. These settings you'd typically add as json to the **Advanced Parameter** or **Provider Options** sections of the Model Parameters section.

Please note that these settings are _generally_ available across models; however, a model may not support all (or any) of these. If you try to add them to a model that doesn't support them, they will be ignored or an error may be thrown. Please check the documentation for the model provider you are using for their available settings.


## Thinking Effort

See the [Thinking Effort](/features/thinking-effort) docs for more information on how to use the thinking effort feature.


## Advanced Runtime Configurations

```json
{
  "runtimeConfig": {
    "priority": "standard", // Options: "low", "standard", "high"
    "timeout": 60000, // Request timeout in milliseconds
    "maxRetries": 3, // Maximum retry attempts
    "stream": true, // Enable streaming responses
    "streamChunkSize": 16, // Number of tokens per streaming chunk
    "streamLatency": "low", // Options: "low", "balanced", "consistent"
    "caching": {
      "enabled": true, // Enable response caching
      "ttl": 3600 // Cache time-to-live in seconds
    },
    "quotaManagement": {
      "tokensPerMinute": 10000, // Rate limit for tokens
      "requestsPerDay": 1000 // Daily request limit
    },
    "logging": {
      "level": "info", // Options: "debug", "info", "warn", "error"
      "includePrompts": false, // Include prompts in logs
      "includeResponses": false // Include responses in logs
    }
  }
}
```

## Memory and Context Configurations

```json
{
  "contextConfig": {
    "maxTokens": 128000, // Maximum context window size
    "retentionStrategy": "recency", // Options: "recency", "importance", "hybrid"
    "compressionRatio": 0.8, // Context compression ratio (0.0-1.0)
    "memoryOptimization": "auto", // Options: "auto", "aggressive", "conservative"
    "contextPrioritization": [
      // Priority order for context management
      "user_instructions",
      "recent_exchanges",
      "relevant_facts",
      "system_instructions"
    ]
  }
}
```

## Multimodal Configurations

```json
{
  "multimodalConfig": {
    "visionEnabled": true, // Enable vision capabilities
    "imageAnalysisDetail": "high", // Options: "low", "medium", "high"
    "imageGenerationEnabled": false, // Enable image generation
    "audioProcessingEnabled": false, // Enable audio processing
    "videoAnalysisEnabled": false, // Enable video analysis
    "modalityPreference": "balanced" // Options: "text", "visual", "balanced"
  }
}
```

## Output Formatting Configurations

```json
{
  "outputConfig": {
    "responseFormat": "markdown", // Options: "markdown", "plain", "json", "xml", "html"
    "verbosityLevel": "concise", // Options: "minimal", "concise", "detailed", "comprehensive"
    "structurePreference": "narrative", // Options: "narrative", "analytical", "bullet", "dialog"
    "citationStyle": "academic", // Options: "none", "informal", "academic", "legal"
    "languageModel": "formal", // Options: "casual", "formal", "technical", "creative"
    "maxOutputTokens": 4096 // Maximum response length
  }
}
```

## Safety and Guardrail Configurations

```json
{
  "safetyConfig": {
    "contentFilters": {
      "harmfulContent": "strict", // Options: "off", "standard", "strict"
      "hateContent": "standard", // Options: "off", "standard", "strict"
      "sexualContent": "standard", // Options: "off", "standard", "strict"
      "violenceContent": "standard" // Options: "off", "standard", "strict"
    },
    "topicRestrictions": ["weapons", "illegal_activities"],
    "refusalBehavior": "explain", // Options: "explain", "redirect", "minimal"
    "userVerification": false, // Enable user verification for sensitive requests
    "contentWarnings": true // Show content warnings when appropriate
  }
}
```

## Sampling Configurations

```json
{
  "samplingConfig": {
    "temperature": 0.7, // Controls randomness (0.0-1.0)
    "top_p": 0.9, // Nucleus sampling parameter (0.0-1.0)
    "top_k": 40, // Limits vocabulary to top K tokens
    "frequencyPenalty": 0.5, // Penalizes repetition (0.0-2.0)
    "presencePenalty": 0.5, // Penalizes token reuse (0.0-2.0)
    "deterministicSampling": false, // Forces deterministic outputs
    "seed": 123456 // Random seed for reproducibility
  }
}
```

## System Behavior Configurations

```json
{
  "behaviorConfig": {
    "personality": "helpful", // Options: "helpful", "concise", "creative", "analytical"
    "roleplayMode": false, // Enable character roleplay capabilities
    "expertiseDomains": ["coding", "science", "math"],
    "conversationalStyle": "balanced", // Options: "formal", "casual", "balanced", "technical"
    "initiativeLevel": "responsive", // Options: "passive", "responsive", "proactive"
    "opinionExpression": "neutral", // Options: "neutral", "balanced", "opinionated"
    "uncertaintyHandling": "transparent" // Options: "confident", "transparent", "conservative"
  }
}
```

## Thinking and Reasoning Configurations

```json
{
  "thinkingConfig": {
    "thinkingBudget": 0, // Disable thinking mode (0) or set custom budget (positive integer)
    "thinkingDepth": "deep", // Options: "shallow", "medium", "deep"
    "enableAutoThinking": false, // Auto-enable thinking for complex queries
    "thinkingStrategy": "structured", // Options: "structured", "exploratory", "critical"
    "reasoningEffort": "low", // Controls effort spent on reasoning
    "microstat": true // Enable fine-grained statistical reasoning
  }
}
```

## Tool Use and Integration Configurations

```json
{
  "toolConfig": {
    "enabledTools": ["calculator", "web_search", "code_execution"],
    "toolCallThreshold": 0.7, // Confidence threshold for tool calling (0.0-1.0)
    "maxToolCalls": 5, // Maximum number of tool calls per request
    "autoToolSelection": true, // Automatically select appropriate tools
    "toolPreferences": {
      "preferred": ["calculator"], // Tools to prioritize
      "fallback": ["web_search"] // Tools to use as fallback
    }
  }
}
```

::Resources


---

Many reasoning models allow you to adjust the thinking effort of the model. This feature allows you to control how much time and effort the model spends reasoning about a response before generating it.

Please note that not all models support reasoning and that model providers may have different configurations for thinking effort. The "thinking" text may also not be returned for all models as well. 

## Set Model Purpose with Reasoning
In order to adjust reasoning and thinking effort, you must first enable **Thinking** as a model's purpose. This is done by editing a model from the model selection dropdown list, then selecting the edit icon, and then enabling **Thinking**. 

![model purpose](/images/thinking-effort/thinking-purpose.png)

## Set Thinking Effort
Once Thinking is enabled, you can set the thinking effort for the model. This can be done by selecting the **Thinking Effort** dropdown in the model settings.

![thinking effort parameter](/images/thinking-effort/thinking-parameter.png)

## Providers
Providers may support different thinking effort configurations. The following providers are known to support thinking effort. However, not all models within these providers support thinking effort configurations. Please check the provider and their model documentation for more details. You will likely see an error message returned when chatting if you try to set thinking effort on a model that does not support it.

### Key
Use the following key to understand the thinking effort support for each provider below. 

- **None**: no thinking effort is applied, model will respond immediately without any reasoning
- **Default**: the default thinking effort configuration determined by the provider
- **Think Lightly**: a light reasoning effort, model will take a short time to respond with minimal reasoning
- **Think Moderately**: a moderate reasoning effort, model will take a longer time to respond with some reasoning
- **Think Deeply**: a deep reasoning effort, model will take the longest time to respond with extensive reasoning
- **Dynamic**: the model will dynamically adjust the thinking effort based on the complexity
- **Exclude**: the model performs its default reasoning effort, but does not return the reasoning text

### Ollama / Msty Models
Supports: 
- None
- Default

### OpenAI Compatible Models
Supports: 
- None
- Default

### OpenAI / ChatGPT
Supports: 
- Default
- Think Lightly
- Think Moderately
- Think Deeply

### Anthropic / Claude
Supports: 
- None
- Default
- Think Lightly
- Think Moderately
- Think Deeply

### Google Generative AI / Gemini
Supports: 
- None 
- Default
- Think Lightly
- Think Moderately
- Think Deeply
- Dynamic

::alert{type="info" icon="tabler:info-circle"}
Gemini 2.5 Pro does not allow for thinking to be disabled
::

### xAI
Supports: 
- None
- Default
- Think Lightly
- Think Moderately
- Think Deeply

### OpenRouter
Supports: 
- None
- Default
- Think Lightly
- Think Moderately
- Think Deeply
- Exclude

### Mistral AI
Supports: 
- None
- Default
- Think Lightly
- Think Moderately
- Think Deeply

### Perplexity
Supports: 
- None
- Default
- Think Lightly
- Think Moderately
- Think Deeply

### Groq
Supports: 
- None
- Default
- Think Lightly
- Think Moderately
- Think Deeply

### Cohere
Supports: 
- None
- Default
- Think Lightly
- Think Moderately
- Think Deeply

### Azure OpenAI
Supports: 
- Default
- Think Lightly
- Think Moderately
- Think Deeply

### DeepSeek
Supports: 
- None
- Default
- Think Lightly
- Think Moderately
- Think Deeply

::Resources

---

Msty Studio saves data locally on your browser. This means that if you clear your browser cache or browser data, you will lose your Msty data. To mitigate this, we recommend regularly backing up your data and restoring it when needed.

## Backup Data

Msty will prompt you periodically to back up your data. You can also manually back up your data by clicking the **Export Data** button in the **Settings** section.

![restore data](/images/data-backup.png)

You can configure the interval for Msty to remind you to back up your data.

Backing up, or exporting, your data will create a zip file containing all of your data that you can save to your computer.

## Restore Data

To restore your data, drag and drop the zip file into the Restore Data section and click on **Restore Data**.

We highly recommend that you back up your data before restoring, if possible. Restoring data will replace all existing data.

## Clear Data

If you want to clear all of your data, you can do so by clicking the **Clear Data** button in the **Settings** section. This will delete all of your data and cannot be undone.

We highly recommend that you back up your data before clearing it.

::Resources


---

Lock your workspace with a passphrase so sensitive settings and API keys stay hidden until you unlock. 

::alert{type="info" icon="tabler:info-circle"}
**IMPORTANT!** Locking Workspace is an experimental feature. Also, keep your passphrase in a secured location where you can access it. If you forget your passphrase, there is no way to recover it nor is there a way to recover the workspace. 
::

## Lock and Encrypt 

In **Settings > General**, locate the **Workspace Lock & Secrets Encryption** section. 

Select the ellipsis (...) icon and then select **Enable Protection**. 

This will display a modal where you'll enter and confirm a passphrase. 

**Important** store your passphrase in a secure location where you can access it again if needed. **There is no way to recover a passphrase and your Workspace cannot be recovered nor restored if you lose or forget it.**

## Workspace Lock Details

- Workspaces lock after every session
- You will not be able to use Msty Studio until you unlock your Workspace 
- Locks are per Workspace, it is not global across all Workspace; however, if you are on a locked Workspace, you cannot navigate to another Workspace until your current Workspace is unlocked
- Rotate the passphrase manually anytime
- Turn protection off if you change your mind
- Creating a new Workspace and copying settings will include Workspace locks if enabled for the current Workspace - passphrase for new Workspace will be same
- Importing a locked Workspace will require you to unlock the Workspace after import



::Resources

---

Insights provides detailed analytics on token usage patterns, helping you understand consumption habits across different models. You can also view cost estimates and usage breakdowns by specific models, enabling more informed decision-making about AI tool usage.

::alert{type="info" icon="tabler:info-circle"}
Costs and token usage are estimations only. Please refer your model provider account for accurate token usage and costs.
::

## Summary :aurum-tag

![token and cost summary](/images/tokens-costs.png)

The **Summary** tab provides an overview of token usage and cost estimates. You can even filter by date range to see how usage has changed over time - including a temperature map visualization of day-by-day usage.

## Provider :aurum-tag

![provider model insights](/images/provider-insights.png)

The **Provider** tab provides more detailed insights into token usage by Provider. You can further break down usage by individual models, allowing you to identify which models are consuming the most tokens. This helps in optimizing costs and understanding model-specific usage patterns.

Also provided are graphs displaying model throughput and latency, which can help you identify any performance issues or bottlenecks in model usage.

::Resources


---

You can enhance your Msty Studio experience by enabling different modes. Each mode is designed to optimize the interaction with Studio and the model so that you can focus on the task at hand.

You can enable modes from **Settings > General > Mode**.

![msty modes](/images/msty-modes.png)

## Vapor

Conversations will not be saved by Msty Studio's history and will disappear when you turn it off or navigate away. Think of Vapor-mode conversations as a fleeting interaction. It exists only for the duration of your current exchange.

::alert{type="info" icon="tabler:info-circle"}
Note that if you use a cloud model, then you are still sending data to the model provider.
::

## Focus

Focus Mode strips away unnecessary elements like the sidebar menu, workspaces, and directory listings to help you concentrate solely on your current task.

## Zen

Zen Mode takes Focus Mode a step further by removing the chat input box, allowing you to immerse yourself in the conversation without distractions. This mode is ideal for deep work or when you want to engage with the model without interruptions.

::Resources


---

## How to Use Keyboard Shortcuts
In Msty Studio, you can customize shortcuts for various actions so that you can perform them quickly without needing to navigate through menus. This is particularly useful for power users who want to streamline their workflow.

You can access the keyboard shortcuts settings in **Settings > Keyboard Shortcuts**. Here, you can view the current shortcuts and customize them to suit your preferences. You can also reset them to their default values if needed.

![keyboard shortcuts](/images/shortcuts/keyboard-shortcuts.png)

Some actions have a default shortcut assigned, which you can use that shortcut or customize to your liking.

## Spell Check Toggle (Desktop)

For Desktop users, Msty Studio provides an option to disable the built-in spell check feature. This is particularly useful for developers writing code or for users whose language isn't supported well by the spell checker. When disabled, the red underlines for unrecognized words will no longer appear.

### How to Toggle Spell Check

::steps
### Open General Settings
Go to **Settings > General**.

### Find Spell Check Option
Scroll down to locate the spell check toggle.

### Change and Restart
Switch the spell check setting as desired, then **restart the application** for the changes to take full effect.
::

::alert{type="info" icon="tabler:info-circle"}
Studio Web can disable via the browser settings. For Studio Desktop, please note your OS settings may override this option.
::

## How to Use Shiftcuts

Shiftcuts are a set of keyboard shortcuts that allow you to quickly access common tasks in Msty Studio. By pressing the shift key twice in quick succession, you can activate a mode that enables you to perform various actions without needing to navigate through menus or use the mouse.

To activate Shiftcuts, simply **press the shift key twice quickly**. This will enable the Shiftcut mode, allowing you to use the following shortcuts. **You will then need to press the corresponding key** for the action you want to perform before the mode times out. When you double click the shift key, you will see a yellow up icon that displays - you'll have until this icon disappears to press the corresponding key for the action you want to perform.

Press the following keys to perform the corresponding actions:

### **t** - Create a new split chat tab

This will open a new split chat tab, allowing you to have multiple conversations open at once. You can use this feature to compare responses from different models or to keep track of multiple discussions simultaneously.
![shiftcut split chat](/images/shiftcuts/shiftcut-split.png)

### **n** - Create a new conversation

This will create a new conversation in the current tab, allowing you to start fresh without losing your previous discussions.
![shiftcut new convo](/images/shiftcuts/shiftcut-new.gif)

### **1** - Toggle sidebar

This will toggle the visibility of the sidebar, allowing you to maximize your workspace or access the sidebar features as needed.
![shiftcut toggle sidebar](/images/shiftcuts/shiftcut-toggle.gif)

### **e** - Show Quick Select Environment Variable picker

This will open a picker that allows you to quickly select an [environment variable](/features/environments). This is useful for inserting variables into your conversations or for quickly accessing specific information.
![shiftcut env picker](/images/shiftcuts/shiftcut-env.png)

## How to Disable ShiftCuts

::steps
### Open Keyboard Shortcuts Settings
Navigate to **Settings > Keyboard Shortcuts**.

### Toggle the Feature Off
At the top of the keyboard shortcuts page, you'll find a switch to enable or disable the Shift Cut feature. Turn it off to deactivate the shortcut completely.
::

::Resources


---

Create and organize prompts for easy access and reuse across Msty.

![Prompts Library](/images/prompts-library.png)

## Import Default Prompts

To quickly get started, you can import a collection of ready-to-use prompts:

1. Select the **down arrow** next to the **New Prompt** button.
2. Choose **Import Default Prompts**.

This will load a curated set of prompts that you can edit and customize to fit your workflow.

## Add a New Prompt

To create your own prompt:

1. Click **New Prompt**.
2. Enter a **Title** and your **Prompt text**.

Alternatively, click the **down arrow** next to **New Prompt** to:

- Import prompts from your clipboard.
- Upload a JSON file with one or more prompts.

## Organize Your Prompts

Keep your prompt library tidy by using folders:

- Use the **down arrow** next to **New Prompt** or the **ellipsis (⋯)** icon beside existing folders to create:

  - New root-level folders
  - Subfolders (child folders)

You can then move prompts into these folders for better organization and faster access.

::Resources


---

## Getting Started with Remote Connections :aurum-tag

Msty Studio Web lets you access many of the same powerful features available in the Desktop version, all from your browser.  

However, certain capabilities require access to a local environment, something the web version cannot do directly due to the inherent constraints of pure web applications.

To bridge this gap, Msty Studio Desktop can act as a **secure proxy**, enabling the web version to connect to your local resources.  

**These capabilities include:**
- **Accessing Local AI Models** — Run high-performance models stored and executed on your own machine.  
- **Web Search with Real-Time Data** — Enhance responses with live search capabilities that pull up-to-the-minute results.  
- **Toolbox MCP Tools** — Use locally installed MCP tools directly from the web version.  

::alert{type="info" icon="tabler:info-circle"}
Remote connections do not share data between the web and desktop versions. 
::

### How Remote Connections Work
When enabled, the Msty Studio Desktop application provides a secure, authenticated tunnel between the web version and your local machine.  
This allows you to use tools, models, and real-time data that are otherwise inaccessible via the browser alone.

### Step 1 - Allow External Connections to Local AI Service

In **Settings > Local AI**: 
1. Enable options to **Enable Network Access** and **Allow Access from Msty Studio** 
2. Add `https://msty.studio` to **https://msty.studio**
3. Save updated settings

### Step 2 — Configure the Remote Tools Connector
The Remote Tools Connector defines the communication details between Msty Studio Web and your local Desktop instance.  

You’ll set:
- **Connection Token** — A secure token to authorize access.  
- **Enable Tunneling** - Allows remote connections to be established. Leave disabled if you are connecting web to desktop locally on the same device.

### Step 3 — Enable Remote Connections
Once the connector is configured, select the button to **Enable** remote connections. 

You'll then be provided with a local and tunnel URL (if you enabled tunneling). 

![Remote Tools Connector URLs](/images/remote-tools-connector/connection-urls.png)

Copy the url that corresponds to your desired connection method (local or tunnel).

### Step 4 — Add Connection URL in Studio Web

Once your **Remote Tools Connector** is set up on your desktop, the next step is to tell **Msty Studio Web** where to connect.  

You’ll do this by adding the **Connection URL** in the Studio Web settings.

#### Accessing Local Models
If you want Studio Web to run **local AI models** through your desktop (instead of only cloud models), go to **Model Hub > Add New Provider** and select **Msty Remote**. 

Paste the Connection URL you copied from earlier into the appropriate field.  

![Remote Tools Connector URLs](/images/remote-tools-connector/connect-to-models.png)  

This allows you to:
- Use your own hardware for inference
- Access models not available in the cloud
- Keep processing and data fully on your machine

#### Accessing Real-Time Data and MCP Tools
If you also want Studio Web to interact with **real-time data sources** or dependencies for **MCP tools** that are available only through your desktop, paste the Connection URL in the Tools Connection field.  

![Remote Tools Connector URLs](/images/remote-tools-connector/connect-to-tools.png)  

With this connection, you can:
- Pull in real-time data using your desktop environment 
- Access local dependencies (Node, python, etc) needed for MCP tools to function


---

The Settings section is where you can configure various aspects of Msty Studio to tailor the experience to your needs.

## General

### Appearance

You can customize the appearance of Msty Studio by modifying the following settings:
* Color preference - Light, Dark, or System Default
* [Mode](/features/modes)
* Font Size
* Font Style
* Code Theme - for code returned by models
* Rendering Modules - enable/disable the following:
    * Markdown - formats markdown content
    * Mermaid Diagrams
    * Math LaTeX
    * GitHub Flavored Markdown
    * Code Highlights
    * Collapsing Tags
    * Enable Links - links returned by models are disabled by default; to make them clickable, enable this setting
* Right-To-Left (RTL) Support - for languages that require right-to-left text direction

### Application Info
* App Version - displays your installed version. You can select the overflow menu to check and install updates as well as enable/disable automatic updates
* App Settings - reset to default
* Data Paths - provides location of app data and app logs
* Help and Discussions - links to these docs and [Discord](https://msty.ai/discord)
* Disable Web Security - enable if your are experiencing CORS related issues; only recommended for specific use cases and you'll need to restart Msty Studio


## Local AI Service
Contains information about the local AI service if you have this installed. 

* Models Path - file path to where models are stored
* Service Health - displays current status with options to stop, start, and restart
* Service Endpoint - endpoint if you'd like to connect other applications to the local AI service
* Service Version - displays current version with options to check for updates, remove service, or [install from archive](/getting-started/onboarding#install-local-ai-from-archive-file)
* Manage Local AI Models - links to Model Hub > Local AI Models
* Service Configurations
    * Configure port number
    * Maximum Parallel Chats
    * Maximum Loaded Models
    * Enable Network Access - allow other devices on local network to connect
    * Allow Access from Msty Studio Web - enable to allow Msty Studio Web to connect and use local AI services
    * Allowed Network Origins - manage permitted external origins
    * Capture Service Logs - enable local AI services logging
    * Advanced Configurations - set local environment variables; in JSON format
* Model Configurations
    * Model Keep-Alive Timeout
    * Advanced Configurations - enter valid JSON to pass additional parameters to models during chat sessions



## MLX Service

MLX is availble for Apple Silicon devices only. 

* Model Path - file path to where models are stored
* Service Health - displays current status with options to stop, start, and restart
* Service Endpoint - endpoint if you'd like to connect other applications to the local AI service
* Service Version - displays current version with options to check for updates and remove service
* Manage MLX AI Models - links to Model Hub > MLX AI Models
* Service Configurations
    * Enable Network Access - allow other devices on local network to connect
    * Capture Service Logs - enable local AI services logging

## Vibe CLI Proxy

Vibe CLI Proxy allows Msty Studio to connect to various CLI providers through a secure local proxy.

* Service Health - displays current status with options to stop, start and restart
* Service Endpoint - endpoint if you'd like to connect other applications to the vibe CLI proxy
* Service Version - displays current version with options to check for updates and remove service
* Service Configurations
    * Enable Network Access - allow other devices on the network to reach the proxy
    * Capture Service Logs - persist proxy logs for troubleshooting (may increase disk usage)
    * Port - the local port where the proxy service listens for requests
    * Retries - number of retry attempts for failed upstream requests
    * Auth Folder - path where Vibe CLI Proxy stores OAuth tokens for connected providers. Managed automatically; not editable
    * Authentication - securely link your AI accounts so Vibe CLI Proxy can call their APIs on your behalf. When you connect, a browser window opens for that provider where you complete sign-in, setup, and authorize [Vibe CLI Proxy providers](/features/vibe-cli-proxy)



## Remote Service

See [Remote Connections](/features/remote-connections) for more information.

## Data
See [Data Backups and Restoration](/features/data-backups) and [Data Migration](/getting-started/quick-start#data-migration-for-msty-app-users) for more information.

## Keyboard Shortcuts
See [Keyboard Shortcuts](/features/keyboard-shortcuts) for more information.

## Log Viewer (Desktop Only)
You can view application logs to help troubleshoot issues. You can filter by log level, search for specific terms, and copy log entries.

You can even enable live logging to see log entries in real-time as they occur.

## Notifications
The Notifications section is an additional way to view alerts to help with troubleshooting issues. This section lists key app events, typically related to errors toasts you may have seen. 

## License and Access
Enter your License to unlock advanced features. 


---

Several features in Msty Studio have prompts that tell a model how to respond; outside of just the conversation-related prompts. 

Default prompts are located in the Settings > Default Prompts section. 

## Default Prompts

The Default Prompts section contains prompts for the following features:
- **Context Shield Summary**: used to summarize long context into shorter summaries so that you can save on context length and tokens
- **Knowledge Stack Context**: included when sending chunks from your Knowledge Stack to the model; this will provide instructions on how to use the context
- **Knowledge Stack Simple Search**: this prompt is used to help the model generate search queries to find relevant documents in your Knowledge Stack
- **Knowledge Stack Structured Search**: for a more semantic search, this prompt helps the model generate better search queries for your Knowledge Stack
- **Real-Time Data Query Synthesis**: creates queries to fetch real-time data in a format common to standard search engines
- **Title Generation**: used to generate titles for chats based on the conversation content
- **Youtube Attachments**: provides context to model about how to use YouTube video transcripts when included as attachments in chats

## Editing Default Prompts

To edit a default prompt, select the prompt from the menu and then modify the text in the editor. Once you are done, select the "Save" button to save your changes.

Many of the default prompts include variables, such as `{input}` or `{content}`. These variables will be replaced with the appropriate content when the prompt is used. Be sure to keep these variables in your prompt to ensure proper functionality.

At the bottom of the text editor, there are buttons to fetch a prompt from **Quick Prompts**, to **Clear Content**, and to **Reset to Default**.

::Resources

---

The Lost & Found helps you find orphaned workspaces for both Msty Studio Desktop and Studio Web. 

For privacy and cross-compatibility reasons, Msty Studio Web stores your data locally in an OPFS database [Read our blog post on how this ensures privacy](https://msty.ai/blog/msty-studio-web-opfs){target="_blank"}. Very rarely, your browser may create a new database unexpectedly. When that happens, your previous workspaces may not appear in the app but **Lost & Found** can help you find and recover them easily.

## How to Use Lost & Found to Recover Workspaces

::steps
### Open Lost & Found
Go to **Settings > Data > Lost & Found**.

### Run a Scan

**For Desktop**

Choose one of:
- **Scan App Data** – searches the app’s internal data directory  
- **Scan Folder** – choose any folder; all subfolders are scanned  

**For Web**
- **Scan Folder** – select a folder using the browser’s directory picker or file-input fallback - see below for instructions on finding and scanning browser file system folders

### Review results and take action 
See below for re-importing found workspaces. 
::

### Scanning Browser File System Data for Msty Studio Web

The **Lost & Found** feature cannot scan your browser’s original `File System` folder directly because it resides in a protected system location. Follow these steps to create a copy of the `File System` folder in an accessible location for scanning:

::steps
1. Find the directory on your computer where your browser stores its `File System` data. Search the web for your specific browser and OS to see where the file system folder is located. 
2. Locate the `File System` folder.
3. Copy the entire folder and paste it somewhere simple and accessible such as your **Desktop** or **Documents**.  
   *Avoid leaving it in protected locations like the system root (`C:\`).*
4. In **Lost & Found**, choose **Scan Folder** and select the copied `File System` folder in its new location.
::


## Scan Results Table

Lost & Found scans specific locations for workspace-like SQLite databases and displays them in a table. For each detected workspace file, it shows:

- **Workspace name**  
- **File name, size, and last modified time**  
- **Status:**  
  - **Current** – matches the currently active workspace  
  - **Linked** – matches an existing workspace in your list  
  - **Found** – not currently in your workspace list  
- **Actions:**
  - **Restore current workspace** (Current only)  
  - **Import as new workspace** (all statuses)

::alert{type="info" icon="tabler:info-circle"}
Only actual Msty Studio workspace databases are shown. The feature never reads files outside the app’s storage or outside folders explicitly selected by the user.
::

## Recover a Workspace

### Restore Current Workspace:

::steps
1. Find a row labeled **Current**  
2. Open the **Actions** menu  
3. Select **Restore current workspace**  
4. Confirm the warning dialog
::
The active workspace is then replaced with the recovered data successfully.

### Import as New Workspace

::steps
1. Open the **Actions** menu
2. Select **Import as new workspace** and a new workspace will be created with the recovered data.
::

::Resources

---

Integrate models from supported CLI applications directly into Msty Studio. This integration supports multiple CLI providers and makes their models available for conversations.

### Supported CLI Providers

- Claude Code
- Codex
- Google Gemini
- iFlow
- Github Copilot
- Antigravity

## Link CLI Provider

::steps
### Open CLI Settings
Go to **Settings > Vibe CLI Proxy**.

### Authorize
Under Authentication, select your provider and click **Authorize**.

### Complete Flow
When you connect, a browser window opens for the selected provider, allowing you to complete the authorization and sign-in process.

::

## Use CLI Models

::steps
### Select Model
In any conversation, open the model selector.

### Choose Provider
Models from authorized CLI providers will appear in the list. Select one to begin chatting.
::

::alert{type="info" icon="tabler:info-circle"}
CLI models work alongside your other configured models, no extra setup needed after authorization. Enabled CLI providers will also appear in the Model Hub.
::


---

Threads and the mini map include a branch dropdown for better navigation and comparison. The Branch Explorer allows you to label branches and perform side-by-side diff comparisons between different conversation branches.

## Using Branch Explorer in Threads

::steps
### Access Branch Dropdown
In any thread, locate the new branch dropdown menu(Edit as Branch). When you use the feature for a user or assistant message and update the prompt a new branch is created that contains the updated user and assistant message

### Label or Explore
Use the dropdown to **label a branch** or open **Branch Explorer**.

### Compare Branches
Branch Explorer displays a side-by-side diff view, letting you compare content between two selected branches.
::

## Using Branch Explorer in Mini Map

::steps
### Open Mini Map
Access the mini map interface.

### Select Branch
Use the branch dropdown to select a different branch.

### View Updates
The mini map will update to reflect the selected branch, allowing for quick navigation and comparison.
::

::Resources

---

The Toolbox allows for seamless communication with tools installed on your local machine or a remote one. These tools can interact with various data sources, perform file operations, and connect to repositories like GitHub, further empowering Msty Studio.

This is Msty Studio's implementation of Model Context Protocol (MCP).

Msty Studio supports local MCP server that run on your machine as well as remote MCP servers that can be connect to over Streamable HTTP. 

::alert{type="warning" icon="tabler:info-circle"}
Please note the SSE protocol has been deprecated in favor of Streamable HTTP for remote MCP server connections. Studio's implementation came after the deprecation, and as such, SSE is not supported. However, you can use a local proxy such as mcp-remote to connect to SSE-based MCP servers if needed.
::

To utilize the Toolbox features with Msty Studio Web, you must have Studio Web connected to Studio Desktop using [Remote Connections](/features/remote-connections) or [Sidecar](/how-tos/sidecar).

![Msty Studio Tools](/images/tools.png)

## Import Default Tools

::alert{type="info" icon="tabler:info-circle"}
Please note that default tools as well as any tool you add are not created, tested, nor maintained by Msty. We are merely providing a platform to use these and allowing to import them as a convenience. **PLEASE USE THEM AT YOUR OWN RISK**. Msty is not responsible for any issues that may arise from using these tools. Also, for support, please reach out to the tool's author.
::

To get started, you can select the option to **Import Default Tools**. Please keep in mind these tools are not created nor maintained by Msty team and are meant to provide a starting point.

## Add A New Tool

Select **Add New Tool** to add a new tool to your toolbox. This will open a new window where you can define the tool's name, configuration, and notes.

::steps

1. Select **HTTP** for remote MCP servers setup for streamable HTTP and tools or **STDIO / JSON** for local MCP servers and tools.
2. If HTTP is selected, enter the **MCP Server URL** endpoint. Also, enter any **Authentication** and **Headers** needed to connect to the MCP server.
3. If STDIO / JSON is selected, enter the **Tool Configuration** in JSON format.

The configuration should be a valid JSON object. Here is an example configuration for a MYSQL tool.

```
{
  "command":"uv",
  "args": [
    "--directory",
    "{dbPath:Database Path:/path/to/database.db}",
    "run","mysql_mcp_server"
  ],
  "env":{
    "MYSQL_HOST":"{Database Host}",
    "MYSQL_PORT":"{Database Port}",
    "MYSQL_USER":"{Database User}",
    "MYSQL_PASS":"{Database Password}",
    "MYSQL_DB":"{Database Name}"
  }
}
```

Take note of the **command**, which identifies dependency programs such as Python, UV, Node, and NPX for examples. These programs must be installed on your local machine in order for the tool to run.

If using the above example, then also take note of the variables in the mustache brackets. These are the variables that will be passed to the tool when it is ran. You can use these variables in your tool configuration to make it more dynamic. You will be able to define variables in the following steps.

3. Optionally, enter **Notes** to help you remember the purpose of the tool and any other information you may need to remember
4. Give the tool a unique **Name**
5. Select **Add** to add the tool to your toolbox

::

## Set Tool's Default Parameters

To set default parameters for a tool, select the asterisk (**\***) icon next to the tool name. This will open a window where you can define the tool's parameters.

Here, you can add **Custom Arguments** and set **Environment Variables** that may be needed for the tool to run, such as directory paths, endpoints, API keys, and so on.

There is also a **Tool Console** where you can test the tool with different parameters.

## Install Dependencies

Most tools will require dependencies - such as Node, NPX, and Python - to be installed on your local machine in order to properly run.

For Node installations - at this time, we recommend installing using Volta to manage installing Node and NPX. Mac users may use Homebrew. We do not recommend using NVM. If using NVM, you may need to uninstall and use Volta instead.

To check which package manager you used to install Node, run the following command in your terminal and take note of the directory path.

```
which node
```

If installed under NVM directory, then you'll likely need reinstall using a recommended package manager.

::alert{type="info" icon="tabler:info-circle"}
If you are running into issues with dependencies not showing as available, click on Sidecar and then select **View Logs** to see if there are any helpful error messages.
::

::Resources


---

Toolsets are a collection of tools with defined parameters. You can create a toolset and add tools to it. When chatting with a model, you can select one or multiple toolsets to use with the model.

## Add New Toolset and Congiure Tools

![Add new toolsets](/images/toolsets.png)

::steps

1. Select **Add New Toolset** to add a new toolset
2. Enable the tools you want to include in the Toolset
3. Select the asterisk (**\***) icon next to the tool to define the [parameters](/features/toolbox/tools#set-tools-default-parameters) the tool should use with this Toolset
4. Add any **Notes** to help you remember the purpose of the toolset and any other information you may need to remember
5. Give the toolset a unique **Name**
6. Select **Add** to add the toolset to your toolbox

::

## Using a Toolset in a Conversation

You can enable a Toolset in a conversation by selecting the Toolset icon and then selecting which Toolset(s) you'd like to enable.

When applying a Toolset, you'll also want to ensure that the selected model supports the usage of the Toolsets you are planning to use.

By default, all models have **Tools** disabled as a 'purpose' and you'll want to test the model with the Toolset to ensure compatibility. If the model is compatible with the Toolsets, then in the Conversation toolbar, select the model dropdown, and then select the edit icon next to the model. A window will display where you can enable **Tools** as a 'purpose' for the model. This will then remove the warning message that you may have noticed from the Conversation toolbar when adding the Toolset.
![set models' purpose](/images/tools-model-purpose.png)

::Resources


---

Live Contexts are external data sources that you can add to your conversation in the form of calling an API. This allows you to bring in information from various sources and services to provide more context and enhance the interaction with models.

Live Contexts can either use a simple GET request to fetch data from an endpoint. Or, it can be more **dynamic** by allowing the model to determine variables and parameters to include in the API call, allowing for more flexibility and adaptability based on the conversation.

## Add New Live Context

Connect to your favorite APIs to enhance your conversations. You'll first want to identify an API you'd like to use and gather necessary information to connect to it, such as an API key.

Check out the [Live Context Examples](/how-tos/live-context-examples) for some inspiration on APIs you can connect to.

![add live context](/images/live-context.png)

::steps

1. From the **Toolbox** section, select **Live Contexts**
2. Click on the **Add New Live Context** button
3. Select an **HTTP Method** (GET or POST)
4. Enter the **URL Endpoint** for the API you want to connect to. You can include variables in curly braces, such as `{query:'keyword'}`, which the model can fill in dynamically
5. Adjust the **Prompt** if needed; you can still add prompts at the point of messaging
6. Include any **Request Headers** needed for the API call, such as an Authorization header - you can also include variables here for the model to fill in
7. Set **Live Context Mode** - by default, it is set to 'Push' which will send the Live Context data to the model automatically when included in a conversation. You can also set it to 'Pull' which will allow the model to decide when to call the Live Context during the conversation. Use the Pull mode option when using dynamic variables in the endpoint or headers that the model needs to fill in.
8. Include any **Request Body** needed for the API call, such as a JSON body - you can also include variables here for the model to fill in
9. Include any **Processing Function** needed to process the API response. The default is to return the response as a string which for most cases you can leave as-is

   `return JSON.stringify(data)`

10. Test the endpoint by selelecting **Test Connection** and you can include test variables if needed
11. Include any helpful **Notes** which is also visible to the models, which can help guide their use of the Live Context
12. Provide a unique **Name** for the Live Context
13. Select **Add** to save the Live Context

::

## Using Live Contexts

Once you have created a Live Context, you can use it in your conversations by clicking on the **Toolset** icon and then select the **Live Contexts** you'd like to include in the conversation. You can even add multiple Live Contexts to a conversation.

![live context in chat](/images/live-contexts-convo.png)

## Example endpoints

Check out the [list of example endpoints](/how-tos/live-context-examples) for example endpoints you can play with.

::Resources


---

Tools run where the Sidecar is running and each tool has its own dependencies such as `npx`, `node`, `python`, `uv`
etc.

There are so many ways to install these dependencies on your machine and it's not possible to cover all of them so we
recommend the following approach.

::alert{type="warning" icon="tabler:info-circle"}
You may find that some dependencies installed via a certain package manager, such as `nvm`, are not compatible with the
tool you are using.
::

## Recommended Approach

For `npx` and `node`, we recommend using [Volta](https://volta.sh/) to install and manage your dependencies. It's a
cross-platform
tool that works on Windows, Mac, and Linux. macOS users can use [Homebrew](https://brew.sh/) to install dependencies as
well.

For `python` and `uv` on Windows, we recommend using [WinGet](https://winget.run/) to install and manage your
dependencies.
Based on your platform, you might have to set full paths to your dependencies in Sidecar connection dialog.

For `uv` on Mac, you can install via Homebrew `brew install uv`. This will automatically include `uvx`.

## Configuring Python and uv/uvx on Windows

1. Install [WinGet](https://learn.microsoft.com/en-us/windows/package-manager/winget/) on your Windows machine.
2. Open a terminal and run the following commands to install Python and uv:
   ```bash
   winget install -e --id Python.Python.3.12 --scope machine
   winget install --id=astral-sh.uv  -e
   ```
3. Open the Sidecar connection dialog and set the full path to your Python installation. You don't need to set the full path
   to `uv` as it will be detected automatically.

![Tool Dependencies Paths Setup](/images/tool-deps-config-windows.png)

4. Once connected, you can create a new tool and use tool console to list the features of this tool. If you see the
   features, it means the tool is working correctly. You can use the following as an example tool:
   ```json
   {
     "command": "uvx",
     "args": ["mcp-request"]
   }
   ```

::alert{type="warning" icon="tabler:info-circle"}
When using a tool for the first time, it could take a few minutes for it to download and install additional dependencies. This depends on the tool you are using and is outside of Msty's control.
We recommend keeping an eye on Sidecar logs to see if there are any errors or issues with the tool.
::

![Tool Console Output](/images/tool-console-output.png)

::Resources


---

Knowledge Stacks are Msty Studio’s take on Retrieval-Augmented Generation (RAG), designed to help you create, manage, and use collections of knowledge in a structured, flexible way. They let you organize your data for easy access in conversations, proving models with deep, domain-specific understanding.
::alert{type="info" icon="tabler:info-circle"}
Knowledge Stacks are currently available in Msty Studio Desktop only
::

## Key Features of Knowledge Stacks

A few of the key features that make Msty's Knowledge Stacks stand out include:
- **Flexible Embedding**: You can select and embed using a local embedding model of your choice, allowing you to tailor the knowledge stack to your specific needs
- **Chunk Console and Visualizer**: With the visualizer, you can view how your documents are chunked and run example queries using the console, making it easier to understand and utilize your data
- **Advanced Query Settings**: Fine-tune how your knowledge stack responds to queries with customizable settings for relevance, context, and more
- **Synthesized Responses**: Msty can generate responses based on the knowledge in your stack, allowing for more dynamic and context-aware interactions
- **PII (Personal Identifiable Information) Scrubbing**: Msty includes ability for identifying and redacting sensitive information in your knowledge stack

## Creating your First Knowledge Stack

When creating your Knowledge Stack, think of each stack as a category or topic that you want to explore or utilize in your AI applications. You can add various types of content to your stack, such as files, folders, notes, and YouTube links. However, we recommend that you keep your stack focused on a single topic or theme to maximize its effectiveness.

::steps
1. Click the Knowledge Stacks icon and select option to create a new stack
2. Add a **Title** and **Description** for your stack
3. Add **Files**, **Folders**, **Notes**, and/or **YouTube Links** to your stack
4. Configure the **Compose Settings** - view [Compose Options](/features/knowledge-stacks/compose-options) for advanced configuration options
5. **Compose** your Knowledge Stack
::

![create your first knowledge stack](/images/knowledge-stacks/ks-setup-full.png)

Knowledge Stack is a powerful tool for organizing and utilizing your data and AI effectively. Be sure to explore the other features and settings in this section to get the most out of your Knowledge Stacks.

## Using Knowledge Stacks in Conversations

Once you have created and composed your Knowledge Stack, you can use it in your conversations.

::steps
1. Start or open a conversation in Msty Studio
2. Select the **Knowledge Stack** icon in the conversation toolbar
3. Choose the Knowledge Stack you want to use from the list
4. Start chatting with a model
::

![knowledge stacks enabled in chat](/images/knowledge-stacks/select-ks.png)

The model will have access to the knowledge in your selected stack, allowing it to provide more informed and context-aware responses.

![knowledge stacks chat response](/images/knowledge-stacks/sherlock-holmes-response.png)

Check out [Query Settings](/features/knowledge-stacks/query-settings) for advanced query options that will help you improve search results.

## Import Default Knowledge Stacks

Select the down chevron next to **New Knowledge Stack** and then select **Import Default Knowledge Stack**. 

This will load a prebuilt Knowledge Stack containing Msty Studio’s documentation. It’s a great way to explore and test how Knowledge Stacks work without needing to upload your own files. Plus, you’ll have instant access to the full Msty Studio docs directly within your conversations.

::Resources

---

Composing resources initiates the process of preparing your files for retrieval-based AI interactions. When you compose, each resource is parsed and broken down into meaningful chunks, then transformed into vector representations using an embedding model. These vectors are stored in a searchable index, enabling the system to quickly retrieve relevant context during a prompt. 

This step is essential for making your documents usable in Knowledge Stacks and ensuring accurate, context-aware responses from the AI.

You can configure compose settings at the resource level and at the composition process level.

## Resource Compose Advanced Options :aurum-tag

When adding new resources under files, folders, notes, and YouTube links, additional configuration options will be available under the ellipsis menu. 

Configuration capabilities depend on resource upload types. 

### Load Modes

Select how a file will be loaded during Knowledge Stack compositions. For file uploads, there are three options you can choose from. 

![file load modes](/images/knowledge-stacks/load-modes.png)

#### Static Mode
Uses the cached version from when the file was added. Fast and predictable, but doesn't reflect recent changes.

Use this option for source files that are not likely to modified. 

This is the default mode for files added to Knowledge Stacks. 

#### Dynamic Mode
Loads the latest file content on each composition. Slightly slower but always up-to-date.

Use this option if you modify source files, want the latest to be included in new compositions, but you are not concerned about the Knowledge Stack having latest information and are okay with manually re-composing. 

#### Sync Mode
Watches for file changes and automatically recomposes. Best for small, frequently updated files.

Use this option if you want the Knowledge Stack to automatically be re-composed when launching Msty and Msty detects that there is a change to a file that is configured for sync mode. 

After marking a file for sync mode, you will need to **Start Sync Mode** from the Knowledge Stack menu in order to watch for file changes and to automatically re-compose the stack.

![enable file change watch](/images/knowledge-stacks/enable-sync-mode.png)

::alert{type="info" icon="tabler:info-circle"}
Sync Mode can be expensive in terms of your local resources and processing if files update frequently.
::

### Mark for Reprocessing 

Marking a resource for reprocessing will process only those marked resources when clicking **Compose**. 

### Ignore for Retrieval

Select **Ignore for Retrieval** to prevent a resource from being queryable. This is helpful as you perfect your Knowledge Stacks. 

### Lock a Resource

You can either temporarily or permanently lock a resource. 

**Temporarily** locking a resource will exclude the file during re-composing. However, the resource from it's last composition will be included in query results. 

**Permanently** locking a file is irreversible and will lock the composed resource forever - until deletion. 

::alert{type="info" icon="tabler:info-circle"}
Use Permanent Lock only if you know you will never update the source file in the future. 
::


If you import a Knowledge Stack, the resources in that imported stack are by default permanently locked. This is because the source files are assumed to not be on your machine and only the vectorized database for the stack is being imported. 

## Compose Settings

In the **Compose Settings** area, you can configure the how the Knowledge Stack is composed.


![configure compose settings](/images/knowledge-stacks/compose-settings.png)

### Embedding Model

Msty uses [gte-tiny](https://huggingface.co/TaylorAI/gte-tiny){target="_blank"} by default, but you can change it to any other embedding model available in your Msty App. You can find an embedding model in **Model Hub > Local AI Models**.

Some embedding models outperform others by better capturing semantic meaning, understanding context, and generalizing across domains. High-quality models improve retrieval accuracy by generating more meaningful vector representations of text. 

When choosing an embedding model, look for strong retrieval performance, domain relevance, efficiency (in size and speed), and compatibility with your deployment setup.

For an embedding model to display as a selectable option, ensure the model has **Embedding** enabled as a purpose. To check this, select the update model icon from either the model selection list or from the installed local models section in Model Hub. 

![embedding model purpose](/images/knowledge-stacks/embedding-purpose.png)

### Chunking Method

Chunking is the process of breaking down large documents into smaller, manageable pieces (or "chunks") to make them suitable for vectorization and retrieval. Each chunk is typically a few hundred words and is designed to preserve context while fitting within token limits of embedding and language models. Effective chunking ensures that relevant information can be retrieved accurately, improving the quality of responses. 

Choose how you want to split your content into chunks. 

Options include:
  - **Recursive Character**: Splits text into chunks based on character count.
  - **Sentence**: Splits text into chunks based on sentence boundaries.

### Overlapping 
Configure how much overlap you want between chunks.

This configuration is available when Chunking Method is set to Recursive Character. 

### Chunk Size
Set the maximum size for each chunk. Smaller chunks may improve search accuracy but can increase processing time and token usage.

### Chunk Size to Ignore
Specify chunk sizes that should be ignored during processing. Useful for excluding very small or very large chunks that may not be relevant.

## Compose

When you are ready to compose, select the **Compose** button. 

![compose a knowledge stack](/images/knowledge-stacks/compose-ks.png)

If you haven't made any changes to compose configurations, and want to re-compose, select the **Force Compose** option. 

::Resources

---

For more accurate results, use the **Query Settings** to configure how your stacks should be queried during conversations. 

You can setup default Query Settings from the Knowledge Stacks main configuration section. 

The default Query Settings will be used when you select the corresponding stack to be used during a conversation. 

From the Conversation Add-Ons, you can alter the settings for the conversation if needed.

If you select multiple stacks to be available in a conversation, then the default settings for only one of the stacks will be returned. So, it is recommended to validate and configure the query settings to be used for the conversation. 

## Default Query Settings

In the Knowledge Stack configuration, select **Query Settings** to set the defaults for that stack. 

![chunk visualizer](/images/knowledge-stacks/query-settings-default.png)

### Chunk Retrieval Mode

You can set which retrieval mode is used during conversations. 

#### Push Mode
This mode first queries the Knowledge Stack and then sends the results to the model for context.

This is the default mode. 

#### Pull Mode
This mode first allows the model to request context from the Knowledge Stack when it identifies a need, and then retrieves the relevant results to provide to the model.

::alert{type="info" icon="tabler:info-circle"}
Ensure the model is able to perform tool calls if using this mode
::

### Prompt Prefix
As with any interaction with LLMs and SLMs, it's all in the prompt. 

For improved results, add a prompt that helps the model understand what they have access to and what they are expected to do with the provided context. 

### Number of Chunks
Set the max number of chunks that are delivered to the model. 

### Similarity Threshold
Define the similarity threshold. Set higher if you are looking for more exact results and similarities. 

### Search type
Choose how you want to search through your Knowledge Stack when retrieving relevant context.

#### Semantic
Semantic search uses vector embeddings to understand the meaning behind your query and retrieve conceptually similar content, even if exact words don’t match. This is ideal for natural language prompts or when you're looking for ideas, explanations, or loosely related information.

This is the default setting. 

#### Keyword
Keyword search performs a more literal match, scanning for exact terms or phrases present in the query. This method is best for precise lookups, such as searching for specific names, terms, or technical references where wording consistency matters.

#### Hybrid
Hybrid search intelligently combines both semantic and keyword approaches. It allows Msty to interpret your prompt and dynamically choose the best retrieval method to maximize accuracy and relevance. Useful when you're unsure which method fits best or when queries benefit from both meaning and precision. 

### Max Full Content contexts :aurum-tag
By default, RAG systems retrieve and send only the most relevant chunks to the model, which is sufficient for many use cases like answering questions or extracting details. However, this approach falls short for tasks that require full-document understanding, such as summarization, narrative analysis, or comprehensive comparisons where partial context can lead to incomplete or inaccurate results.

Msty’s Knowledge Stacks supports sending the full content when needed. Use this setting to define the maximum number of full files that can be included in the model's context when such depth is required.

::alert{type="info" icon="tabler:info-circle"}
Note: This is disabled by default and should be used selectively based on the task and model token limits. Also, this method is triggered semantically - adjust your prompt if full context is desired but is not being provided.
::

### Synthesize Query :aurum-tag
Synthesizing queries enables the model to generate richer, more dynamic responses by interpreting and combining relevant information from your Knowledge Stack. This leads to more context-aware interactions, especially for tasks that require reasoning, summarization, or multi-part answers.

This is disabled by default. 

### PII Scrubbing :aurum-tag
If you do not want personal identifiable information (PII) to be sent to the model, typically a concern when using online model providers, then enable this setting. 

You will be asked to select a locally installed model that will be tasked with detecting any PII in the Knowledge Stack and to redact the information. 

For best results and for added security, test PII Scrubbing in [Chunks Visualizer](/features/knowledge-stacks/chunks-visualizer) and [Chunks Console](/features/knowledge-stacks/chunks-console) prior to using Knowledge Stacks with online providers where PII is a concern. 

![pii](/images/knowledge-stacks/pii.png)

## Conversation Query Settings

In conversations, the default Query Settings will be used; however, you can alter the settings for the conversation. All of the same settings are available with the exception of the prompt prefix. 

If you are enabling multiple Knowledge Stacks in a conversation, be sure to review the Query Settings to ensure they are appropriate for your intended conversation. 

## Knowledge Stacks Query Results

In the conversation with a model, if Knowledge Stacks are enabled, you can see the results that were provided to the model.

### Knowledge Stacks Metrics
![knowledge stacks results metrics](/images/knowledge-stacks/knowledge-stack-contexts-metrics.png)

The first portion displays high level metrics for the Knowledge Stacks results as well as which settings were used to query the results with. 

#### Query Analysis
![knowledge stacks query analysis](/images/knowledge-stacks/query-analysis.png)
This section provides more details about which specific document resources were returned, if the contexts provided was chunks and/or full contensts, and the search keywords used and how they were weighted. 

#### Returned Chunks and Full Contexts
![knowledge stacks returned results](/images/knowledge-stacks/returned-results.png)
The last section shows the actual chunks and/or full contents that were returned and sent as context to the model. 


::Resources

---

Chunking is the process of breaking down large documents into smaller, manageable pieces (or "chunks") to make them suitable for vectorization and retrieval. Effective chunking ensures that relevant information can be retrieved accurately, improving the quality of responses. 

In Msty Studio’s **Chunk Visualizer**, you're looking to ensure that chunks are **coherent**, **contextually complete**, and **logically separated**; meaning, each chunk should ideally contain a self-contained idea or narrative unit. Good chunks avoid cutting sentences or thoughts in awkward places, which can confuse embedding models and degrade retrieval quality.

::alert{type="info" icon="tabler:info-circle"}
Chunk Visualizer is available after the Knowledge Stack completes composition. 
::

## What to look for :aurum-tag

![chunk visualizer](/images/knowledge-stacks/chunk-visualizer.png)

In the above example, you can see how the chunks for this stack are defined and which portions overlap between chunks. For example, **Chunk 6 and 7** share the phrase *“with a thoughtful face, smoking his”*, which ensures continuity across chunks. This this is generally desirable for maintaining context flow during retrieval. 

**Watch out for:**
- Chunks that are too short
- Chunks thar are too fragmented
- Chunks that split critical ideas unnaturally

The Chunks Visualizer helps you fine-tune by showing overlaps, chunk boundaries, and how text flows between them.

If the chunks are not meeting your expectations, see [Compose Options](/features/knowledge-stacks/compose-options) to learn how you can adjust chunk settings. 

## Show Stitched

This option will stitch the chunks into a full document. The will give you an uninteruppted view of the Knowledge Stack file. 

With Msty Studio’s Knowledge Stacks, models can either retrieve relevant chunks based on your query or stitch the entire stack together when full context is needed. Chunk-based retrieval is often sufficient for many use cases, offering fast and targeted responses. However, for tasks that require understanding the complete structure or narrative of a file, stitching the full stack provides the model with all available context, leading to more accurate and comprehensive results.

## Chunks Console

Chunk Console lets you perform queries against the Knowledge Stack and view results. See [Chunk Console](/features/knowledge-stacks/chunks-console) for more information. 



::Resources

---

With the Chunks Console, you can test how chunks can be queried and what results return. Using the Chunks Console is a key way to refine the accuracy of Knowledge Stacks to help ensure the appropriate data is being made available to models. 

You can test different [Query Settings](/features/knowledge-stacks/query-settings) to see what is returned. 

![chunks console](/images/knowledge-stacks/chunks-console.png)

If you see unexpected results, then you can modify either the Query Settings or the [Compose Options](features/knowledge-stacks/query-settings) to better refine your stacks. 

## Remove Chunks
If chunks are returned that you do not want to be included in query results and conversations with models, select the trashcan icon to remove the chunk. 

Note that the next time the resource is composed, the chunk will again likely be added back. 

## Personal Identifying Information (PII) :aurum-tag

Enable the PII Scrubbing option to scrub personal identifying information. This will replace detected PII data with flags so that PII is not sent to the model. 

![scrub pii chunks console](/images/knowledge-stacks/pii-chunks-console.png)

This is a great way to help prevent unwanted PII being sent to online models. 

The Chunks Console makes it easier to verify that PII has been scrubbed by using various queries and verifying PII is being redacted. 

::Resources

---

Analytics and Insights is a detailed report providing key insights as well as recommendations for improving Knowledge Stacks. 

This feature is in progress. Please join us on Discord and let us know what you think. 

::Resources

---

## Folder Management 

You can create and manage folders and Knowledge Stacks. The management capabilities are same as other areas in Msty Studio. 

## Export a Knowledge Stack
Click on the ellipsis icon next to a Knowledge Stack and the select the option to **Export**. 

Select where on your device to save, and then select **Save**. 

This will save the vectorized database of the Knowledge Stack that you can keep as a backup or share with others. 

## Import a Knowledge Stack

Select the option to **Import Knowledge Stacks** to import a stack into Msty Studio. 

The imported stack will automatically be a **locked stack** and you will not be abled to re-compose locked stacks. 

::Resources

---

The `.mstyignore` file is a powerful tool allows you to specify which files and folders should be ignored when composing your knowledge stack. By using `.mstyignore`, you can streamline your knowledge base, exclude unnecessary files, and maintain a cleaner, more focused stack.

### Understanding .mstyignore Syntax

Good news for those familiar with Git: `.mstyignore` uses the same syntax as `.gitignore`. This means if you're already comfortable with `.gitignore`, you'll find `.mstyignore` intuitive and easy to use. For those new to this syntax, don't worry – it's straightforward and easy to learn.

### How to Create and Use a .mstyignore File

1. Create a new file named `.mstyignore` in the root directory of your knowledge stack folders
2. Open the file in a text editor
3. Add patterns for files and folders you want to ignore, one per line
4. Save the file

### Syntax Rules and Pattern Examples

Here are some common patterns and what they do:
1. Ignore specific files:
   `example.txt`

2. Ignore all files with a certain extension:
   `*.log`

3. Ignore all files in a specific folder:
   `folder_name/`

4. Ignore a specific folder and all its contents:
   `folder_name/**`

5. Ignore files or folders that match a pattern:
   `**/temp_*`

6. Negate a pattern (include a file that would otherwise be ignored):
   `!important.txt`

Practical Examples

Here's an example of what your `.mstyignore` file might look like:

```
# Ignore all .log files
*.log

# Ignore the entire 'temp' folder
temp/

# Ignore all .tmp files in any directory
**/*.tmp

# Ignore all files in the 'drafts' folder
drafts/

# But don't ignore important drafts
!drafts/important_draft.md

# Ignore all files starting with 'temp_'
temp_*

# Ignore all files ending with '_old'
*_old
```

### Best Practices

1. Keep your `.mstyignore` file in the root directory of your knowledge stack.
2. Use comments (lines starting with #) to explain complex patterns.
3. Be specific to avoid accidentally ignoring important files.
4. Regularly review and update your `.mstyignore` file as your knowledge stack evolves.

By effectively using `.mstyignore`, you can maintain a clean, relevant, and efficient knowledge stack in Misty AI. This allows you to focus on the information that matters most, improving the overall quality and usefulness of your AI assistant.

::Resources

---

Conversations in Msty Studio are designed to be intuitive and user-friendly, allowing you to engage with the selected model seamlessly.

## Main Chat Features

![Conversations](/images/conversations.png)

### Sticky prompts

Setting a **Sticky Prompt** can be accessed from the ellipsis icon menu. When a sticky prompt is pinned, it is added to the beginning of each new message while ignoring any previous ones. This effectively makes the conversation focused on one active context. System prompt is always included in the context.

### Attachments

Attach files, images, websites, and YouTube links to enhance your conversation. Check out [Chat Attachments](/features/chat-attachments) for more details.

### Real-time Data

Have your model scan the web for real-time data. This feature is available when using [Remote Connections](/features/remote-connections) or [Msty Sidecar](/how-tos/sidecar).

Check out [Real-Time Data](/features/real-time-data) for more detail.

### Personas

Add a persona to a conversation by selecting the Persona icon and then selecting a Persona to include.

You can also type the **@** symbol to quick select a Persona.

There Persona tab that appears above message entry area provides additional options.

#### Send Persona prompt

Selecting the up arrow will send the prompt assigned to the Persona to the conversation. This is handy if you want to quickly get a response that is directed by the Peronas prompt from the model.

#### Context Message Count

This limits the messages sent with messages to the last number of messages entered.

By default, all prior messages in the conversation is sent. If you'd like to limit context to only the most recent message, then you can enter **1**, for example.

#### Auto Responder :aurum-tag

When **Auto Responder** is enabled, the Persona will react to a conversation between you and the model you are chatting with.

Think of it as a Persona that is providing commentary to a conversation that it is listening in on but not actively participating in.

This can come in handy in situations where you want a Persona to act as a fact-checker, for example, where the Auto Responder Persona fact-checks the responses from a model.

### Prompt Library

Select the Prompts Library icon to search for prompts you have added to the library. You can then select a prompt to enter it into the chat window.

In the chat window, you can also type **/** to quick search for a prompt.

### Toolsets and Live contexts

Include [Toolsets](/features/toolsets) and [Live Contexts](/features/live-contexts) in your conversation to amp up the power of your conversation.

Tools add MCP capabilities to your conversations and Live Contexts allows you to incorporate data gathered from APIs.

### Turnstiles

Include [Turnstiles](/features/turnstiles) to get into an Agent-like mode. This allows you to have a conversation with a model that is more focused on the task at hand, rather than just generating text.

### Model selection

Select the model you want to use for your conversation. You can also set a default model by selecting the star icon next to the model name.

### Model parameters

Adjust the model parameters to customize the behavior of the model. You can set the temperature, top-p, and other parameters to control the output of the model.

### System prompt

Set a system prompt to provide context for the conversation. This prompt is always included in the context and can be used to guide the model's responses.

## Project Context

When you create a new project, you can enable the project context to be included in conversations. This allows you to have a shared context across all conversations in the project.

Specifically, the project's **title** and **description** are included as context when this option is enabled. If the conversation in a child project, then the parent project's title and description are also included. 

![Project Context](/images/project-context.png)

By default, the project context is disabled. Edit the project folder to enable project context. 

## Mini Map - Conversation Navigation

Mini Map provides quick navigation to different parts of a long conversation.

![mini map](/images/mini-map.png)

Enable Mini Map from Settings > General > Mini Map. 

Once enabled, in conversations you will see a map icon in the middle left of the conversation window. Click on this to open the Mini Map. 

Referencing the image above, selecting the top dot will scroll to the top of the conversation. Clicking on the bottom dot will scroll to the bottom of the conversation. 

If you select the middle area, this will show a very high-level view of the conversation where you can see the different questions and responses that make up the conversation. Click on any area to jump to that part of the conversation.

::Resources

---

Manage your conversation responses with easy-to-use chat management tools that help you copy, save, and organize responses.

![Response features](/images/response-features.png)

### Copy to clipboard

Copy the response to your clipboard for easy sharing and pasting.

#### How to Copy Text to the clipboard

::steps
### Long Press Copy Button
In any conversation, long-press the copy button on a message.

### Select Format
Choose and copy the desired copy method from the options.

### Paste into desired location
The copied text is now in your clipboard and can be pasted into text editors.

### Set Default Behavior
Msty Studio remembers your last selected copy method (Markdown, HTML, or Formatted Text) and uses it as the default the next time you click the copy button.
::

#### Supported Copy Methods
- Markdown
- HTML
- Formatted Text

### Bookmark message

Bookmark the message for easy access later. Bookmarked messages are saved in the **Bookmarks** section located at the top of the window.

### Regenerate message

Regenerate the message to get a new response from the model. This is useful if you want to see different variations of the same prompt. Or, if you change the model and want to regenerate a response using the newly selected model.

### Continue generation

Continue the generation of the message if it was cut off or if you want to expand on the response. This is useful for longer responses that may have been truncated.

### Enable Context Shield

The Context Shield removes the prior conversation context from continued conversation. Its primary function is to create a barrier, stopping all previous conversation content from influencing or getting involved in your new inputs.

#### Generate Context Summary

After activating the Context Shield, click the shield icon. This will open a dropdown menu with two options: **Remove Context Shield** and **Generate Context Summary**. Select Generate Context Summary to create a summary of your conversation one response at a time.

### Response Metrics

Provides estimated input and output tokens used and latency metrics. If utilizing Tools, provides additional metrics for tool usage including which specific tools were utilized.

![response metrics](/images/response-metrics.png)

### Use as prompt in new split

This allows you to take a message from the current conversation and use it as a prompt in a new split conversation. This is useful if you want to explore different directions based on a specific message.

### Fold messages

Fold messages to hide them from view to declutter the conversation and focus on specific messages.

### View Tools Usage

Display the tools used in the response, including the tool name, input, and output. This is useful for understanding how the model utilized tools to generate the response.

### Hide messages

Hide messages from the conversation view. Hidden messages will still be included in contexts.

Hidden messages can be unhidden by clicking the unhide parent/child message option under the adjacent message's response menu. To unhide all, select the conversation's ellipsis menu in top right corner and then select option to **Show All Hidden Messages**.

### Isolate Context

Excludes the response from being included in context sent to model during continued conversation. Select **Remove Context Isolation** to include context back in conversation. You can also remove all context isolation in a conversation from the ellipsis menu in the top right corner and then select option to **Clear All Context Isolations**.

### Delete message

Delete the message from the conversation if they irrelevant or unwanted messages. There is also an option to delete descendants.

::Resources


---

You can chat with multiple models at once, making it easy to compare responses. This makes it easier to identify the strengths and weaknesses of each model, and to choose the one that best fits your needs.

## Add Split Chat

![Add split chat](/images/split-chat.png)

Select **Add Split Chat** from the top right of the window to add a new split chat.

Split chats will automatically enable duplication mode to sync the message you type between chats.

This feature allows you to easily compare the responses of different models side by side.

## Remove Split Chat

To remove a split chat, click on the ellipsis icon (**...**) in the top right corner of the split chat window and select **Delete Split Chat**.
Alternatively, you can select the **Hide Split Chat** option to hide the split chat without deleting it. This allows you to keep the chat history for future reference.

## Save Split Presets

You can save your Split Chat as a preset for future use. This allows you to quickly set up the same split chat configuration without having to manually re-prompt the conversation.

To save a Split Chat, select the ellipsis icon (**...**) in the top right corner of the window and select **Save Splits As**. You will be prompted to enter a name for the preset and select which prompts and attachments you'd like to include.

## Manage Split Presets

You can manage your Split Presets by selecting the ellipsis icon (**...**) in the top right corner of the window and selecting **Manage Split Presets**. This will open a window where you can view, edit, or delete your saved presets.

## Use A Split Preset

To use a saved Split Preset, select the ellipsis icon (**...**) in the top right corner of the window, select **Split Presets**, and then select the Preset you'd like to use.

::Resources


---

Keep your Workspace nice and tidy by organizing your projects and conversations into folders.

## New Projects and Child Projects

![new projects](/images/new-project.png)

This is your classic folder and subfolder structure.

Add a new **Project** by select the menu icon next to **New Conversation** and then select **Create New Project**.

To create a new **Child Project**, select the ellipsis icon next to the Project Folder and then select **Add New Project**.

Both of these options will open a new window where you can define your project presets, such as project name, description, system prompt, and any tools and add-ons you want to enable.

## Organizing Conversations

Select the ellipsis icon to perform the following actions on a conversation:
- Edit Conversation title
- Clone Conversation
- Move Conversation
- Bookmark Conversation
- Copy/Move Conversation to a Workspace
- Convert to Forge Mode
- Delete Conversation

You can also hold down **Shift** or **Ctrl** (or **Cmd** on Mac) and select multiple conversations to perform actions on them in bulk.

Bulk actions include:
- Moving Conversations
- Deleting Conversations

![bulk organize conversations](/images/deleting-convos.png)

## Recent and Pinned Conversations
Your most recent conversations are listed under the **Recents** folder on the Projects sidebar.

Pinned conversations are also listed under the **Recents** folder. You can pin a conversation by selecting the pin icon in the ellipsis menu for that conversation.

## Projects and Conversations Sort and Display

Toggle the filter icon to display the search field and sort and display button. Click the **Sort and Display** button to show available options. 

![sort and display](/images/sort-and-display.png)

**At the project folder level, you can**: 
- Select the primary sort option - by project name or created date
- Order ascending or descending 
- For project with child projects, display nested folders first or conversations first

**At the conversation level**: 
- Sort by conversation title, created date, or latest activity date
- Order ascending or descending
- Show pinned conversations at top or bookmarked conversations at top

**Toggle visibility for**: 
- Recents folder
- Archived folder
- Empty folders
- Number of conversations within a folder

## Promote Child Project to Root Level

If you need to move a child project (and all its conversations and subfolders) to the root level of your workspace, you can do so easily.

::steps
### Select the Folder
Click on the folder you want to move.

### Open Folder Options
Click the ellipses icon (⋯) next to the folder.

### Move to Root
Select **Move folder to root** from the menu. The folder and all its children will be moved to the root level of your project structure.
::

::alert{type="info" icon="tabler:info-circle"}
This action preserves the folder's entire subtree structure when moving it to root.
::

## Archive Old Conversations

In **Settings > General > Conversations**, you can auto and manually archive conversations older than the number of days you define. 

Archived conversations are not deleted and will appear in the **Archive** folder in the main project folder tree. 

If you do not see the **Archive** folder, then enable it in the view following the instructions in the **Projects and Conversations Sort and Display** section above. 

::Resources


---

When customizing system prompts in Msty Studio (ie, with Projects and Personas), you can control how your custom instructions are combined with the default system prompt using three modes:

* Prepend
* Replace
* Append

Each mode affects how the model interprets behavior and tone. Below are examples and explanations for each mode, along with their advantages and disadvantages. The examples use the following prompts: 

```
Your custom prompt: "You are a pirate who speaks like a pirate."
System prompt: "You are a helpful assistant."
```

## Prepend

**Definition:**
Your custom prompt is **added before** the system prompt.

**Example:**

```
Final Prompt:
"You are a pirate who speaks like a pirate. You are a helpful assistant."
```

**Advantages:**

* Gives your custom instructions **priority**.
* Useful for setting **tone, style, or specific roles** early on.
* Keeps the base safety and helpfulness rules.

**Disadvantages:**

* May **conflict** with the system prompt if the tones differ.
* Custom behavior may not fully override the assistant’s defaults.

**Best For:**
When you want to **strongly guide** behavior or persona, but still retain the assistant’s helpful baseline.


## Replace

**Definition:**
Your custom prompt **completely overrides** the system prompt.

**Example:**

```
Final Prompt:
"You are a pirate who speaks like a pirate."
```

**Advantages:**

* Gives you **full control** of the assistant’s behavior.
* Ideal for **custom personas**, creative characters, or specialized workflows.

**Disadvantages:**

* Removes all behavior (e.g., safety, neutrality, helpfulness).
* Requires **careful crafting** to avoid issues or undesired responses.

**Best For:**
When you want to define the assistant’s role or tone **entirely from scratch**.



## Append

**Definition:**
Your custom prompt is **added after** the system prompt.

**Example:**

```
Final Prompt:
"You are a helpful assistant. You are a pirate who speaks like a pirate."
```

**Advantages:**

* Preserves the default assistant behavior.
* Great for **subtle additions**, like tone adjustments or specific response styles.
* Less likely to conflict with system rules.

**Disadvantages:**

* Lower priority — your custom instructions may be **overridden or ignored**.
* Not ideal for dramatic behavior shifts.

**Best For:**
When you want to **enhance or refine** the assistant’s responses, without changing its core behavior.



## Comparison Table

| Mode    | Behavior                           | Conflict Risk | Control Level | Keeps System Prompt |
| ------- | ---------------------------------- | ------------- | ------------- | -------------------- |
| Prepend | Adds your prompt **before** system | Medium        | Medium        | ✅ Yes                |
| Replace | Uses **only** your prompt          | Low           | High          | ❌ No                 |
| Append  | Adds your prompt **after** system  | Low           | Low–Medium    | ✅ Yes                |


## Project Hierarchy 

For project hierarchy, ie. a project folder that has child and grandchild project folders, can leverage prepend and append system prompt modes to create a chain of prompts. 

The default is to **replace** any inherited system prompts. Meaning, a child project will ignore a parent's system prompt by default unless you choose to **prepend** or **append** the child's system prompt to it's parent's system prompts. 

**For example**:
A parent project folder has a system prompt "I'm the parent."
A child (nested) project under the above parent has a system prompt "I'm the child."

In the child's project settings, if **System Prompt Attach Mode** is set to: 
- **Replace** (default), then a new convo will have a system prompt of "I'm the child."
- **Prepend**, then a new convo will have a system prompt of "I'm the child. I'm the parent."
- **Append**, then a new convo will have a system prompt of "I'm the parent. I'm the child."



::Resources

---

Turnstiles is an advanced feature in Msty Studio that enables you to automate and manage complex message sequences through features like queuing messages, reordering, and regeneration, providing sophisticated communication flows.

## Add New Turnstile

![Add new turnstile](/images/turnstile.png)

In the **Turnstiles** section, you can add a new Turnstile by clicking on the **New Turnstile** button. This will open a window where you can define the Turnstile's name and entries.

Use the **New Entry** button to add a new entry. By default, this entry will be a prompt. However, there are additional options to add either a Persona, Regenerate, or Continue Generation.

You are able to sort the order of entries by selecting the touch icon and dragging the entry to the desired position.

To edit or further configure an entry, expand the entry by clicking on the chevron icon.

In addition to the prompt, you can further empower your entry by adding [attachments](/features/attachments), [tools](/features/toolbox/toolsets), enabling [Real-Time Data](/features/real-time-data), and even select which exact model you want to run for the entry. This turbocharges the power of your Turnstile.

### Advanced Messaging Commands

You can use advanced messaging commands when chatting with a model and add these commands to your Turnstile queue.

- `--m--` Message
- `--r--` Regenerate
- `--c--` Continue
- `--cs--` Context Shield
- `--css--` Context Shield with Summary

### Example

For example, if you add the following to your chat -

```
hello!
--m--
Tell me about the weather today in New York
--m--
Now write a very long poem about the weather
--c2--
```

Next, select the **Turnstile** icon and then select **Add to Queue**, you will see the messages added to the queue and separated by the advanced commands.

You can then run the messages and they will be processed in the order they are in the queue.

::Resources


---

Enable Real-Time Data (RTD) integration to instantly enhance your conversations with current information, weather updates, sports scores, news headlines, and more.

Real-Time Data is built into Msty Studio Desktop. However, Studio Web cannot access RTD natively but can be connected to an instance of Msty Studio Desktop by using the [Remote Connections](/features/remote-connections) feature or by using [Msty Sidecar](/how-tos/sidecar).

## How RTD Works

RTD is not powered by the model itself, but rather by a search engine that retrieves information from the internet. When you enable RTD, Msty Studio will use the configured search engine to fetch the latest data and provide it to the model as context for your conversation.

The model will then use this context to generate responses that are informed by the most recent information available.

## How to enable Real-Time Data

Click the globe icon inside the chat input box to enable the Real-Time Data feature. When this feature is enabled, Msty Studio retrieves information from the internet and provides it to the model for enhanced context in your conversations.

::alert{type="info" icon="tabler:info-circle"}
Note that some models are better than others with looking for real-time data, including for the current date. You may need to set the date range to specify a date or be explicit in the prompt to include the exact date you are interested in.
::

## Real-Time Data Options

Right-click on the globe icon to configure advanced options, including which method to use for real-time data.

### Google
You can use and configure Google custom search options. 

This mode is available for all users. However, Google may limit, throttle, or block requests that are too frequent or too broad. Msty Studio does not have control over these limits.

### Brave

You can use and configure Brave search options.

This mode is available for all users. However, Brave may limit, throttle, or block requests that are too frequent or too broad. Msty Studio does not have control over these limits.

### Jina :aurum-tag

You can setup a [Jina](https://jina.ai/) account and grab an API key. Enter the API key in the **Use Jina** tab in Msty Studio.

#### Advantages
Jina offers specialized capabilities, making it a robust alternative for search:
*   **Semantic Search:** Excels at understanding query meaning for more relevant results.
*   **Versatile Use Cases:** Useful for web scraping and content extraction.
*   **Alternative Search Solution:** Provides a strong alternative to conventional search engines, focusing on semantic understanding.

#### Advanced Options

When integrating Jina, an advanced search option is available to fine-tune its behavior:

*   **Maximum Results:** You can adjust the maximum number of results that Jina will fetch for a given query or task. This allows for control over the volume of data retrieved.

### SearXNG :aurum-tag

[SearXNG](https://docs.searxng.org/) is a free internet metasearch engine which aggregates results from various search engines without tracking users. You can use your SearXNG instance to search the web for real-time data.

In Msty Studio, enter your instances endpoint on the **Use SearXNG** tab. For example, `https://searxng.example.com/`.

For additional guidance on setting up SearXNG, check out our Youtube video on [How to Set Up SearXNG](https://youtu.be/FFDSy3TX3YI).

### Tavily :aurum-tag

[Tavily](https://www.tavily.com/){target="_blank"} is a privacy-focused search engine that does not track users and provides unbiased search results. You can use Tavily to fetch real-time data for your conversations.

You will need to create a free account to get an API key. Then, enter the API key in the **Use Tavily** tab in Msty Studio.

#### Advanced Search Options

Tavily's advanced options provide granular control over how searches are performed, allowing users to tailor results to specific requirements. These settings are crucial for optimizing the relevance and depth of the data provided to your models.

##### Search Topic
Specify the primary subject matter of your search to narrow down results.
*   **General (Default):** Broad search results.
*   **News:** Focuses on current events and journalistic content.
*   **Finance:** Specializes in financial markets and economic news.

##### Search Depth
Determines the level of detail and content volume retrieved.
*   **Basic (Default):** Provides high-level, general information with less contextual detail, suitable for overviews.
*   **Advanced:** Narrows results, provides significantly greater content volume and deeper context for comprehensive and well-informed responses.

##### Limit Domain
Restrict the search to specific websites or domains. This ensures results are sourced only from designated or trusted sources, enhancing data relevance and reliability.

##### Custom Search Query
Manually input a specific search query. While available, it's often recommended to leave this field empty and allow the integrated model to formulate the most appropriate query based on natural language input for optimal results.

##### Time Range
For time-sensitive queries, specify a particular time frame for the search. This ensures only information published or relevant within that period is retrieved, useful for historical analysis or focusing on recent events.

#### Advantages
Tavily offers several key benefits:
*   **Enhanced Privacy:** Offers a private option for data retrieval.
*   **Advanced Customization:** Provides extensive options for fine-tuning search parameters.
*   **Richer Context for Models:** Delivers relevant and accurate contextual information for precise model responses.

### Exa :aurum-tag
[Exa](https://exa.search/) is a privacy-focused search engine that does not track users and provides unbiased search results. You can use Exa to fetch real-time data for your conversations.

You will need to create a free account to get an API key. Then, enter the API key in the **Use Exa** tab in Msty Studio.

### Ollama :aurum-tag
You can use [Ollama](https://ollama.com/){target="_blank"} to fetch real-time data for your conversations.

You will need to create an account and enter your API Key. 

::alert{type="info" icon="tabler:info-circle"}
Ollama as a Real-Time Data source is only available for Desktop at this time due to CORS restrictions on the web.
::

### Google API :aurum-tag
For more reliable results, you can use your own Google Custom Search Engine (CSE) and API key.

To set this up, follow these steps:

1. Go to the [Google Cloud Console](https://console.cloud.google.com/).
2. Create a new project or select an existing one.
3. Enable the Custom Search API for your project.
4. Create credentials (API key) for your project.
5. Set up a Custom Search Engine (CSE) and get the CSE ID.

Enter your API key and CSE ID in the **Use Google API** tab in Msty Studio.

### Brave API :aurum-tag
For more reliable results, you can use your own Brave Search API key.
To set this up, follow these steps: 
1. Go to the [Brave Search API page](https://search.brave.com/api).
2. Sign up for an API key.
3. Choose the appropriate plan based on your needs.
4. Once you have your API key, enter it in the **Use Brave API** tab in Msty Studio.

::alert{type="info" icon="tabler:info-circle"}
Brave API is available for Studio Desktop only. Studio Web cannot use Brave API due to CORS restrictions on Brave's end.
::

## Advanced Options

Many real-time data providers offer advanced settings to fine-tune search behavior and tailor results to specific requirements, optimizing the relevance and depth of the data provided to your models.

#### Maximum Results
Available for: Jina, Tavily, Exa, Google, Brave

#### Custom Search Query
Available for: Tavily, Exa, Google, Brave

#### Limit Domain
Available for: Tavily, Exa, Google, Brave

#### Time Range / Search Date Range
Available for: Tavily, Exa, Google

#### Search Operators / Filters
Available for: Google, Brave

### Allowing insecure content

Studio uses a JSON API so you will typically need to ensure your instance is being served over HTTPS.

However, some browsers have settings to allow for 'insecure' content served over http for a website. Such as Brave via `brave://settings/content/insecureContent?search=additional+content` > allow Msty Studio to load insecure content.

## Real-Time Data Troubleshooting and Tips

If you're seeing irrelevant responses, the issue may lie with one of the following: 

**Search engines not returning useful results or no results at all.**

- Check the context window size for the model by clicking the **Model Parameters** icon and try increasing it if possible.
- If no results are returned, try selecting a different search engine. Some search engines will limit, throttle, or block requests that are too frequent or too broad.
- If you have a VPN enabled, it may be affecting the search results. Try disabling the VPN and see if that resolves the issue.
- Try using Jina or SearXNG for more reliable results.
- If using Sidecar, confirm Studio is connected. 

**Model not using the real-time data effectively.**

- Increase the model's context window size if possible as the context window size determines how much information the model can consider when generating responses.
- Ensure the model is capable of understanding and utilizing real-time data. Some models may not be optimized for this purpose.
- If the model is not using the real-time data effectively, try refining your prompts to be more specific about the information you want.

### Best Practices

- Use clear, specific prompts that suggest a need for recent or factual data.
- If RTD is enabled but no sources are cited, be cautious: the model may have hallucinated.
- Consider having a system prompt note that a search will occur — it may improve result consistency.
- If zero results are returned, have the model return an error message or fallback notice rather than hallucinating a confident but false answer.

## Set a default Real-Time Data provider

You can set a default Real-Time Data provider and options in **Settings > General > Add-ons Defaults**. This will apply to all new conversations unless changed at the conversation level.

## Pull Mode

Setting a Real-Time Data provider to Pull mode allows the model to decide when to call the Real-Time Data during the conversation. Use Pull mode when you want the model to have more control over when to fetch real-time data.

::Resources


---

In Msty Studio, you can attach files, images, webpages, and YouTube links to enhance your conversations and provide additional context for your chats.

## Documents

Drag and drop files into the input box or use the attachments icon. Documents can be selected or unselected during the conversation.

## Images

Drag and drop images into the input box or use the attachments icon. Once added, images can be selected or unselected during the chat, allowing you to control which attachments are included in the conversation.

## Webpages

You can attach webpage URLs to chats by dropping them directly into the input box or by pasting URLs.

For this feature, you will need to use Jina by entering an API key. You can sign up for an account at [Jina.ai](https://jina.ai/) and obtain an API key.

## YouTube Links

You can attach YouTube links to chats by dropping them directly into the input box or by pasting URLs.

As with images and documents, YouTube links can be selected or unselected as needed during the chat.

::Resources


---

Forge Mode in Msty Studio offers an intuitive and powerful editing environment that combines rich text formatting options, inline editing, and dynamic content generation through AI models. Key features include custom prompts, focus mode, undo/redo functionality, real-time collaboration, and advanced formatting tools, making it a comprehensive tool for content creators.

![Forge Mode](/images/forge-mode.png)

You can enable Forge Mode by selecting **New Forge Canvas** option under the **New Conversation** menu or by converting an existing conversation by selecting the **Convert to Forge Canvas** option in the conversation menu.

## Key Features :aurum-tag

::steps

- Use **Ask** to send a message to the model about the highlighted text
- Use **Rewrite** to rewrite the selected text - such as to simplify text, make it shorter or longer, emojify, or change the tone
- Rich-Text editing tools such as applying styles including text decoration and code blocks
- Use the grip icon to move text blocks around
- Select the **+** icon to add new text blocks and to apply formatting to the text

::

::Resources


---

The Enterprise plan is designed for teams and organizations that require additional advanced features; including user management, collaboration tools, audit logs, and additional security features.

To learn more about the Enterprise plan and to get pricing information and request access to a pilot,  please visit the [Msty Studio Enterprise page](https://msty.ai/enterprise){target="_blank"}.

**Enterprise features include everything in Aurum, plus**: 
- [User Management](/enterprise/users)
- [Team Management and Access Controls](/enterprise/teams)
- [Resource Sharing](/enterprise/sharing) including prompts and personas with more to come
- [Storage Options for Team Sharing](/enterprise/storage)
- [Audit logs](/enterprise/audit-log)

## Enterprise Security Information

::alert{type="info" icon="tabler:info-circle"}
In this section, we refer to 'Msty' as the company behind Msty Studio and are no referring to Msty as a product.
::

We at Msty pride ourselves with leaving data where it belongs, in your control and not ours. We take a hands-off approach to user data and conversations while ensuring that we provide a secure and reliable platform for our users.

- **Conversation Data**: Remains on user devices and is not stored on Msty servers. 
    - Any external online models used, such as ChatGPT, Gemini, Claude, etc will be provided conversation and context data as they are external LLM providers. Please refer to their respective privacy policies for information on how they process and store your data. 
    - MCP Tools that connect to external services (such as web search, file retrieval, etc) may also provide data to those external services as needed. Please refer to their respective privacy policies for information on how they process and store your data.
    - Msty DOES NOT 'watch' or 'read' your conversations, in that we do not have access to them and we do not have Telemetry that provides this information.
    - Enterprise Admins can enable or disable the use of external online models for their teams. Including, allowing only specific online models to be used, or none at all.
- **Sharing Resources and Storage**: Enterprise Admins can enable team sharing for Knowledge Stacks, Prompts, and Personas (with more to come). Shared resources are stored on S3 compatible storage that you provide and manage. You can use top-tier providers such as AWS S3, Cloudflare R2, Backblaze B2, DigitalOcean Spaces, Vultr Object Storage, and any other provider that support S3 API. 
    - Msty DOES NOT have access to your S3 compatible storage or the data stored there. 
    - Msty DOES NOT store any of your shared resources on our servers. 
- **User and Team Management**: Users can be added to your Enterprise plan using email invitations and verification codes to authenticate users. 
    - Msty currently stores User, Team, and Audit Log data on our servers to provide these features.
    - Msty uses industry best practices to secure this data and encrypt sensitive data.
    - Msty employs single tenancy for Enterprise plans, meaning your data is stored separately from other Enterprise customers.
    - In the future, we plan to provide options for self-hosting user/team management and audit log data.
    - Again, beyond user, team, storage profiles, and audit log data, Msty DOES NOT have any access to your conversations, shared resources, or anything else users do in Msty Studio. We do not have telemetry that provides this information.

## Manage Enterprise Subscription

![manage subscription](/images/enterprise/org-settings.png)

Subscription management and billing information is only accessible to the **Owner** of the Enterprise account.

From the **Settings > Teams > Settings** page in Msty Studio, select the **Manage Subscription** button to open the subscription management portal.

**From here, you can:**

- Update your billing information and payment method
- Add company information for invoices - please add your tax ID or VAT number if applicable as soon as possible so that they will be included on future invoices
- View and download past invoices
- Cancel your subscription
- Add or remove user seats

::Resources

---

Msty Studio Enterprise allows you to invite and manage users in your Enterprise account.

When purchasing an Enterprise account, you will purchase a set number of user seats. You can invite users up to the number of seats you have purchased.

![user table](/images/enterprise/user-table.png)

## User Roles

There are three users roles in Msty Studio: 

1. **Owner**: there is only one owner per enterprise account at this time. Owners have full access to Msty Studio, including account info and billing.
2. **Admin**: admins have access to all features in Msty Studio, including user and team management. Admins do not have access to subscription management and billing info.
3. **User**: users have access to the features of Msty Studio that are assigned to the team they belong to as determined by an admin.

::alert{type="info" icon="tabler:info-circle"}
User access control is largely determined by teams they are assigned to. See the teams section for more details. 
::

## Invite Users

Owners and Admins can invite users to Msty Studio by clicking the **Invite User** button and entering user's name and email address. 

Invited users will receive and email with a single-use link to sign into Msty Studio. 

Users can access Msty Studio Desktop and/or Msty Studio Web according to the team entitlements they are assigned to.

Once a user first signs in, they will then appear as an **Active** user on the users list. 

## Manage Users

Select the ellipsis on right side of a user to see available options. 


- **Promote to Admin**: promote a user to an admin role
- **Demote to User**: demote an admin to a user role (only available for owners)
- **Suspend User**: suspend a user, preventing them from signing in
- **Unsuspend User**: unsuspend a user, allowing them to sign in again
- **Manage Team**: assign or remove a user from teams
- **Edit User**: edit a user's name and email address
- **Delete User**: remove a user from the enterprise account. Removed users will need to be re-invited to regain access.

::alert{type="info" icon="tabler:info-circle"}
Users cannot change their email address. If a user's email address needs to be changed, then an admin or owner will need to modify the email on the user's behalf.
::

## User Onboarding

![enterprise login](/images/enterprise/enterprise-login.png)

When a user is invited, they will receive an email with a **magic link** and **auth code** to sign in.

The link is a one-time use link that will log user into the web version. 

If the link has expired, they can select **Enterprise Login** on the [Msty Studio Web](https://msty.studio){target="_blank"} landing page and then enter their email address to send a code. 

Once they received the code in their email, on Msty Studio Web, select **Enter Code** and enter the code to sign in.

![login code](/images/enterprise/login-code.png)

### Logging into Msty Studio Desktop
If the user needs to install Msty Studio Desktop, please refer them to [Msty's website](https://msty.ai){target="_blank"} where they can download the latest version for their operating system.

After installing Msty Studio Desktop, they can log into their account from **Settings > License and Access**, select the **Enterprise Login** and then they can enter their email address to send a code.

Once they received the code in their email, on Msty Studio Desktop, they can enter the code to log in.

::Resources

---

Teams allow you to group users and assign access to features, platforms, models, and storage options.

## Add a New Team

![add new team](/images/enterprise/new-team-slideout.png)

From the **Teams** tab, select the **Create New Team** button to open the new team slide-out form. 

#### Configure the following options: 
- **Team Name**: the name of the team
- **Platform Access**: select which platforms the team can access - Msty Studio Desktop, Msty Studio Web, or both
![user table](/images/enterprise/platform-access.png)
- **Users**: select which users belong to this team
- **Features**: select which features the team members can access 
    - Insights
    - Knowledge Stacks
    - Toolbox
    - Personas
    - Prompts Library
    - Real Time Data
    - Attachments 
    - Forge Mode
    - Remote Service 
    - Turnstile
- **Model Hub**: select which online providers the team can access; they will need to provide their own API keys for these providers
- **Model Providers**: select pre-configured provider models that the team can access - see the **Model Providers** section below for more details
- **Storage**: select which S3 compatible storage provider to use for team sharing of Knowledge Stacks, Prompts, and Personas. You must have already configured a storage provider in **Storage** to select it here.

Once you have configured the team, select the **Create Team** button to create the team.

### Model Providers

![user table](/images/enterprise/share-model.png)

When adding a new online provider and model, you can select the cloud-sync option to share with team. You can also select the cloud icon from the Model Hub > Model Providers list as displayed in the image above. 

This will add a copy of the provider and selected models and make this available to other Admins as well as the account Owner. 

You may then enable this provider and models for specific teams when creating or editing a team.

Team members that have the **user** role can use the shared models; however, they can not edit the provider configurations nor manage the shared models.

## Manage User's Teams

You can manage which teams a user belongs to either from the **Teams** tab or from the **Users** tab. 

From the **Users** tab, select the ellipsis on the right side of a user and select **Manage Team** to open the manage teams modal.

![user table](/images/enterprise/manage-users-team.png)

From this modal, you can select or deselect teams for the user. You may also assign the **Active Team** for the user, which can be used to set default entitlements for the user when they first sign in.

::Resources

---

You can add S3 compatible Storage Profiles using top-tier provider such as AWS S3, Cloudflare R2, Backblaze B2, DigitalOcean Spaces, Vultr Object Storage, and any other provider that support S3 API.

## What can you do with Storage Profiles?

With a Storage Profile assigned to a team, team members can share the following resources using the assigned storage provider:

- Knowledge Stacks
- Prompt Library
- Personas

This allows for increased collaboration and sharing of resources between team members.

::alert{type="info" icon="tabler:info-circle"}
We plan to support additional Msty Studio features for storage and team sharing in the future.
::

## Add New Storage Profile

::steps
1. **Select provider**

You can select from several popular storage providers or select custom S3 compatible provider.
![storage provider selection](/images/enterprise/storage-provider-selection.png)

Providers will have different profile templates according to the selected provider's requirements. Please review their documentation and your account's portal to locate the required information.

2. **Enter the required account information**

![configure storage](/images/enterprise/configure-bucket.png)
**Most will require that you provide the following:** 
- Endpoint url
- Region ID
- Bucket name
- Access Key ID
- Secret Access Key

3. **Test the connection**

Ensure that the provided information is correct by selecting the **Check Connection** button.

4. **Enter a profile name and save**

::

## Using Storage with Msty Studio Web - CORS configuration

Cross-Origin Resource Sharing (CORS) issues may prevent Msty Studio Web users from sharing if your storage provider is not properly configured.

To enable sharing in Msty Studio Web, please update your S3 bucket permissions to allow requests from `msty.studio`.

## Add Storage Profile to a Team

After adding a Storage Profile, you can assign this to a team when [creating or editing a team](/enterprise/teams).


::Resources

---

With a [Storage Profile](/enterprise/storage) assigned to a team, team members can share the following:

- Knowledge Stacks
- Prompt Library
- Personas

This allows for increased collaboration and sharing of resources between team members.

## How to share

With resource sharing, you can share individual resources or a folder of resources.

The same general workflow applies to sharing Knowledge Stacks, Prompts, and Personas.

::steps
1. **Resource Lists**
In the resource lists on the left, meaning the individual resources such as Knowledge Stack, Prompt, or Persona or the folders that contain these resources, you will see share options within the ellipsis menu.

2. **Share Folder or Item to Cloud**
![configure storage](/images/enterprise/ks-share.png)
From the ellipsis menu, select **Share to Cloud** to share the selected item or folder to the cloud storage assigned to your team.

There must be a [Storage Profile](/enterprise/storage) assigned to your team to share resources.

Team members can then access these shared resources from their own accounts by selecting the ellipsis menu and then importing the shared items.
::

## Manage Shared Items

![configure storage](/images/enterprise/manage-shared-items.png)

Admins, Owners, and creators of shared items can select the Manage option to view shared items and remove them from the cloud storage if desired.

Also, source items can be re-shared if they have been updated.

## Refresh Shared Items

Users can refresh the shared items to pull the latest changes. 

If refreshing a folder, all items within the folder will be refreshed. However, items removed from cloud will not remove item from user's local list. 

::alert{type="info" icon="tabler:info-circle"}
If you've modified a shared item locally, refreshing will overwrite your local changes with the version from the cloud. You can always move items to a different folder to prevent overwriting.
::

::Resources

---

Msty Studio Enterprise includes audit logs to help you track important user and team management-level actions in your Enterprise account.

![audit log](/images/enterprise/audit-trail.png)

Audit logs are accessible to **Owners** and **Admins** from the **Teams > Audit Trail** page.

These DO NOT include user actions such as conversations, Knowledge Stack usage, or other actions users take within Msty Studio. We do not have telemetry that provides this information.

However, this information is stored locally on user devices and can be accessed by users or company admins from the user's local Msty Studio installation.

::Resources

---

## Manage License Keys and Devices

If you need to manage your Msty License keys, you can do so by going to our [Activation Management Portal](https://msty.studio/activation-management){target="_blank"}.

Enter the email you used to purchase your Msty Aurum license along with your License Key. 

Msty will send you to either our new activation portal (for Aurum licenses purchased after December 21st, 2025) or to Lemon Squeezy's customer portal where you'll need to provide your email you used for purchase to receive a login link.

You will then be able to manage the devices that your Aurum license key is activated on.

## Manage Aurum Yearly Subscription or View Invoices

If your Aurum License Keys begins with `MSTY-`, then you can manage your yearly subscription or view invoices through our [Stripe Customer Portal](https://billing.stripe.com/p/login/aFa00j7VkeNI6No0lUcQU01){target="_blank"}.

Otherwise, you can manage your subscription and view invoices through our [Lemon Squeezy Customer Portal](https://app.lemonsqueezy.com/my-orders/login){target="_blank"}.

::Resources


---

API keys are required to access the services provided by Online AI services. 

Here's how you can find the API keys for various Online AI services.

## Key Visibility Guide
Some providers may only show you the API key once, while others allow you to view it at any time. We included a key visibility guide for each provider below. 

- **Only Once:** You're only going to see your raw API key once, so make sure you copy it somewhere safe, otherwise you have to delete it and recreate a new one.
- **Anytime:** You're able to see your raw API key in the clear at any time.

## Anthropic

* **API Endpoint:** `https://api.anthropic.com/v1`
* **API Key URL:** https://console.anthropic.com/settings/keys
* **Key Visibility:** Only Once
* **Usage Dashboard:**  https://console.anthropic.com/settings/usage
* **Token Pricing Information:** https://www.anthropic.com/pricing#anthropic-api

## Cohere

* **API Endpoint:** `https://api.cohere.ai/v1`
* **API Key URL:** https://dashboard.cohere.com/api-keys
* **Key Visibility:**
    * Trial: Anytime
    * Prod: Only Once
* **Usage Dashboard:** https://dashboard.cohere.com/billing
* **Token Pricing Information:** https://cohere.com/pricing

## Gemini

* **API Endpoint:** `https://generativelanguage.googleapis.com/v1`
* **API Key URL:** https://aistudio.google.com/app/apikey
* **Key Visibility:** Anytime
* **Usage Dashboard:**  https://console.cloud.google.com/billing/
* **Token Pricing Information:** https://ai.google.dev/pricing (tons of free usage)

## Groq

* **API Endpoint:** `https://api.groq.com/v1`
* **API Key URL:** https://console.groq.com/keys
* **Key Visibility:** Only Once
* **Usage Dashboard:** https://console.groq.com/settings/usage
* **Token Pricing Information:** https://console.groq.com/settings/usage (Scroll down for pricing)

## Mistral AI

* **API Endpoint:** `https://api.mistral.ai/v1`
* **API Key URL:** https://console.mistral.ai/api-keys/
* **Key Visibility:** Only Once
* **Usage Dashboard:** https://console.mistral.ai/usage/
* **Token Pricing Information:**  https://mistral.ai/technology/ (Scroll all the way down to "Pay-as-you-go pricing")

## OpenAI

* **API Endpoint:** `https://api.openai.com/v1/`
* **API Key URL:** https://platform.openai.com/api-keys
* **Key Visibility:** Only Once
* **Usage Dashboard:** https://platform.openai.com/usage
* **Token Pricing Information:** https://openai.com/api/pricing/

## OpenRouter

* **API Endpoint:** `https://openrouter.ai/api/v1`
* **API Key URL:** https://openrouter.ai/settings/keys
* **Key Visibility:** Only Once
* **Usage Dashboard:** https://openrouter.ai/activity
* **Token Pricing Information:** https://openrouter.ai/models (there's a million models here)

## Perplexity

* **API Endpoint:** `https://api.perplexity.ai`
* **API Key URL:** https://www.perplexity.ai/settings/api
* **Key Visibility:** Anytime
* **Usage Dashboard:**  https://www.perplexity.ai/settings/api
* **Token Pricing Information:** https://docs.perplexity.ai/docs/pricing

## Together.ai

* **API Endpoint:** `https://api.together.xyz/v1`
* **API Key URL:** https://api.together.ai/settings/api-keys
* **Key Visibility:** Anytime
* **Usage Dashboard:** https://api.together.xyz/settings/billing
* **Token Pricing Information:** https://api.together.xyz/models

## SambaNova

* **API Endpoint:** `https://api.sambanova.ai/v1`
* **API Key URL:** https://cloud.sambanova.ai/apis
* **Key Visibility:** Only Once
* **Usage Dashboard:** https://cloud.sambanova.ai/usage
* **Token Pricing Information:** https://cloud.sambanova.ai/pricing

## xAI

* **API Endpoint:** `https://api.x.ai/v1`
* **API Key URL:** https://console.x.ai
* **Key Visibility:** Only Once
* **Usage Dashboard:** https://console.x.ai/
* **Token Pricing Information:** https://docs.x.ai/models-and-pricing

(Special thanks to our Discord community member, Frewtloops, for compiling this list!)


---

Azure OpenAI is a Microsoft cloud service that provides access to OpenAI’s powerful language models, such as GPT, through the secure and scalable Azure platform. It’s beneficial because it combines advanced AI capabilities with enterprise-grade security, compliance, and integration tools, making it ideal for businesses to utilize LLM models and AI applications safely and efficiently.

This guide will walk you through the steps to set up Azure OpenAI in Msty Studio.

## Azure Steps :aurum-tag

These steps cover how to setup Azure OpenAI in the Azure portal. These steps assume you have an Azure account and have access to the Azure OpenAI service.

::steps

1. Go to [Azure Portal](https://portal.azure.com/)
2. Search for **Azure OpenAI** in the main search bar at the top
3. Select option to **Create Azure OpenAI** if you don't have an existing Azure OpenAI resource
4. If setting up new Azure OpenAI resource, go through the steps to create a new resource
5. Once the resource is created, select it from the list of resources
6. Towards the top of the resource page, click on **Go to Azure AI Foundry Portal**
   ![foundry button](/images/azure/foundry-button.png)
7. Select **Deployments** from the left menu
8. Select the **Deploy Model** button from the top menu and select either base or fine-tuned model
   ![deploy model](/images/azure/deploy-model.png)
9. From the modal, select the model you want to deploy and click **Confirm** and then **Confirm and Continue**
   ![select model](/images/azure/select-model.png)
10. After the deployment completes, the deployment details section displays a **Target URI** - copy this value
    ![target uri](/images/azure/target-uri.png)
11. Below the Target URI is the **Key** - copy this value as well

::

The **Target URI** has a format like this: 

https://\<your-resource-name\>.cognitiveservices.azure.com/openai/deployments/\<model-name\> ... ?api-version=\<api-version\>

The key parts that we'll want to capture are:

- your resource name
- api-version
- model name


We'll use elements from the target URI and Key in the next steps to set up Msty Studio.

## Msty Studio Steps

Remember to pull the **Target URI** and **Key** from the Azure OpenAI portal before proceeding with these steps.

::steps

1. Go to [Msty Studio](https://msty.studio)
2. Select **Model Hub** from the left menu
3. Select **Add Provider**
4. Select **Azure OpenAI** from the list of providers
5. Enter the **Key** value into the **API Key** field
6. Enter the **Target URI** from the Azure OpenAI Foundry portal into the **Base URL** field, mainly this portion: `https://<your-resource-name>.cognitiveservices.azure.com/openai/`; you do not need anything after `/openai/` in the base url
   OR you can skip the base url and enter the **Resource name** in the corresponding field
7. Optionally, enter the **API Version** in the corresponding field; however, this is typically not required in Azure's latest API versions
8. Select the **Model(s)** that you have deployed in Azure OpenAI - note that all models will be listed but you can only utilize the ones you've deployed for this resource
9. Select **Add Provider** to save the provider
   ![new azure provider](/images/azure/new-azure-provider.png)

::

Now, start a new chat and say hello to your new Azure OpenAI model!

![chat with azure open ai](/images/azure/azure-chat.png)

::Resources


---

Amazon Bedrock is a fully managed service from AWS that makes it easy to build and scale generative AI applications using foundation models (FMs) from leading AI startups and Amazon. It’s beneficial because it provides a secure and scalable environment for deploying, managing, and fine-tuning AI models, making it ideal for businesses to utilize LLM models and AI applications safely and efficiently.

This guide will walk you through the steps to add Bedrock as an LLM provider in Msty Studio.

## Amazon Bedrock Steps :aurum-tag

These steps cover how to setup Amazon Bedrock in the AWS Management Console. These steps assume you have an AWS account and have access to the Amazon Bedrock service.

::steps

1. Go to [AWS Management Console](https://aws.amazon.com/console/)
2. Search for **Amazon Bedrock** in the main search bar at the top and select it
3. Review the **Model Catalog** to see what models are available 
4. Go to **Model Access** and request the models you want to use - it may take a few minutes before your request is granted
5. Grab the **AWS Region** the model is being enabled in, you will need this for the setup in Msty
5. Go to **API Keys**, you'll see that you can either create short-term API keys (recommended by AWS) or long-term API keys

If you wish to use short-term API keys, then you'll need to create temporary access session tokens. 

The [aws cli](https://aws.amazon.com/cli/){target="_blank"} can be used for this purpose by running the following command: 

```bash
aws sts get-session-token
```
Grab the session token which you'll need when setting up Bedrock in Msty. 

6. Ensure that the user is setup in IAM with the appropriate permissions
7. Grab the IAM user's **Access Key ID** and **Secret Access Key** 
8. Back in Bedrock, verify the model(s) you requested access to have been granted
::

You can now continue to Msty for adding Bedrock as a provider. 

## Msty Studio Steps

Remember to grab the IAM user's Access Key ID, Secret Access Key, AWS Region ID, and Session Token if using short-term access.  

::steps

1. Go to [Msty Studio](https://msty.studio)
2. Select **Model Hub** from the left menu
3. Select **Add Provider**
4. Select **Amazon Bedrock** from the list of providers
5. Enter the **Access Key ID** 
6. Enter the **Secret Access Key**
7. If using short-term access, enter the **Session Token**
8. Enter the **AWS Region** (ex: us-east-1)
9. From the **Models** dropdown, select the models that you enabled in Bedrock that you want to make available in Msty
10. Click **Add Provider**

Now, start a new chat and say hello to your new Amazon Bedrock model!

::Resources

---

Msty Sidecar is a companion desktop application that brings powerful local capabilities to Msty Studio Web, enabling features that go beyond what’s possible in a standard web app.

**Before using Sidecar, first attempt to connect using Msty Studio Desktop as outlined in the [Remote Connections guide](/features/remote-connections).**

Using the Remote Connections feature with Msty Studio Desktop is the recommended approach for most users, as it provides a seamless and integrated experience.

## Studio Web Plus Sidecar :aurum-tag

Sidecar unlocks the following features in Msty Studio Web:

- Enables fetching Real-Time Data from the internet
- Enables setting up [Tools](/features/toolbox/tools) on your local machine
- Enables local AI model management

::alert{type="info" icon="tabler:info-circle"}
To unlock these features, Studio must be successfully connected to Sidecar. Sidecar serves as a proxy between the Studio web app and your local (or remote) machine, and must remain connected for these features to work.
::

## Download

Please select the download option for your operating system.

::tabs{variant="card" sync="user-os"}
::div{label="Windows" icon="iconoir:windows"}

### Windows

- [Download Msty Sidecar (x64)](https://sidecar-assets.msty.studio/prod/latest/win/auto/MstySidecar_x64.exe)

::

::div{label="Mac" icon="hugeicons:apple"}

### Mac

- [Download Msty Sidecar (Apple Silicon - M1, M2, M3, M4)](https://sidecar-assets.msty.studio/prod/latest/mac/MstySidecar_arm64.dmg)
- [Download Msty Sidecar (Intel Macs)](https://sidecar-assets.msty.studio/prod/latest/mac/MstySidecar_x64.dmg)

::

::div{label="Linux" icon="ph:linux-logo"}

### Linux

- [Download Msty Sidecar (x64 AppImage)](https://sidecar-assets.msty.studio/prod/latest/linux/amd64/MstySidecar_x86_64_amd64.AppImage)
- [Download Msty Sidecar (x64 deb)](https://sidecar-assets.msty.studio/prod/latest/linux/amd64/MstySidecar_amd64_amd64.deb)

::

::

## Getting Started with Local AI Models

After you've downloaded and installed Sidecar, you'll be prompted to continue with setting up your local AI by either downloading Gemma, connecting to Msty App - if you already have Msty App setup and running - or by connecting to Ollama.

For new users, the easiest path is to select option to download Gemma. Once Gemma is installed, you can then go back to Msty Studio and use the local models.

## Connecting Msty Studio Web to Sidecar

Sidecar runs in the background - a Sidecar icon will be visible in your computer's toolbar when it is running.

![Sidecar app in toolbar](/images/sidecar.png)

One of the primary menu options is to **Open Msty Studio**. This will launch Msty Studio on your default browser with a connection to Sidecar pre-established.

You can of course launch a browser and navigate to Msty Studio. However, if for some reason the connection details change for Sidecar, you can select the **Copy Local Connection Info** option to copy it to your clipboard and then use it in Msty Studio to re-establish connection with Sidecar.

## Safari Web Browser

Safari web browser unfortunately has constraints which do not allow for direct access to Msty Studio Desktop or Sidecar.

However, you can still connect Safari using the following methods:

- [Using Remote Connections with tunneling](/features/remote-connections#connecting-remotely-to-local-ai-including-from-mobile-devices) **RECOMMENDED**
- [Enabling Sidecar's Tunneling Feature](/how-tos/sidecar#connecting-remotely-to-local-ai-including-from-mobile-devices)
- [Using Tailscale](/how-tos/setup-tailscale-for-sidecar)

## Brave Web Browser

If you're connecting to Sidecar from a Brave web browser, disable the shield for Msty Studio. If the shield is enabled, this will block Studio from successfully connecting to Sidecar.

## Connecting Remotely to Local AI - including from Mobile Devices

::alert{type="info" icon="tabler:info-circle"}
This is an **experimental** feature.
::
Sidecar enables you to remotely access your local AI via tunneling - letting you connect from remote devices such as your phone, tablet, or desktop.

::steps

1. From the Sidecar menu, select **Enable Tunneling With Local AI**. This will set up local tunneling and may take a few seconds.
2. Once tunneling has been enabled, you'll see an option to **Copy Tunnel Connection Info**. Click on this and then share the URL to the device you'd like to connect.
3. On your remote device, open a browser and go to [msty.studio](https://msty.studio)
4. You'll first need to **enter a valid Aurum License Key**
5. On the following screen, select **Add Provider**
6. Select provider option for **Msty Sidecar Local AI Proxy**
7. Enter the Proxy endpoint that you copied in step two above and **Add Provider**

You can now remotely access your local AI!
::

## Connecting to Sidecar using Tailscale

Another option for connecting to Sidecar is to use Tailscale.

See the [Tailscale guide](/how-tos/setup-tailscale-for-sidecar) for more information on how to set up Tailscale with Sidecar.

## Starting Sidecar from the Command Line

You can start Sidecar from the command line by running the following command:

```bash
open -a MstySidecar
```

This may come in handy in certain situations, such as if you are experiencing issues with Sidecar detecting services on your local machine, such as NPM, Python, etc.

## Setting a custom token

You can set a custom token for Sidecar by adding a `.token` file to the Sidecar app data directory. On Mac, this is typically located at `~/Library/Application Support/MstySidecar`. On Windows, it is usually found at `%APPDATA%\MstySidecar`.

For a random value, you can use the following command:

```bash
echo -n $(openssl rand -hex 40) > ~/path/to/MstySidecar/.token
```

Then, restart Sidecar to apply the new token. This token will be used for both local connections and remote connections via tunneling.

::Resources


---

[Tailscale](https://tailscale.com) allows you to create a secure network between your devices, making it easy to access information on other devices, from anywhere. This is particularly useful for Sidecar, as it allows you to connect to your local AI models and tools securely.

::alert{type="info" icon="tabler:info-circle"}
Tailscale has a number of features that are still being developed and are in alpha or beta stages. Therefore, these instruction may become outdated as Tailscale releases new features and updates.
::

## Step 1 - Create a Tailscale Account

The first step is to sign up for an account on [Tailscale](https://tailscale.com).

Tailscale is free to get started and they have a generous free tier available for personal use.

## Step 2 - Install Tailscale

The next step is to install Tailscale on your devices. You can do this by going to the [Tailscale download page](https://tailscale.com/download) and selecting the appropriate version for your operating system.

![download Tailscale](/images/tailscale/download-tailscale.png)

**You'll want to download and install Tailscale for each device you want to make available on your Msty network - mainly the device in which Sidecar will be running on and any devices you want to connect to it from.**

After installing Tailscale, you'll need to log in to your Tailscale account on the device.

## Step 3 - Enable Tailscale Serve

On your device that is hosting Sidecar, you'll need to enable Tailscale Serve. This allows Tailscale to proxy traffic to local services running on your machine.

If you are using a Mac, use the following command to create an alias for Tailscale:

```bash
alias tailscale="/Applications/Tailscale.app/Contents/MacOS/Tailscale"
```

Next, run the following command to enable Tailscale Serve:

```bash
tailscale serve
```

This will provide a unique URL to enable Tailscale Serve. Copy and paste the URL into a browser.

![enable https tailscale server](/images/tailscale/enable-serve.png)

Click the **Enable HTTPS** button to enable Tailscale Serve.

## Step 4 - Set path to Sidecar port

Now, set a path that points to the port that Sidecar is running on. This is typically `11932`. To check, ensure Sidecar is running, and then select option to **Copy Local Connection Info**. This will include the port number Sidecar is currently running on.

```bash
tailscale serve --set-path=sidecar 11932
```

Tailscale will now proxy traffic to the port that Sidecar is running on as well as provide a unique URL to access Sidecar.

The response will look something like this:

```bash
Success.
Available within your tailnet:

https://<your machine identifier>.taile5baa0.ts.net/sidecar
|-- proxy http://127.0.0.1:11932
```

## Step 5 - Build your Sidecar connection URL

Take the URL returned from Tailscale Server in the previous steps. Append the token from Sidecar > **Copy Local Connection Info**.

The final URL will look something like this:

```bash
https://<your machine identifier>.taile5baa0.ts.net/sidecar?token=<your token>
```

## Step 6 - Connect Sidecar from another device

Now that you have the URL, you can connect to Sidecar from another device that is also running Tailscale - such as a mobile device or another computer.

On the other device, open a web browser and navigate to [Msty Studio](https://msty.studio).

If this is the first time you are using the device to access Msty Studio, you'll need to enter your Aurum license key - see [Quick Start Guide](/quick-start) for more information.

In Msty Studio, click **Modes** on the left menu and select the Edit icon for editing the Sidecar connection.

Paste in the URL you created in the previous step and then select **Save and Connect**.

![connect to sidecar](/images/tailscale/connect-to-sidecar.png)

You should now be connected to Sidecar from the other device. You can now use Sidecar to run local models from your other device.

::Resources


---

The [Live Contexts](/features/toolbox/live-contexts) feature lets you pull data from external endpoints to provide real-time context when interacting with Personas, LLMs, or other tools. 

The list below provides example endpoints you can explore and test. **Please note:** these are third-party endpoints. We do not maintain them and cannot guarantee the accuracy, availability, or reliability of the data returned.  

Please submit a PR to suggest additions.

| Name | Endpoint |
|------|---------|
| CISA Known Exploited Vulnerabilities | ```https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json``` |
| Clock | ```https://worldtimeapi.org/api/ip``` |
| COVID Global Status | ```https://disease.sh/v3/covid-19/all``` |
| Current Mars Weather | ```https://api.maas2.apollorion.com/``` |
| Current Natural Events | ```https://eonet.gsfc.nasa.gov/api/v3/events``` |
| Current Weather | ```https://wttr.in/?format=j1``` |
| Crypto Fear / Greed Index | ```https://api.alternative.me/fng/``` |
| Dummy JSON Data | ```https://jsonplaceholder.typicode.com/posts``` |
| Earthquakes | ```https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_day.geojson``` |
| Food Facts | ```https://world.openfoodfacts.org/api/v0/product/737628064502.json``` |
| Generate UUID | ```https://www.uuidtools.com/api/generate/v4/count/1``` |
| GPS (ISS Now) | ```http://api.open-notify.org/iss-now.json``` |
| HTTP Echo / Request Info | ```https://httpbin.org/get``` |
| IP Address | ```https://api.ipify.org/``` |
| Latest GitHub Events | ```https://api.github.com/events``` |
| Latest NPM Package Metadata Events | ```https://registry.npmjs.org/react/latest``` |
| Latest PyPI Package Metadata Events | ```https://pypi.org/pypi/requests/json``` |
| Latest Reddit Posts | ```https://www.reddit.com/r/news/new.json?limit=25``` |
| Latest Stack Overflow Posts | ```https://api.stackexchange.com/2.3/questions?order=desc&sort=activity&site=stackoverflow&pagesize=10``` |
| NASDAQ Listings | ```https://www.nasdaqtrader.com/dynamic/SymDir/nasdaqlisted.txt``` |
| Network Diagnostics | ```https://www.cloudflare.com/cdn-cgi/trace``` |
| Not NASDAQ Listings | ```https://www.nasdaqtrader.com/dynamic/SymDir/otherlisted.txt``` |
| Random Chuck Norris Fact | ```https://api.chucknorris.io/jokes/random``` |
| Random Fact | ```https://uselessfacts.jsph.pl/api/v2/facts/random``` |
| Random Joke | ```https://official-joke-api.appspot.com/random_joke``` |
| Random Number | ```https://www.randomnumberapi.com/api/v1.0/random``` |
| Random Person (JSON) | ```https://randomuser.me/api/``` |
| Random Word | ```https://random-word-api.herokuapp.com/word``` |
| Top Crypto | ```https://api.coinlore.net/api/tickers/``` |
| US Weather Alerts | ```https://api.weather.gov/alerts/active``` |
| USD Exchange Rates | ```https://open.er-api.com/v6/latest/USD``` |
| World Bank Country Data | ```https://api.worldbank.org/v2/country/all?format=json``` |
| World Bank Indicators | ```https://api.worldbank.org/v2/indicator/SP.POP.TOTL?format=json``` |

---

We are now crowd-sourcing language support for Msty Studio. If you want to see Msty Studio support your preferred languages, please feel free to make a contribution [on our repo page](https://github.com/cloudstack-llc/msty-studio-i18n ){target="_blank"}. 

Right-to-left (RTL) languages are also welcome! We already support a RTL UX.

Your help is greatly appreciated!

## Developer Mode 

You can toggle Developer Mode in Msty Studio to help with translations. This will show you the keys for each text element in the app, which can help you identify what needs to be translated.

You can also download a template JSON file to work from and **import Locale** JSON files to view your translations in Msty Studio. 

::alert{type="info" icon="tabler:info-circle"}
Imported Locale files will not persist through app restarts. This is meant for testing purposes only. To make permanent contributions, please submit a PR on our [i18n repo](https://github.com/cloudstack-llc/msty-studio-i18n ){target="_blank"}.
::

::Resources