Getting started with Kyalulu

What you need#

Kyalulu manages characters, conversations, and memory. Models generate text through a separate inference engine. Start with Mock Echo, which needs no model, to check the interface and persistence. Connecting an engine afterward makes it easier to distinguish setup problems from model problems.

• Python 3.11 or later and uv 0.12 or later.
• Node.js 20 or later and pnpm 10 or later. The public workspace specifies pnpm 10.30.1.
• Git and network access to download dependencies.

Get the source and configure the environment#

The commands below use PowerShell on Windows. Choose any suitable destination, then run all subsequent commands from the cloned repository root. A new directory helps avoid overwriting an existing setup.

git clone https://github.com/ELRdn/Kyalulu.git
cd Kyalulu
Copy-Item .env.example .env

On macOS or Linux, replace the last line with cp .env.example .env. Open the new .env in a text editor and initially clear these external connection settings and generic aliases. The public example contains specific endpoints and a model name; they may not match your setup.

OPENAI_COMPATIBLE_URL=
OPENAI_COMPATIBLE_API_KEY=
LLM_BASE_URL=
LLM_API_KEY=
LLM_MODEL=

Sending a message through Mock Echo requires neither an external API key nor a model download. You can leave the default local URLs for Ollama and LM Studio in place. Restart the API after changing connection settings later. Do not share a .env containing keys. Read Data and privacy before choosing an endpoint.

Install workspace dependencies#

uv sync --frozen --all-packages --no-install-workspace
pnpm install --frozen-lockfile

The root pyproject.toml declares runtime as a uv workspace member. --all-packages includes the runtime dependencies, while --no-install-workspace skips installation of the workspace packages themselves, including the root package. The startup command below explicitly locates the API source. The virtual environment lives in .venv at the repository root.

--frozen uses the public lockfile. If installation fails, check your Python and uv versions, the source and lockfile you downloaded, and network access first. For a Windows uv cache permission error, set $env:UV_CACHE_DIR = "$PWD/.uv-cache" in that shell and retry. The dev and remote extras are not required for the initial chat setup.

Run the API and web app in separate terminals#

Terminal A: API

.venv/Scripts/python.exe -m uvicorn python.api.main:app --app-dir runtime --host 127.0.0.1 --port 8000

On macOS or Linux, replace .venv/Scripts/python.exe with .venv/bin/python. --app-dir runtime makes python.api.main importable. Leave this terminal open. Run only one API process against the same data directory.

Terminal B: web app

Open another terminal, navigate to the same repository root, and run:

pnpm dev

Open http://localhost:5173 in your browser. The web app proxies /api requests to the API on port 8000. If the page loads but cannot connect, inspect errors in Terminal A. If a port is occupied, check the existing process and avoid starting a duplicate. When using a custom web port, Hub fetching also requires the exact web origin in the API's KYALULU_TRUSTED_ORIGINS setting.

Check your first conversation with Mock Echo#

1. Open a new conversation and explicitly select Mock Echo as the model.
2. Send “Hello. This is a setup check.”
3. Check that a dummy reply reflecting your input appears and the history is saved.
4. Navigate away and reopen the conversation; reload if needed to check persistence.

The expected result is a working connection between the interface, API, and storage, with a reply corresponding to your input. Mock output cannot establish character quality or real-model speed. If the model list is empty, inspect API startup and YAML registry synchronization. A listed model does not necessarily mean it is ready to generate.

Use Status for connection diagnostics. The API's GET /api/models and GET /api/providers/health endpoints can also help identify the problem. Once this stage works reliably, continue to Importing and editing characters.

Connect an engine and optionally use Desktop#

When you are ready to use actual generation, choose LE, LM Studio, Ollama, or an OpenAI-compatible API. For a local model, prepare and start it in the engine, check its model ID and connection status, then select it in Kyalulu. LE connects to 127.0.0.1:8130 by default. Its served models appear as le:<model ID>, so an additional YAML file is usually unnecessary. See Models and connections for configuration details.

To use the Desktop development shell, run this in another terminal after installing dependencies:

pnpm dev:desktop

Desktop uses an existing API when available; otherwise it supervises startup using the checkout's Python environment. Automatic LE startup needs a separately specified binary. Public materials report incomplete validation of a distribution bundling Python and LE, so this command should not be treated as a finished installer. Continue with Memory or Personas and worlds, or return to the documentation index.