# KoboldAI-Client: legacy local AI writing frontend

> KoboldAI-Client is a Python and browser-based frontend for local and remote AI models, aimed at interactive fiction, novels, and role-playing. The README says it is legacy software that will not run modern models and directs new users to KoboldCpp.

**KoboldAI/KoboldAI-Client** — For GGUF support, see KoboldCPP: https://github.com/LostRuins/koboldcpp

- Repository: https://github.com/KoboldAI/KoboldAI-Client
- Website: https://koboldai.com
- Stars: 3,958 · Forks: 860
- Language: Python
- License: AGPL-3.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/koboldai-koboldai-client

## Why the legacy KoboldAI-Client exists

KoboldAI-Client provides a browser interface for AI-assisted stories, text adventures, and conversations. Its users include writers who want a controllable co-author, role-players who want direct control over actions and characters, and people who already operate a local or remote inference service. The repository contains Google Colab notebooks, shell scripts, Python server files, and configuration templates, so its intended operating model extends beyond a static chat page.

The project separates regular writing, Adventure mode, and Chatbot mode because those modes require models trained for different interaction conventions. A Novel-oriented model is intended for prose that does not assume a second-person player. An Adventure-oriented model responds to actions such as "You take the sword." A chatbot model expects alternating speaker turns. Generic models can be used across several cases, but the README warns that output quality depends on the selected model or service.

KoboldAI-Client is therefore a frontend and orchestration layer, not a claim that one model supports every mode equally well. It includes Memory, Author's Note, World Info, story saving and loading, adjustable generation settings, and formatting options. Existing AI Dungeon adventures can be imported, while Adventure mode provides a separate interaction style for interactive fiction.

The repository warning defines a firm boundary for adoption. The README calls this old legacy software, says it is not maintained, and states that it will not run modern models. It directs readers seeking current model support to KoboldCpp.

## KoboldAI-Client request and model architecture

The repository layout indicates that KoboldAI-Client combines a Python application server with assets served to a browser. The dependency file lists Flask, Flask-SocketIO, Werkzeug, python-socketio, and eventlet, while top-level Python modules include aiserver.py, gensettings.py, structures.py, utils.py, fileops.py, and warpers.py. This is a web application with server-side generation logic and browser communication, rather than a model running entirely inside the page.

Generation settings are handled through Python modules and JSON-oriented configuration files. The repository includes customsettings_template.json, models/, templates/, stories/, static/, maps/, and user-related script directories. That separation suggests that generation configuration, model assets, presentation, and saved narrative content are managed independently. The README documents settings that switch the interface among generic writing, Adventure, and Chatbot modes. Those modes alter prompt construction and expected user input rather than making the underlying model itself an adventure model or a novel model.

The dependency set also contains transformers, huggingface_hub, accelerate, safetensors, sentencepiece, and a bounded Torch requirement of `torch >= 1.9, < 1.13`. The repository includes separate CPU-oriented, ROCm, CUDA, and TPU-related scripts and backend code. This is a broad collection of execution paths, but the presence of files for several backends does not mean every model works across all of them. The pinned package versions and old Torch ceiling place the project in an earlier Python ML environment.

External inference is part of the design. The README describes connecting to services such as OpenAI or Inferkit when an API key is available, while also describing local execution and Google Colab deployment. The frontend therefore does not require every generation request to use the bundled Python inference stack. That flexibility helps an existing setup, although compatibility depends on the selected backend and model rather than on the browser interface alone.

## Novel, Adventure, and Chatbot input contracts

The most consequential project-specific mechanism is the input format attached to each mode. In regular writing, the README recommends a Novel model. The generated text is treated as prose, and the user takes turns with the model rather than controlling an implied player character. Large generic models may also work if the introduction provides enough context, although a purpose-trained model can reduce corrective work.

Adventure mode expects a complete sentence that identifies the actor. The documentation uses "You take the sword" rather than the terse "take the sword" form associated with AI Dungeon. Dialogue should also identify the speaker, such as `You say "We should probably gather some supplies first"`. The README says that explicit actor names produce more reliable character handling. For multiplayer-style play, it recommends keeping `You` as the main character and referring to other characters by name.

That contract has a direct model requirement. Adventure models assume a `You` character, while Novel models are described as lacking that assumption. Passing adventure-style commands to a Novel model can therefore be the wrong interaction model. This is not a small prompt preference. It changes who is expected to act and how the continuation should be framed.

Chatbot mode applies another transformation. According to the README, it adds the user's name to the beginning of sentences and tries to prevent the model from speaking as that user. An opening is formatted with both participants:

```plaintext
Bot : Hey!
You : Hey Boyname, how have you been?
Bot : Been good! How about you?
You : Been great to, excited to try out KoboldAI
```

The initial turns may still confuse speakers. Models can swap names, particularly when one configured name is more familiar to the model. Novel and Adventure models are not recommended for chatbot mode because they can leave the conversation format, while Generic and dedicated chatbot models are the documented choices.

## Legacy deployment paths and first use

The repository contains platform launchers for Windows, Linux, ROCm, CUDA, standalone Docker, and Google Colab. It also contains `install_requirements.sh`, `install_requirements.bat`, `play.sh`, `play.bat`, `commandline.sh`, and related backend files. The README does not give the syntax for these scripts, so it would be unsafe to invent command-line arguments or claim a particular address at which the interface will appear.

For the shortest documented path, the README says to use its Google Colab edition. Open the linked TPU or GPU notebook from the README, follow that notebook's instructions, and select one of the models listed in the notebook. The editions run on Google's servers and differ in hardware and available models. A reader who cannot access one edition may still be able to use the other, according to the README.

A first Colab session can be used as follows. Open the chosen edition, run the notebook cells in their documented order, wait for the model to load, and open the generated application interface. The models available in each notebook are an important part of setup because this client cannot run modern models. The README does not provide the exact cell text or generated address, so those details must come from the notebook itself.

Story persistence is also documented. Saving a story through the Colab edition can upload the save to Google Drive. Alternatively, the reader can download the save so it is not stored there. Users who care about retention should make that choice before treating a generated story as a durable record.

## Dependency age and upgrade constraints

The dependency set is the strongest warning for engineers. `requirements.txt` pins `transformers==4.24.0`, `huggingface_hub==0.12.1`, `Flask==2.2.3`, `Flask-SocketIO==5.3.2`, `Werkzeug==2.3.7`, `python-socketio==5.7.2`, and `eventlet==0.33.3`. It also constrains Torch to `torch >= 1.9, < 1.13`. Modernizing those packages is not a routine version bump because server libraries, inference libraries, Python compatibility, and accelerator builds are coupled.

The README says that the legacy product is not maintained. Its listed release history adds another operational signal: versioned releases shown include 1.19.2 from 2022-11-20 and 1.19.1 from 2022-10-12, while a 2024-08-21 entry is named `dummy` and points readers toward a newer KoboldAI product. The repository being unarchived should not be confused with a maintained release line. For production planning, the README's maintenance warning and the absence of recent versioned releases carry more weight than the `main` branch label alone.

The AGPL-3.0 license also affects adoption review. Code covered by AGPL-3.0 carries source-availability and license obligations when it is distributed or used in covered network-service scenarios. The repository README does not document an organization-specific compliance process, so no legal conclusion should be drawn. Teams planning to modify, host, or embed the application should review `LICENSE.md` and determine whether their distribution model triggers source-offer obligations.

## KoboldAI-Client versus KoboldCpp

The real alternative named by the repository is KoboldCpp. The difference begins with model generation. The repository description says, "For GGUF support, see KoboldCPP," while the README calls KoboldCpp the destination for users who want the latest models and explicitly warns that the old software will not run modern models.

KoboldAI-Client organizes story-oriented controls in the browser, including Memory, Author's Note, World Info, saves, formatting, Adventure mode, Chatbot mode, and AI Dungeon adventure imports. Its Python dependency list and backend scripts reflect an older Transformers-based application environment. KoboldCpp is presented as the current direction for current models, including the GGUF path that this repository does not provide.

That distinction makes the choice straightforward for many readers. Choose this repository when reproducing a legacy workflow, using a compatible model or remote API, or working with its existing story-writing interface. Follow the README's pointer to KoboldCpp when the primary requirement is modern GGUF model support. The README does not provide a feature-by-feature comparison or installation details for KoboldCpp, so claims about its interface, hardware coverage, or performance would go beyond its documentation.

## Failure modes when using the old client

The clearest failure mode is selecting an unsupported model. The README's opening warning states that this software will not run modern models. An engineer could still treat the repository as a current inference client based on its unarchived status and recent push, but that interpretation would conflict with the project's own migration notice.

Mode mismatch is the second failure mode. Adventure commands delivered to a Novel model do not match the interaction assumptions of that model. Chatbot mode combined with Novel or Adventure models can lose the required speaker format. These are not server outages. They are interface and training-contract conflicts. Choosing a model described for the intended mode is more important than changing generation sliders after a bad response.

Backend compatibility is another constraint. The Torch ceiling, pinned Transformers release, CUDA and ROCm scripts, TPU backend, and remote API paths are separate compatibility surfaces. The repository proves that these paths exist, but it does not confirm that they are interchangeable for one model. A deployment attempt that ignores backend format, accelerator library, or Python version can fail before the browser interface becomes relevant.

The application is also a poor fit when GGUF is mandatory. In that case, the limitation is architectural rather than a missing feature toggle. The repository sends users to a different project for that format. Legacy model research, existing story workflows, and interface-focused evaluation are more defensible uses.

## Conclusion

KoboldAI-Client may suit someone reproducing an older Python-based writing workflow or working with a compatible legacy model and API service. It is a poor choice for a new deployment that needs modern GGUF models. Before adoption, verify the exact model format, Python and Torch compatibility, backend availability, and whether the maintenance status fits your operational requirements.

## FAQ

### Can KoboldAI-Client run modern or GGUF models?

No. The README states that this legacy software will not run modern models. For GGUF support, the repository description directs users to KoboldCpp.

### Which KoboldAI-Client mode should I use for AI-assisted novel writing?

The README recommends regular mode with a model optimized for Novels. It says these models focus on novel-like writing and generally work better for that purpose than Adventure or Generic models.

### How should I enter actions in KoboldAI Adventure mode?

Write complete sentences that identify the actor, such as "You take the sword." The README says Adventure models assume a `You` character, so Novel models are a poor match for this mode.

## Sources

- [KoboldAI/KoboldAI-Client on GitHub](https://github.com/KoboldAI/KoboldAI-Client)
- [License: AGPL-3.0](https://github.com/KoboldAI/KoboldAI-Client/blob/main/LICENSE)
- [Project website](https://koboldai.com)
- [README](https://github.com/KoboldAI/KoboldAI-Client/blob/main/README.md)
- [Releases](https://github.com/KoboldAI/KoboldAI-Client/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/koboldai-koboldai-client