First run

Two commands. The first configures her, the second starts her.

kotoba setup
kotoba serve

You can skip kotoba setup if you like: kotoba and kotoba --once "…" both run it themselves when no key is configured, and so does the browser — opening /app on an unconfigured install redirects to /setup, which asks the same questions with the same answers landing in the same places.

kotoba setup, question by question

Six questions and a seventh you can skip. Every answer is a real setting, not a form field. Ctrl+C stops it anywhere, and nothing is written until you answer.

1. Which brain. OpenAI or xAI (Grok). Enter takes OpenAI, which is the default. The list shows which prefix each provider's keys start with.

2. Which model. Cheapest first, each row saying what it costs relative to the cheapest and how much conversation it can hold. OpenAI's list opens with gpt-5.6-luna; xAI's opens with grok-4.3. The last row lets you type any other id belonging to that provider — she takes it, and says plainly that she has not checked it.

The model is asked before the key on purpose. The key is proved with a real sixteen-token call to the model you just picked, so a key that cannot reach that model fails here, where you can still paste another one, rather than on your first real question.

3. The key. Not echoed where the terminal can hide it; where it cannot, she says so instead of promising something she cannot deliver. The key is verified against the provider before it is stored, and it is stored encrypted in the database — never in a plaintext file. A key that already exists can be kept by pressing Enter.

A wrong key is not a dead end. Three attempts, and every failure gets its own sentence: a key the provider does not know, an account with no credit, no network at all, a model that provider does not serve, and a key belonging to the other provider each read differently, and each names the page where a key is made.

4. Your name. Stored as your user profile name; she uses it in every conversation. Enter skips.

5. Her name. Enter keeps "Kotoba". She reads the row back before saying she will answer to it, so a name the database refuses does not get confirmed.

6. Language. auto, English, Spanish, Japanese, or any two- or three-letter code typed in. This sets two things: how she replies, and how she hears you — a pinned language pins transcription too, so a short sentence is not detected as the wrong language.

7. A voice (optional). An ElevenLabs key, checked against ElevenLabs before it is stored. Enter skips it, and skipping is a real choice: she reads and writes perfectly well without it, and kotoba setup asks again any time you run it. If the voice extra is not installed she keeps a good key for later and names pip install "kotoba-companion[voice]".

The closing screen names whatever you skipped and how to get it back.

What it writes, and where

Measured on a fresh run:

Nothing there is a secret in the clear: a stored key reads as v1: followed by ciphertext. The personality files are copied once and never overwritten afterwards, because editing them is the point.

KOTOBA_HOME moves that whole directory. From a clone, the database and the personality file belong to the checkout instead — see Installing from a clone.

kotoba serve

kotoba serve                 # backend on 8000, web UI on 3000
kotoba serve --open          # and open your browser once it answers
kotoba serve --port 8080     # move the backend
kotoba serve --web-port 3100 # move the web UI

It prints the addresses it is using. On a plain install there is nothing to compile and no second server, so the backend serves the app from its own port:

[api] http://127.0.0.1:8000/health
[web] http://127.0.0.1:8000/app  (built in, 69 files, kotoba 0.10.0)

The file count is whatever that build contains, so yours may differ.

In a clone with Node it starts the Next development server instead, because your edits have to show, and the web address is http://127.0.0.1:3000. Either way / redirects to /app.

One Ctrl+C stops everything it started, and if one child dies the other is brought down with it. Each child runs in its own process group, because npm run dev forks a worker that outlives npm and signalling npm alone would leave that worker holding port 3000.

--open waits for something to accept a connection on the port the UI will actually answer on — the web port with a dev server, the backend port with the packaged build — and gives up after 90 seconds with a sentence rather than opening a window on a port that never came up.

Talking to her

Open the address it printed. / sends you to /app.

• Type. Text works with only the model key configured.
• Press Call and allow the microphone. This needs the ElevenLabs key. There is no agent to register anywhere in the default local voice mode.

If you set her up from the terminal she has no face yet, so the first visit to /app sends you once to the face step of the setup screen, where you can fetch Live2D's free sample or drop in a .zip. That offer is made once per browser; afterwards the way back is Settings, and the avatar area names the folder to unpack a model into.

The terminal instead

kotoba                       # her interactive terminal
kotoba --once "what can you do?"

Same engine, same database, same memory and same files as the browser. Ask her something in one and she knows it in the other.

Next: kotoba doctor.