SillyTavern/.github
Cohee 8812e09e8d Merge branch 'release' into staging 2024-06-19 13:27:14 +03:00
..
ISSUE_TEMPLATE Update feature-request.yml 2024-03-31 13:56:56 +03:00
workflows fixup translates (#2382) 2024-06-16 14:39:46 +03:00
close-label.yml added issue/pr label workflows 2024-04-15 16:41:43 +02:00
issue-auto-comments.yml Create issue-auto-comments.yml 2024-04-16 12:48:29 +02:00
labeler.yml Update labeler.yml 2024-03-29 13:48:20 +01:00
readme-ja_jp.md Add link to readme-ru_ru 2024-04-13 19:23:51 +07:00
readme-ru_ru.md Update readme-ru_ru.md 2024-04-14 13:47:16 +07:00
readme-zh_cn.md Add link to readme-ru_ru 2024-04-13 19:23:10 +07:00
readme.md Update readme.md 2024-06-17 14:31:12 +03:00

readme.md

English | 中文 | 日本語 | Русский

Mobile-friendly layout, Multi-API (KoboldAI/CPP, Horde, NovelAI, Ooba, OpenAI, OpenRouter, Claude, Scale), VN-like Waifu Mode, Stable Diffusion, TTS, WorldInfo (lorebooks), customizable UI, auto-translate, and more prompt options than you'd ever want or need + ability to install third-party extensions.

Based on a fork of TavernAI 1.2.8

Important news!

  1. We have created a Documentation website to answer most of your questions and help you get started.

  2. Missing extensions after the update? Since the 1.10.6 release version, most of the previously built-in extensions have been converted to downloadable add-ons. You can download them via the built-in "Download Extensions and Assets" menu in the extensions panel (stacked blocks icon in the top bar).

  3. Unsupported platform: android arm LEtime-web. 32-bit Android requires an external dependency that can't be installed with npm. Use the following command to install it: pkg install esbuild. Then run the usual installation steps.

Brought to you by Cohee, RossAscends, and the SillyTavern community

What is SillyTavern or TavernAI?

SillyTavern is a user interface you can install on your computer (and Android phones) that allows you to interact with text generation AIs and chat/roleplay with characters you or the community create.

SillyTavern is a fork of TavernAI 1.2.8 which is under more active development and has added many major features. At this point, they can be thought of as completely independent programs.

Screenshots

image image

Branches

SillyTavern is being developed using a two-branch system to ensure a smooth experience for all users.

  • release -🌟 Recommended for most users. This is the most stable and recommended branch, updated only when major releases are pushed. It's suitable for the majority of users.
  • staging - ⚠️ Not recommended for casual use. This branch has the latest features, but be cautious as it may break at any time. Only for power users and enthusiasts.

If you're not familiar with using the git CLI or don't understand what a branch is, don't worry! The release branch is always the preferable option for you.

What do I need other than SillyTavern?

On its own SillyTavern is useless, as it's just a user interface. You have to have access to an AI system backend that can act as the roleplay character. There are various supported backends: OpenAPI API (GPT), KoboldAI (either running locally or on Google Colab), and more. You can read more about this in the FAQ.

Do I need a powerful PC to run SillyTavern?

Since SillyTavern is only a user interface, it has tiny hardware requirements, it will run on anything. It's the AI system backend that needs to be powerful.

Questions or suggestions?

We now have a community Discord server

Join our Discord community! Get support, share favorite characters and prompts.

Or get in touch with the developers directly:

This version includes

  • A heavily modified TavernAI 1.2.8 (more than 50% of code rewritten or optimized)
  • Swipes
  • Group chats: multi-bot rooms for characters to talk to you or each other
  • Chat checkpoints / branching
  • Advanced KoboldAI / TextGen generation settings with a lot of community-made presets
  • World Info support: create rich lore or save tokens on your character card
  • OpenRouter connection for various APIs (Claude, GPT-4/3.5 and more)
  • Oobabooga's TextGen WebUI API connection
  • AI Horde connection
  • Prompt generation formatting tweaking

Extensions

SillyTavern has extensibility support, with some additional AI modules hosted via SillyTavern Extras API

  • Author's Note / Character Bias
  • Character emotional expressions (sprites)
  • Auto-Summary of the chat history
  • Sending images to chat, and the AI interpreting the content
  • Stable Diffusion image generation (5 chat-related presets plus 'free mode')
  • Text-to-speech for AI response messages (via ElevenLabs, Silero, or the OS's System TTS)

A full list of included extensions and tutorials on how to use them can be found in the Docs.

UI/CSS/Quality of Life tweaks by RossAscends

  • Mobile UI optimized for iOS, and supports saving a shortcut to the home screen and opening in fullscreen mode.

  • HotKeys

    • Up = Edit last message in chat
    • Ctrl+Up = Edit last USER message in chat
    • Left = swipe left
    • Right = swipe right (NOTE: swipe hotkeys are disabled when the chat bar has something typed into it)
    • Ctrl+Left = view locally stored variables (in the browser console window)
    • Enter (with chat bar selected) = send your message to AI
    • Ctrl+Enter = Regenerate the last AI response
  • User Name Changes and Character Deletion no longer force the page to refresh.

  • Toggle option to automatically connect to API on page load.

  • Toggle option to automatically load the most recently viewed character on page load.

  • Better Token Counter - works on unsaved characters, and shows both permanent and temporary tokens.

  • Better Past Chats View

    • New Chat filenames are saved in a readable format of "(character) - (when it was created)"
    • Chat preview increased from 40 characters to 300.
    • Multiple options for characters list sorting (by name, creation date, chat sizes).
  • By default the left and right settings panel will close when you click away from it.

  • Clicking the Lock on the nav panel will hold the panel open, and this setting be remembered across sessions.

  • Nav panel status of open or closed will also be saved across sessions.

  • Customizable chat UI:

    • Play a sound when a new message arrives
    • Switch between round or rectangle avatar styles
    • Have a wider chat window on the desktop
    • Optional semi-transparent glass-like panels
    • Customizable page colors for 'main text', 'quoted text', and 'italics text'.
    • Customizable UI background color and blur amount

Installation

!WARNING]
* DO NOT INSTALL INTO ANY WINDOWS CONTROLLED FOLDER (Program Files, System32, etc).
* DO NOT RUN START.BAT WITH ADMIN PERMISSIONS
* INSTALLATION ON WINDOWS 7 IS IMPOSSIBLE AS IT CAN NOT RUN NODEJS 18.16

🪟 Windows

Installing via Git

  1. Install NodeJS (latest LTS version is recommended)
  2. Install Git for Windows
  3. Open Windows Explorer (Win+E)
  4. Browse to or Create a folder that is not controlled or monitored by Windows. (ex: C:\MySpecialFolder)
  5. Open a Command Prompt inside that folder by clicking in the 'Address Bar' at the top, typing cmd, and pressing Enter.
  6. Once the black box (Command Prompt) pops up, type ONE of the following into it and press Enter:
  • for Release Branch: git clone https://github.com/SillyTavern/SillyTavern -b release

  • for Staging Branch: git clone https://github.com/SillyTavern/SillyTavern -b staging

    1. Once everything is cloned, double-click Start.bat to make NodeJS install its requirements.
    2. The server will then start, and SillyTavern will pop up in your browser.

Installing via SillyTavern Launcher

  1. On your keyboard: press WINDOWS + R to open Run dialog box. Then, run the following command to install git:
cmd /c winget install -e --id Git.Git
  1. On your keyboard: press WINDOWS + E to open File Explorer, then navigate to the folder where you want to install the launcher. Once in the desired folder, type cmd into the address bar and press enter. Then, run the following command:
git clone https://github.com/SillyTavern/SillyTavern-Launcher.git && cd SillyTavern-Launcher && start installer.bat

Installing via GitHub Desktop

(This allows git usage only in GitHub Desktop, if you want to use git on the command line too, you also need to install Git for Windows)

  1. Install NodeJS (latest LTS version is recommended)
  2. Install GitHub Desktop
  3. After installing GitHub Desktop, click on Clone a repository from the internet.... (Note: You do NOT need to create a GitHub account for this step)
  4. On the menu, click the URL tab, enter this URL https://github.com/SillyTavern/SillyTavern, and click Clone. You can change the Local path to change where SillyTavern is going to be downloaded.
  5. To open SillyTavern, use Windows Explorer to browse into the folder where you cloned the repository. By default, the repository will be cloned here: C:\Users\[Your Windows Username]\Documents\GitHub\SillyTavern
  6. Double-click on the start.bat file. (Note: the .bat part of the file name might be hidden by your OS, in that case, it will look like a file called "Start". This is what you double-click to run SillyTavern)
  7. After double-clicking, a large black command console window should open and SillyTavern will begin to install what it needs to operate.
  8. After the installation process, if everything is working, the command console window should look like this and a SillyTavern tab should be open in your browser:
  9. Connect to any of the supported APIs and start chatting!

🐧 Linux & 🍎 MacOS

For MacOS / Linux all of these will be done in a Terminal.

  1. Install git and nodeJS (the method for doing this will vary depending on your OS)
  2. Clone the repo
  • for Release Branch: git clone https://github.com/SillyTavern/SillyTavern -b release
  • for Staging Branch: git clone https://github.com/SillyTavern/SillyTavern -b staging
  1. cd SillyTavern to navigate into the install folder.
  2. Run the start.sh script with one of these commands:
  • ./start.sh
  • bash start.sh

Installing via SillyTavern Launcher

For Linux users

  1. Open your favorite terminal and install git
  2. Git clone the Sillytavern-Launcher with:
git clone https://github.com/SillyTavern/SillyTavern-Launcher.git && cd SillyTavern-Launcher
  1. Start the installer.sh with:
chmod +x install.sh && ./install.sh
  1. After installation start the launcher.sh with:
chmod +x launcher.sh && ./launcher.sh

For Mac users

  1. Open a terminal and install brew with:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  1. Install git with:
brew install git
  1. Git clone the Sillytavern-Launcher with:
git clone https://github.com/SillyTavern/SillyTavern-Launcher.git && cd SillyTavern-Launcher
  1. Start the installer.sh with:
chmod +x install.sh && ./install.sh
  1. After installation start the launcher.sh with:
chmod +x launcher.sh && ./launcher.sh

🐋 Installing via Docker

These instructions assume you have installed Docker, are able to access your command line for the installation of containers, and familiar with their general operation.

Building the image yourself

We have a comprehensive guide on using SillyTavern in Docker here which covers installations on Windows, macOS and Linux! Give it a read if you wish to build the image yourself.

Using the GitHub Container Registry (easiest)

You will need two mandatory directory mappings and a port mapping to allow SillyTavern to function. In the command, replace your selections in the following places:

Container Variables

Volume Mappings
  • [config] - The directory where SillyTavern configuration files will be stored on your host machine
  • [data] - The directory where SillyTavern user data (including characters) will be stored on your host machine
  • [plugins] - (optional) The directory where SillyTavern server plugins will be stored on your host machine
Port Mappings
  • [PublicPort] - The port to expose the traffic on. This is mandatory, as you will be accessing the instance from outside of its virtual machine container. DO NOT expose this to the internet without implementing a separate service for security.
Additional Settings
  • [TimeZone] - The timezone your instance should use. This is useful for making logs match your local time for easier troubleshooting. Use your TZ Identifier. (https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
  • [DockerNet] - The docker network that the container should be created with a connection to. If you don't know what it is, see the official Docker documentation.
  • [version] - On the right-hand side of this GitHub page, you'll see "Packages". Select the "sillytavern" package and you'll see the image versions. The image tag "latest" will keep you up-to-date with the current release. You can also utilize "staging" and "release" tags that point to the nightly images of the respective branches, but this may not be appropriate, if you are utilizing extensions that could be broken, and may need time to update.

Install command

  1. Open your Command Line
  2. Run the following command

docker create --name='sillytavern' --net='[DockerNet]' -e TZ="[TimeZone]" -p '8000:8000/tcp' -v '[plugins]':'/home/node/app/plugins':'rw' -v '[config]':'/home/node/app/config':'rw' -v '[data]':'/home/node/app/data':'rw' 'ghcr.io/sillytavern/sillytavern:[version]'

Note that 8000 is a default listening port. Don't forget to use an appropriate port if you change it in the config.

📱 Mobile - Installing via termux

!NOTE]
**SillyTavern can be run natively on Android phones using Termux. Please refer to this guide by ArroganceComplex#2659:**
* <https://rentry.org/STAI-Termux>

API keys management

SillyTavern saves your API keys to a secrets.json file in the user data directory (/data/default-user/secrets.json is the default path).

By default, they will not be exposed to a frontend after you enter them and reload the page.

In order to enable viewing your keys by clicking a button in the API block:

  1. Set the value of allowKeysExposure to true in config.yaml file.
  2. Restart the SillyTavern server.

Remote connections

Most often this is for people who want to use SillyTavern on their mobile phones while their PC runs the ST server on the same wifi network.

However, it can be used to allow remote connections from anywhere as well.

IMPORTANT: Refer to the official guide if you want to configure SillyTavern user accounts with (optional) password protection: Users.

1. Managing whitelisted IPs

  • Create a new text file inside your SillyTavern base install folder called whitelist.txt.
  • Open the file in a text editor, and add a list of IPs you want to be allowed to connect.

Both individual IPs and wildcard IP ranges are accepted. Examples:

192.168.0.1
192.168.0.20

or

192.168.0.*

(the above wildcard IP range will allow any device on the local network to connect)

CIDR masks are also accepted (eg. 10.0.0.0/24).

  • Save the whitelist.txt file.
  • Restart your ST server.

Now devices which have the IP specified in the file will be able to connect.

Note: config.yaml also has a whitelist array, which you can use in the same way, but this array will be ignored if whitelist.txt exists.

2. Getting the IP for the ST host machine

After the whitelist has been setup, you'll need the IP of the ST-hosting device.

If the ST-hosting device is on the same wifi network, you will use the ST-host's internal wifi IP:

  • For Windows: windows button > type cmd.exe in the search bar > type ipconfig in the console, hit Enter > look for IPv4 listing.

If you (or someone else) want to connect to your hosted ST while not being on the same network, you will need the public IP of your ST-hosting device.

  • While using the ST-hosting device, access this page and look for IPv4. This is what you would use to connect from the remote device.

3. Connect the remote device to the ST host machine

Whatever IP you ended up with for your situation, you will put that IP address and port number into the remote device's web browser.

A typical address for an ST host on the same wifi network would look like this:

http://192.168.0.5:8000

Use http:// NOT https://

Opening your ST to all IPs

We do not recommend doing this, but you can open config.yaml and change whitelistMode to false.

You must remove (or rename) whitelist.txt in the SillyTavern base install folder if it exists.

This is usually an insecure practice, so we require you to set a username and password when you do this.

The username and password are set in config.yaml.

After restarting your ST server, any device will be able to connect to it, regardless of their IP as long as they know the username and password.

Still Unable To Connect?

  • Create an inbound/outbound firewall rule for the port found in config.yaml. Do NOT mistake this for port-forwarding on your router, otherwise, someone could find your chat logs and that's a big no-no.
  • Enable the Private Network profile type in Settings > Network and Internet > Ethernet. This is VERY important for Windows 11, otherwise, you would be unable to connect even with the aforementioned firewall rules.

Performance issues?

Try enabling the No Blur Effect (Fast UI) mode on the User settings panel.

I like your project! How do I contribute?

DO's

  1. Send pull requests
  2. Send feature suggestions and issue reports using established templates
  3. Read the readme file and built-in documentation before asking anything

DONT's

  1. Offer monetary donations
  2. Send bug reports without providing any context
  3. Ask the questions that were already answered numerous times

Where can I find the old backgrounds?

We're moving to a 100% original content only policy, so old background images have been removed from this repository.

You can find them archived here:

https://files.catbox.moe/1xevnc.zip

License and credits

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.